Module: Java::OrgTmapiCore::TopicMap

Extends:
Superiseable
Includes:
RTM::TopicMap
Defined in:
rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb,
rtm-javatmapi/lib/rtm/javatmapi/aliases.rb

Overview

Copyright: Copyright 2009 Topic Maps Lab, University of Leipzig. License: Apache License, Version 2.0

Constant Summary

URI_PATTERN = 
":"

Instance Attribute Summary

Instance Method Summary

Methods included from Superiseable

method_added, register_java_implementation, superised, superising

Instance Attribute Details

- (Object) prefixes (readonly)

hash 



11
12
13
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 11

def prefixes
  @prefixes ||= {}
end

Instance Method Details

- (Object) add_prefix(identifier, reference)

Adds the identifier (key) and reference (value) to the prefixes-Hash and returns all prefixes. Qnames consisting of “identifier:localpart” will be converted to “referencelocalpart”.

Examples:

add_prefix("tml", "http://www.topicmapslab.de/")

Parameters:

Returns:

  • void 



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 33

def add_prefix(identifier, reference)
  unless identifier.is_a?(String) && reference.is_a?(String)
    raise("add_prefix: identifier and reference must be Strings")
    # TODO @raise in yardoc
  end
  if identifier.empty? || reference.empty?
    raise("add_prefix: identifier or reference may not be empty")
  end
  if (identifier == "sl") || (identifier == "si") || (identifier == "ii")
    raise("add_prefix: identifier 'sl', 'si' or 'ii' not allowed for prefixes")
  end
  unless reference.include?(URI_PATTERN)
    raise("add_prefix: reference must be absulute")
  end
  # prefix xsd is allowed
  prefixes[identifier]= reference
  prefixes
end

- (Object) associations(type = :any) Also known as: a

Returns all associations contained in this topic map.

The optional argument specifies the type the associations should have, i.e. all instances of the specified type are returned. Type may be a topic reference.

The return value may be empty.

:call-seq: 

  associations -> Set of Associations
  associations(type) -> Array of Associations



276
277
278
279
280
281
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 276

def associations(type = :any)
  return getAssociations if type == :any
  raise("associations(type): type must be a topic reference.") unless (type.is_a?(RTM::Topic) || type.is_a?(RTM::Locator) || type.is_a?(String))
  type = self.get(type) unless type.is_a?(RTM::Topic)
  return type ? type_instance_index.getAssociations(type).to_a : []
end

- (Object) base_iri Also known as: base_locator

returns the base iri of this topic map 



14
15
16
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 14

def base_iri
  getLocator.reference
end

- (Object) children Also known as: reverse_parent

Returns all Associations and Topics contained in this TopicMap.

:call-seq: 

  children -> Array of Associations and/or Topics



125
126
127
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 125

def children
  getAssociations.to_a + getTopics.to_a
end

- (Object) construct_by_id(id) 



548
549
550
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 548

def construct_by_id(id)
  getConstructById(id)
end

- (Object) create_association(type, *args) {|assoc| ... }

Creates an Association in this TopicMap.

Type specifies the Association type.

If given, scope specifies the association scope; else the Association is in the unconstrained scope. Scope must be an Array of identifiers.

The last argument - a roles-Hash - is optional. If given, all specified roles will be created additionally. A role is specified by the role type: the key in the Hash and the role player: the corresponding value in the Hash.

Each identifier (type, scope-identifier, roletype-identifier and player-identifier) may be a topic reference.

:call-seq: 

  create_association(type) -> Association
  create_association(type, scope-Array) -> Association
  create_association(type, roletype-identifier => player-identifier, ...) -> Association
  create_association(type, scope-Array, roletype-identifier => player-identifier, ...) -> Association

Yields:

  • (assoc) 


153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 153

