View source for Wandora Web Service

Wandora contains a SOAP based web service implemented with [http://ws.apache.org/axis/ Apache Axis] web service toolkit. Web service interface makes it possible to use topic maps remotely and with other platforms than Java. The source code distribution package contains a [[Sample Flash Application]] in ''extras > flash_apps'' that utilizes the web service interface and allows the user to browse a topic map inside a [http://www.adobe.com/products/flash/ Flash] based application.

See [[Setting up Wandora Piccolo server#Web Service]] for information about how to setup the web service with Wandora Piccolo server.

You can also use the web service through the [[Embedded HTTP server#SOAP Web service access (axis) | Embedded HTTP server]].

== Using the Web Service ==

The web service exposes four methods that can be used to access the topic map.

{| border="1" cellspacing="0" cellpadding="5"
!  Method !!   Parameters !! Description 
|-
|  getTopic || String si, boolean full || Gets information about the topic with subject identifier ''si''.
|-
|  getTopics || String[] si, boolean full || Gets information about sereval topics. The subject identifiers of the topics are given as an array in ''si''.
|-
|  getTopicWithBaseName || String baseName, boolean full || Gets information about the topic with base name ''baseName''.
|-
|  getTopicsOfType || String si, boolean full || Gets information about all topics that are instances of the topic with subject identifier ''si''.
|}

All methods can be used in two different modes, partial or full mode. Passing ''true'' as second parameter invokes the method in full mode, otherwise the method is invoked in partial mode. In partial mode no association or occurrence information about the topic is included. In full mode everything about the topic is included. Separating full and partial modes enables the implementation work significantly faster in certain occasions where associations and occurrences are not necessary.

All methods return one or more WSTopic data structures. Other topics in the data structure are always referenced by subject identifiers. For example, the type array contains subject identifiers of the type topics. Only one subject identifier of each type is included in the array. If a type contains more than one subject identifier the choice which one is used in the array is done arbitrarily. Following table describes the WSTopic data structure.

{| border="1" cellspacing="0" cellpadding="5"
|colspan=3 align="center"|  WSTopic
|-
!  field !! type !! Description 
|-
|  full || boolean || A flag indicating if this topic data structure contains full information about a topic or only partial. Partial topics do not have association or occurrence information but all other fields are set properly.
|-
|  baseName || String || The base name of the topic.
|-
|  variantTypes || String[] || All variant name types used in this topic. The array contains subject identifiers of the topics used as types.
|-
|  variantLanguages || String[][] || All variant name languages used for a certain variant name type. variantLanguages[i] contains languages for variant type variantType[i]. The array contains subjec tidentifiers of the topics used as languages.
|-
|  variantNames || String[][] || The variant names of the topic. variantNames[i][j] is the variant name with type variantTypes[i] and language variantLanguages[i][j].
|-
|  subjectLocator || String || The subject locator of the topic. Can be null.
|-
|  subjectIdentifiers || String[] || The subject identifiers of the topic.
|-
|  types || String[] || The types of the topic. The array contains subject identifiers of type topics.
|-
|  associations || WSAssociation[] || Associations of the topic. This field is only set in full mode. The array contains WSAssociation data structures.
|-
|  occurrences || WSOccurrence[] || Occurrences of the topic. This field is only set in full mode. The array contains WSOccurrence data structures.
|}

Topics may contain associations which are returned in WSAssociation data structures. Following table describes this data structure.

{| border="1" cellspacing="0" cellpadding="5"
|colspan=3 align="center"|  WSAssociation
|-
!  field !! type !! Description 
|-
|  type || String || The type of the topic. Field contains a subject identifier of the type topic.
|-
|  players || WSPlayer[] || The players of the topic as an array of WSPlayer data structures.
|}

Following table describes WSPlayer data structure used in WSAssociation 

{| border="1" cellspacing="0" cellpadding="5"
|colspan=3 align="center"|  WSPlayer
|-
!  field !! type !! Description 
|-
|  role || String || The role of the player. The field contains a subject identifier of the role topic.
|-
|  member || String || The member topic. The field contains a subject identifier of the topic.
|}

Topcis may also contain occurrences which are returned in WSOccurrence data structures. Following table describes this data structure.

{| border="1" cellspacing="0" cellpadding="5"
|colspan=3 align="center"|  WSOccurrence
|-
!  field !! type !! Description 
|-
|  type || String || The type of the occurrence. The field contains a subject identifier of the type topic.
|-
|  version || String || The version of the occurrence. The field contains a subject identifier of the version topic.
|-
|  content || String || Content data for the occurrence.
|}


Typically you would first get information about one topic in full mode using either ''getTopic'' or ''getTopicWithBaseName'' method. Since you probably want to include at least the name of some of the associated topics, you will need to make another query. Best way to do this is to use ''getTopics'' method to get information about all the needed topics in one query. You most likely don't need associations or occurrences of these topics so you can use partial mode. If you want to present the instances of the topic, use ''getTopicsOfType'' to get them.