org.xspace.service
Class XSpaceService

java.lang.Object
  org.xspace.service.XSpaceService

public class XSpaceService

extends java.lang.Object

An XSpace is a hierarchically-keyed repository for values, accessible globally via XSpaceService.
A key is simply a String with a tree path syntax. For example, /a/b/c
A value can be a String or an XML document.

XSpaceService provides the methods you'll need to interact with an XSpace.

The most useful methods when you are starting to use this API are:

createXSpace - to create an XSpace
put - to put a key/value into an XSpace
get - to get the value of a key in an XSpace
delete - to remove a key from an XSpace

Other useful methods are:

putXML - to put a key/value where value is an XML document
listXSpaces - to get a list of available XSpace names
createSubscriptionForEvents - to listen for XSpace events (for e.g.,when a key is added or deleted)
createSubscriptionForAdminEvents - to listen for admin events (for e.g., when an XSpace is created or deleted)

Method Summary

XSpaceSubscriber	createSubscriptionForAdminEvents(javax.jms.MessageListener listener) Creates a subscription for an XSpace administration event.
XSpaceSubscriber	createSubscriptionForEvents(java.lang.String xspaceName, javax.jms.MessageListener listener) Creates a subscription for an XSpace event.
XSpaceSubscriber	createSubscriptionForEvents(java.lang.String xspaceName, java.lang.String key, javax.jms.MessageListener listener) Creates a subscription for an XSpace event for a specified key.
int	createXSpace(java.lang.String xspaceName) Creates an XSpace with the given name
void	delete(java.lang.String xspaceName, java.lang.String key) Deletes a key from an XSpace
void	deleteXSpace(java.lang.String xspaceName) Deletes an XSpace with the given name
java.lang.String[]	findChildrenPaths(java.lang.String xspaceName, java.lang.String path, boolean fullPath) Returns all immediate children paths for a specified path.
java.lang.String[]	findDescendantPaths(java.lang.String xspaceName, java.lang.String path) Returns all descendant paths for a specified path.
XSpaceItem	get(java.lang.String xspaceName, java.lang.String key) Gets the value for a key in an XSpace
java.lang.String[]	getAllKeys(java.lang.String xspaceName) Gets all the keys in an XSpace.
static XSpaceService	getInstance() Returns a handle to the non-authenticated XSpaceService.
static XSpaceService	getInstance(XSpaceCredential credential) Returns a handle to the authenticated XSpaceService.
java.lang.String[]	getKeys(java.lang.String xspaceName, java.lang.String path) Gets all the keys starting at the given path in an XSpace
java.lang.String[]	listXSpaces() Lists the names of all XSpaces
void	put(java.lang.String xspaceName, java.lang.String key, java.lang.String value) Puts a value for a key in an XSpace
void	putXML(java.lang.String xspaceName, java.lang.String key, org.w3c.dom.Document document) Puts an XML document as a value for a key in an XSpace
java.lang.String[]	search(java.lang.String xspaceName, java.lang.String path, java.lang.String searchString) Searches an XSpace for values containing the search string.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static XSpaceService getInstance()

Returns a handle to the non-authenticated XSpaceService.

Returns:

the XSpace handle

getInstance

public static XSpaceService getInstance(XSpaceCredential credential)

Returns a handle to the authenticated XSpaceService.

Parameters:

credential - the user ID/password credential

Returns:

the XSpace handle

createXSpace

public int createXSpace(java.lang.String xspaceName)
                 throws java.rmi.RemoteException,
                        org.xspace.util.XSpaceException

Creates an XSpace with the given name

Parameters:

xspaceName - the XSpace name

Returns:

an identifier for the newly created XSpace

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

deleteXSpace

public void deleteXSpace(java.lang.String xspaceName)
                  throws java.rmi.RemoteException,
                         org.xspace.util.XSpaceException

Deletes an XSpace with the given name

Parameters:

xspaceName - the XSpace name

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

listXSpaces

public java.lang.String[] listXSpaces()
                               throws java.rmi.RemoteException,
                                      org.xspace.util.XSpaceException

Lists the names of all XSpaces

Returns:

an array of XSpace names

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

put

public void put(java.lang.String xspaceName,
                java.lang.String key,
                java.lang.String value)
         throws java.rmi.RemoteException,
                org.xspace.util.XSpaceException

Puts a value for a key in an XSpace

Parameters:

xspaceName - the name of the XSpace

key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)

value - the string value

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

putXML

public void putXML(java.lang.String xspaceName,
                   java.lang.String key,
                   org.w3c.dom.Document document)
            throws java.rmi.RemoteException,
                   org.xspace.util.XSpaceException

Puts an XML document as a value for a key in an XSpace

Parameters:

xspaceName - the name of the XSpace

key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)

document - the XML document

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

get

public XSpaceItem get(java.lang.String xspaceName,
                      java.lang.String key)
               throws java.rmi.RemoteException,
                      org.xspace.util.XSpaceException

Gets the value for a key in an XSpace