def create_association(type, *args)
  roles = {}
  if args.size == 0
    # no args -> no scope and no roles given
    scope = :ucs
  elsif args.size == 1
    # args may be an array (scope) or hash (roles)
    argument = args[0]
    if argument.is_a?(Array)
      scope = argument
    elsif argument.is_a?(Hash)
      scope = :ucs
      roles = argument
    else
      raise("create_association: arguments after type may be an Array or Hash")
    end
  else
    # several arguments after type
    argument1 = args[0]
    argument2 = args[1]
    if argument1.is_a?(Array)
      scope = argument1
      roles = argument2
    elsif argument1.is_a?(Hash)
      scope = :ucs
      roles = argument1
    else
      raise("create_association: arguments after type may be an Array or Hash")
    end
  end
  raise("create_association: type must be a Topic or Topic-Reference") unless type.is_a?(Java::OrgTmapiCore::Topic) || type.is_a?(String) || type.is_a?(Java::OrgTmapiCore::Locator)
  if scope == :ucs
    assoc = createAssociation(get!(type),[].to_java(Java::OrgTmapiCore::Topic))
  else
    raise("create_association: scope must be an Array") unless scope.is_a?(Array)
    assoc = scope.empty? ? createAssociation(get!(type),[].to_java(Java::OrgTmapiCore::Topic)) : createAssociation(get!(type),get!(scope))
  end 
  raise("create_association: roles must be a Hash") unless roles.is_a?(Hash)
  roles.each do |k,v|
    if v.is_a?(Array)
      v.each{|player| assoc.create_role(k,player)}
    else
      assoc.create_role(k,v)
    end
  end
  yield assoc if block_given?
  return assoc
end

- (Object) create_locator(identifier, to_raise = org.tmapi.core.MalformedIRIException)

Returns a Locator representing the identifier. Identifier may be a String (IRI).

:call-seq: 

  create_locator(identifier) -> Locator



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 308

def create_locator(identifier, to_raise = org.tmapi.core.MalformedIRIException)
  return identifier if identifier.is_a?(Java::OrgTmapiCore::Locator)
  raise("create_locator: identifier must be a String") unless identifier.is_a?(String)
  qname = check_for_qname(identifier)
  if qname
    identifier = qname
  else
    unless identifier.include?(URI_PATTERN)
      begin
        if self.engine.identifier == :tinytim
          identifier = identifier.gsub(' ','%20')
        end
        identifier = getLocator.resolve(identifier)
      rescue org.tmapi.core.MalformedIRIException => mie
        if to_raise == mie
          raise(mie.message)
        else
          return :fail
        end
      end
      return identifier
    end
  end
  begin
    identifier = createLocator(identifier)
  rescue org.tmapi.core.MalformedIRIException => mie
    if to_raise == mie
      raise(mie.message)
    else
      return :fail
    end
  end
  return identifier
end

- (Object) create_topic_by(identifier)

Assumes identifier is an IRI (Locator or String) or an Array of IRIs. Returns an existing or created Topic or an Array of Topics according to the nature of the IRI.

:call-seq: 

  create_topic_by(identifier) -> Topic
  create_topic_by(identifier-Array) -> Array of Topics



457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 457

def create_topic_by(identifier)
  case identifier
  when Java::OrgTmapiCore::Locator
    return create_topic_by_subject_identifier(identifier)
  when String
    reroute_for_create(identifier)
  when Array
    return identifier.map{|i| create_topic_by(i)}
  else
    return nil
  end
end

- (Object) create_topic_by_item_identifier(identifier)

Assumes identifier is a item identifier (Locator or String) or an Array of item identifiers (Locators and/or Strings). Either returns an existing Topic (or Array of Topics) or creates a/ new Topic instance/s with the specified item identifier/s.

:call-seq: 

  create_topic_by_item_identifier(identifier) -> Topic
  create_topic_by_item_identifier(identifier-Array) -> Array of Topics

If a topic with the specified item identifier exists in the topic map, that topic is returned. If a topic with a subject identifier equals to the specified item identifier exists, the specified item identifier is added to that topic and the topic is returned. If neither a topic with the specified item identifier nor with a subject identifier equals to the subject identifier exists, a topic with the item identifier is created. 



445
446
447
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 445

def create_topic_by_item_identifier(identifier)
  get_stuff(identifier){|x| createTopicByItemIdentifier(x)}
end

- (Object) create_topic_by_subject_identifier(identifier)

Assumes identifier is a subject identifier (Locator or String) or an Array of subject identifiers (Locators and/or Strings). Either returns an existing Topic (or Array of Topics) or creates a/ new Topic instance/s with the specified subject identifier/s.

:call-seq: 

  create_topic_by_subject_identifier(identifier) -> Topic
  create_topic_by_subject_identifier(identifier-Array) -> Array of Topics

If a topic with the specified subject identifier exists in the topic map, that topic is returned. If a topic with an item identifier equals to the specified subject identifier exists, the specified subject identifier is added to that topic and the topic is returned. If neither a topic with the specified subject identifier nor with an item identifier equals to the subject identifier exists, a topic with the subject identifier is created. 



411
412
413
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 411

def create_topic_by_subject_identifier(identifier)
  get_stuff(identifier){|x| createTopicBySubjectIdentifier(x)}
end

- (Object) create_topic_by_subject_locator(identifier)

Assumes identifier is a subject locator (Locator or String) or an Array of subject locators (Locators and/or Strings). Either returns an existing Topic (or Array of Topics) or creates a/ new Topic instance/s with the specified subject locators/s.

:call-seq: 

  create_topic_by_subject_locator(identifier) -> Topic
  create_topic_by_subject_locator(identifier-Array) -> Array of Topics



425
426
427
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 425

def create_topic_by_subject_locator(identifier)
  get_stuff(identifier){|x| createTopicBySubjectLocator(x)}
end

- (Object) delete_prefix(identifier, reference = :any) Also known as: del_prefix

Deletes a prefix (given the identifier) from the prefixes-Hash and returnes the remaining prefixes.

If reference is given, it must match the value of the identifier (key) in the prefixes-Hash - if not, the prefix is not deleted.

The result may be empty.

:call-seq: 

  delete_prefix(identifier) -> Hash
  delete_prefix(identifier,reference) -> Hash



65
66
67
68
69
70
71
72
73
74
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 65

def delete_prefix(identifier,reference = :any)
  #warn("delete_prefix: identifier not found") unless prefixes.has_key?(identifier)
  #warn("delete_prefix: reference does not match") unless reference == :any || reference == prefixes[identifier]
  if reference == :any
    prefixes.delete(identifier)
  else
    prefixes.delete_if{|k,v| k == identifier && v == reference}
  end
  prefixes
end

- (Object) find_prefix(filter = {})

Returns the prefixes that match the given the identifier and/or reference.

:call-seq: 

  find_prefix -> Hash
  find_prefix({:identifier => String}) -> Hash
  find_prefix({:reference => String}) -> Hash
  find_prefix({:identifier => String, :reference => String}) -> Hash



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 86

def find_prefix(filter = {})
  #TODO Specs
  identifier = filter[:identifier]
  reference = filter[:reference]
  if identifier && reference
    return prefixes.select{|k,v| k == identifier && v == reference}
  end
  if identifier
    return prefixes.select{|k,v| k == identifier}
  elsif reference
    return prefixes.select{|k,v| v == reference} 
  else
    prefixes
  end
end

- (Object) get(identifier) Also known as: topic

If identifier is a Topic, returns this Topic.

If identifier is a Locator, returns the Topic specified by the Locator (as item identifier or subject identifier).

If identifier is a String, returnes the Topic which has this String as subject identifier (by default or if the String starts with “si:”) or as subject locator (if the String starts with a “=” or “sl:”) or as item identifier (if the String starts with a “^” or “ii:”).

Returns an Array of Topics if an Array of identifiers is given according to the rules above.

Given one identifier, if no Topic is found, returns nil.