Parameters:

xspaceName - the name of the XSpace

key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)

Returns:

value the value

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

delete

public void delete(java.lang.String xspaceName,
                   java.lang.String key)
            throws java.rmi.RemoteException,
                   org.xspace.util.XSpaceException

Deletes a key from an XSpace

Parameters:

xspaceName - the name of the XSpace

key - the key (the format must adhere to XSpace path syntax: e.g. /a/b/c)

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

getKeys

public java.lang.String[] getKeys(java.lang.String xspaceName,
                                  java.lang.String path)
                           throws java.rmi.RemoteException,
                                  org.xspace.util.XSpaceException

Gets all the keys starting at the given path in an XSpace

Parameters:

xspaceName - the name of the XSpace

path - the path (e.g. /, /a, /a/b/c)

Returns:

an array of keys

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

getAllKeys

public java.lang.String[] getAllKeys(java.lang.String xspaceName)
                              throws java.rmi.RemoteException,
                                     org.xspace.util.XSpaceException

Gets all the keys in an XSpace. Equivalent to calling getKeys with "/" as the path

Parameters:

xspaceName - the name of the XSpace

Returns:

an array of keys

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

findChildrenPaths

public java.lang.String[] findChildrenPaths(java.lang.String xspaceName,
                                            java.lang.String path,
                                            boolean fullPath)
                                     throws java.rmi.RemoteException,
                                            org.xspace.util.XSpaceException

Returns all immediate children paths for a specified path. For example, if the following keys exist: /a/b, /a/c, /a/d then this method would return b, c, d as the children of /a

Parameters:

xspaceName - the name of the XSpace

path - the starting path

fullPath - a flag indicating whether the returned paths should be full paths

Returns:

an array of paths (keys)

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

findDescendantPaths

public java.lang.String[] findDescendantPaths(java.lang.String xspaceName,
                                              java.lang.String path)
                                       throws java.rmi.RemoteException,
                                              org.xspace.util.XSpaceException

Returns all descendant paths for a specified path. For example, if the following keys exist: /a/b, /a/c, /a/c/d, /a/c/e then this method would return /a/b, /a/c, /a/c/d and /a/c/e as the descendants of /a

Parameters:

xspaceName - the name of the XSpace

path - the starting path

Returns:

an array of paths (keys)

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

search

public java.lang.String[] search(java.lang.String xspaceName,
                                 java.lang.String path,
                                 java.lang.String searchString)
                          throws java.rmi.RemoteException,
                                 org.xspace.util.XSpaceException

Searches an XSpace for values containing the search string. The search can begin from any node in the tree. For example to search an entire tree, simply pass in "/" (root) as the starting path. An array of keys containing the search results is returned. If no results are found, an empty array is returned.

Parameters:

xspaceName - the name of the XSpace

path - the starting path

searchString - the search string

Returns:

an array of paths (keys)

Throws:

java.rmi.RemoteException

org.xspace.util.XSpaceException

createSubscriptionForEvents

public XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName,
                                                    javax.jms.MessageListener listener)
                                             throws org.xspace.util.XSpaceException,
                                                    javax.jms.JMSException

Creates a subscription for an XSpace event. An XSpace event could be one of the following:
1. a new key/value has been added to the XSpace
2. the value has been updated for an existing key in the XSpace
3. a key has been deleted from the XSpace
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:

xspaceName - the name of the XSpace

listener - the listener (which implements javax.jms.MessageListener interface)

Returns:

a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.

Throws:

org.xspace.util.XSpaceException

javax.jms.JMSException

createSubscriptionForEvents

public XSpaceSubscriber createSubscriptionForEvents(java.lang.String xspaceName,
                                                    java.lang.String key,
                                                    javax.jms.MessageListener listener)
                                             throws org.xspace.util.XSpaceException,
                                                    javax.jms.JMSException

Creates a subscription for an XSpace event for a specified key. An XSpace event could be one of the following:
1. the specified key with value has been added to the XSpace
2. the value has been updated for an existing specified key in the XSpace
3. the specified key has been deleted from the XSpace
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:

xspaceName - the name of the XSpace

key - the key

listener - the listener (which implements javax.jms.MessageListener interface)

Returns:

a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.

Throws:

org.xspace.util.XSpaceException

javax.jms.JMSException

createSubscriptionForAdminEvents

public XSpaceSubscriber createSubscriptionForAdminEvents(javax.jms.MessageListener listener)
                                                  throws org.xspace.util.XSpaceException,
                                                         javax.jms.JMSException

Creates a subscription for an XSpace administration event. An XSpace administration event could be one of the following:
1. an XSpace has been created
2. an XSpace has been deleted
The event will be delivered wrapped in a JMS message to the listener's onMessage method.

Parameters:

listener - the listener (which implements javax.jms.MessageListener interface)

Returns:

a handle to the subsriber. To stop receiving events, invoke close() on this subscriber.

Throws:

org.xspace.util.XSpaceException

javax.jms.JMSException