Given an Array of identifiers, if no Topics are found, returnes an empty Array.

:call-seq: 

  get(identifier) -> Topic or nil
  get(identifier-Array) -> Array of Topics or empty Array



491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 491

def get(identifier)
  self.cached(self, :get, identifier) {
    case identifier
    when nil
      nil
    when Java::OrgTmapiCore::Topic
      identifier
    when Java::OrgTmapiCore::Locator
      if get_construct_by_item_identifier(identifier).is_a?(Java::OrgTmapiCore::Topic)
        get_construct_by_item_identifier(identifier)
      elsif get_topic_by_subject_identifier(identifier)
        get_topic_by_subject_identifier(identifier)
      else
        #return get_topic_by_subject_locator(identifier) if get_topic_by_subject_locator(identifier) #not allowed because Topics with equals si and ii are merged but sl not
        nil
      end
    when String
      reroute_for_get(identifier)
    when Array
      # in: multi array -> out: multi array
      identifier.map{|i| get(i)}
      #when Hash
      #TODO: use case for getting Topics if argument is a hash
    else
      raise("get(#{identifier.inspect}): arguments do not match")
    end
  }
end

- (Object) get!(identifier) Also known as: topic!

Calls get(identifier) and returns the Topic or Array of Topics according to the nature of the identifier (Topic/Topic-References or Array of those types).

Calls create_topic_by(identifier) if a Topic specified by identifier does not exist in the TopicMap. Returns the created and/our found Topic/s.

If identifier is a String, returnes/creates the Topic which has this String as subject identifier (by default or if the String starts with “si:”) or as subject locator (if the String starts with a “=” or “sl:”) or as item identifier (if the String starts with a “^” or “ii:”).

:call-seq: 

  get!(identifier) -> Topic
  get!(identifier-Array) -> Array of Topics



538
539
540
541
542
543
544
545
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 538

def get!(identifier)
  return nil unless identifier
  if identifier.is_a?(Array)
    return identifier.map{|i| get!(i)}
  end
  found = get(identifier)
  return found ? found : create_topic_by(identifier)
end

- (Object) get_construct_by_item_identifier(identifier) Also known as: by_ii

Assumes identifier is an item identifier (Locator or String) or an Array of item identifiers (Locators and/or Strings) and returns a Construct or an Array of Constructs by its/their item identifier/s.

:call-seq: 

  get_construct_by_item_identifier(identifier) -> Construct
  get_construct_by_item_identifier(identifier-Array) -> Array of Constructs



353
354
355
356
357
358
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 353

def get_construct_by_item_identifier(identifier)
  identifier = create_locator(identifier) if identifier.is_a?(String)
  return getConstructByItemIdentifier(identifier) if identifier.is_a?(Java::OrgTmapiCore::Locator)
  return identifier.map{|i| get_topic_by_subject_locator(i)} if identifier.is_a?(Array)
  return nil
end

- (Object) get_topic_by_subject_identifier(identifier) Also known as: by_si

Assumes identifier is a subject identifier (Locator or String) or an Array of subject identifiers (Locators and/or Strings) and returns a Topic or an Array of Topics by its/their subject identifier/s.

:call-seq: 

  get_topic_by_subject_identifier(identifier) -> Topic
  get_topic_by_subject_identifier(identifier-Array) -> Array of Topics



370
371
372
373
374
375
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 370

def get_topic_by_subject_identifier(identifier)
  identifier = create_locator(identifier) if identifier.is_a?(String)
  return getTopicBySubjectIdentifier(identifier) if identifier.is_a?(Java::OrgTmapiCore::Locator)
  return identifier.map{|i| get_topic_by_subject_locator(i)} if identifier.is_a?(Array)
  return nil
end

- (Object) get_topic_by_subject_locator(identifier) Also known as: by_sl

Assumes identifier is a subject locator (Locator or String) or an Array of subject locators (Locators and/or Strings) and returns a Topic or an Array of Topics by its/their subject locator/s.

:call-seq: 

  get_topic_by_subject_locator(identifier) -> Topic
  get_topic_by_subject_locator(identifier-Array) -> Array of Topics



387
388
389
390
391
392
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 387

def get_topic_by_subject_locator(identifier)
  identifier = create_locator(identifier) if identifier.is_a?(String)
  return getTopicBySubjectLocator(identifier) if identifier.is_a?(Java::OrgTmapiCore::Locator)
  return identifier.map{|i| get_topic_by_subject_locator(i)} if identifier.is_a?(Array)
  return nil
end

- (Object) instances(type = :any)

Returns all topics in the topic map that are used as instance in an “type-instance”-relationship.

The optional argument specifies the type the instances should have. Type may be a topic reference. This method equals topics(type).

The result may be empty.

:call-seq: 

  instances -> Array of Topics
  instances(type) -> Array of Topics



247
248
249
250
251
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 247

def instances(type = :any)
  return types.map{|t| t.instances.to_a}.flatten.uniq if type == :any
  type = self.get(type) unless type.is_a?(RTM::Topic)
  return type ? type_instance_index.getTopics(type).to_a : []
end

- (Object) literal_index Also known as: li

Calls TMAPI TopicMap.getIndex which returns the index for the LiteralIndex.

:call-seq: 

  literal_index -> LiteralIndex



219
220
221
222
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 219

def literal_index
  # Equals _index(:LiteralIndex), which doesn't work yet
  getIndex(Java::OrgTmapiIndex::LiteralIndex.java_class)
end

- (Object) names

Returns all names occurring in the topic map 



553
554
555
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 553

def names
  name_types.map{|type| type.typed_names.to_a}.flatten
end

- (Object) occurrences

Returns all occurrences occurring in the topic map 



558
559
560
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 558

def occurrences
  occurrence_types.map{|type| type.typed_occurrences.to_a}.flatten
end

- (Object) parent Also known as: reverse_children

Returns nil.

:call-seq: 

  parent -> nil



115
116
117
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 115

def parent
  getParent
end

- (Object) roles

Returns all roles occurring in the topic map 



563
564
565
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 563

def roles
  role_types.map{|type| type.typed_roles.to_a}.flatten
end

- (Object) scoped_index Also known as: si

Calls TMAPI TopicMap.getIndex which returns the index for the ScopedIndex.

:call-seq: 

  scoped_index -> ScopedIndex



230
231
232
233
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 230

def scoped_index
  # Equals _index(:ScopedIndex), which doesn't work yet
  getIndex(Java::OrgTmapiIndex::ScopedIndex.java_class)
end

- (Object) topics(type = :any) Also known as: t

Returns all topics contained in this topic map.

The optional argument specifies the type of the topics should have, i.e. all instances of the specified type are returned. Type may be a topic reference. This method equals instances (type).

The return value may be empty.

:call_spec: 

  topics -> Set of Topics
  topics(type) -> Array of Topics



296
297
298
299
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 296

def topics(type = :any)
  return getTopics if type == :any
  return instances(type)
end

- (Object) type_instance_index Also known as: tii

Calls TMAPI TopicMap.getIndex which returns the index for the TypeInstanceIndex.

:call-seq: 

  type_instance_index -> TypeInstanceIndex



208
209
210
211
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 208

def type_instance_index
  # Equals _index(:TypeInstanceIndex), which doesn't work yet
  getIndex(Java::OrgTmapiIndex::TypeInstanceIndex.java_class)
end

- (Object) types

Returns all topics in the topic map that are used as type in an “type-instance”-relationship.

:call-seq: 

  types -> Set of Topics



259
260
261
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 259

def types
  type_instance_index.getTopicTypes
end

- (Object) variants

Returns all variants occurring in the topic map 



568
569
570
 
# File 'rtm-javatmapi/lib/rtm/javatmapi/core/topic_map.rb', line 568

def variants
  names.map{|name| name.variants.to_a}.flatten
end