Quick Start

Document Index:

1. Installation

XSpace requires Java JDK 1.4 or higher. Ensure that java is in your execution path.

By default, the XSpace Server is deployed in JBoss.

Ensure you have JBoss (4.0.3 is the most well-tested with XSpace) on your computer.
You will also require ant to be installed and available on your path.

Follow these steps to install XSpace:

On a separate terminal, start the JBoss server. (For example, execute jboss-4.0.3/bin/run)
Unzip xspace release zip file to your local folder.
On another terminal, cd to the xspace home directory (refered to as: <xspace_home> in all documents)
Edit build.properties and ensure that deploydir points to the correct deployment path in JBoss.
Deploy the XSpace Server to JBoss; type: ant deploy

2. Walk-through of the QuickStart example.

In this simple program, we create an XSpace called “MySpace”, put data about stocks into it and get data out of it. We also create a listener for changes made to data in MySpace. The following listing shows the QuickStart program. (The complete source is found in <xspace_home>/src/org/xspace/examples/quickstart/QuickStart.java)

public class QuickStart implements MessageListener {

    private XSpaceService xspaceService = XSpaceService.getInstance(); // Handle to XSpace Service



    public void run() {

        // Create an XSpace called "MySpace".

        try {

            xspaceService.createXSpace("MySpace");

        } catch (Exception e) {

            // An exception will be thrown if the XSpace already exists, but it's OK to proceed.

            System.out.println (e.getMessage());

        }



        // Put some data into "MySpace"

        try {

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/GOOG", "480.5");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/AAPL", "80.5");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/ORCL","18.4");

          xspaceService.put("MySpace", "/Portfolio/Equities/MediumCap/Tech/TIBX", "7.2");

          xspaceService.put("MySpace", "/Portfolio/Equities/MediumCap/Tech/HP", "35.0");

          xspaceService.put("MySpace", "/Portfolio/Equities/MediumCap/Tech/BEA", "14.5");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/IBM", "99.1");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/GOOG", "480.5");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Healthcare/PFZ","88.0");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Healthcare/DNA","77.0");

          xspaceService.put("MySpace", "/Portfolio/Equities/MediumCap/Healthcare/AMGN", "70.2");

          xspaceService.put("MySpace", "/Portfolio/Equities/MediumCap/Healthcare/UHC", "56.0");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Finance/GS","288.0");

          xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Finance/MS","48.0");

          xspaceService.put("MySpace", "/Portfolio/Bonds/Treasury", "");

          xspaceService.put("MySpace", "/Portfolio/Bonds/Corporate", "");

        } catch (Exception e) {

            System.out.println (e.getMessage());

        }

        // Get some data from "MySpace"

        try {

            XSpaceItem item = null;

            item = xspaceService.get("MySpace", "/Portfolio/Equities/LargeCap/Tech/IBM");

            System.out.println (item.getKey() + " " + item.getValue());

            item = xspaceService.get("MySpace", "/Portfolio/Equities/LargeCap/Tech");

            System.out.println (item.getKey() + " " + item.getValue());

                        // Get the keys for large cap financial stocks.

            String[] financialStocks =

              xspaceService.findChildrenPaths("MySpace","/Portfolio/Equities/LargeCap/Finance", true);

            if (financialStocks != null) {

                System.out.println ("Large cap financial stocks:");

                for (int i = 0; i < financialStocks.length; i++) {

                    item = xspaceService.get("MySpace", financialStocks[i]);

                    System.out.println (item.getKey() + " " + item.getValue());

                }

            }

        } catch (Exception e) {

            System.out.println (e.getMessage());

        }

        // Create a subscription to listen for events on "MySpace"

      try {

            XSpaceSubscriber subscriber = xspaceService.createSubscriptionForEvents("MySpace", this);

        } catch (Exception e) {

            System.out.println (e.getMessage());

        }

    }

    public void onMessage (Message msg) {

       ObjectMessage om = (ObjectMessage) msg;

       try {

           XSpaceEvent event = (XSpaceEvent)om.getObject();

           System.out.println (event);

           XSpaceItem item = xspaceService.get("MySpace", event.getKey());

           if (item != null) {

              System.out.println ("Value = " + item.getValue());

           }

       } catch (Exception e) {

          System.out.println (e.getMessage());

       }

    }

       public static void main(String[] args) {

            new QuickStart().run();

       }

}

Notes:

Because our program wants to receive events, it needs to implement the JMS MessageListener interface.

public class QuickStart implements MessageListener {

To get a handle to the XSpace Service, we simply invoke the newInstance() static method on the XSpaceService class.

Any subsequent operations on XSpace can then be invoked using this handle.

private XSpaceService xspaceService = XSpaceService.getInstance();

To create an XSpace, we simply call the service’s “createXSpace” method giving it the name of the XSpace. XSpace names are simply strings.

xspaceService.put("MySpace", "/Portfolio/Equities/LargeCap/Tech/GOOG", "480.5");

xspaceService.createXSpace("MySpace");

An exception is thrown if the XSpace already exists.

To put a key/value pair into an XSpace, we use the “put” method. The key must conform to the path syntax. Note that / is considered the root in XSpace and so all paths must begin with /. In the example, we are putting a simple string value. If the key already exists in the XSpace, its value will be overwritten by the latest put.

To get a key/value pair from an XSpace, we use the “get” method passing in the XSpace name and the key. An XSpaceItem object is returned if the key exists, otherwise null is returned. The XSpaceItem contains the value for the key plus other bits of useful information such as when it was last modified and by whom.

The value may be null or an empty string (“”).

XSpaceItem item = xspaceService.get("MySpace", "/Portfolio/Equities/LargeCap/Tech/IBM");

The following call to “findChildrenPaths” retrieves all the immediate children of a node in XSpace. The results are returned as an array of paths. In our quick start example, we want all the large cap financial stocks, so we invoke “findChildrenPaths” passing in “/Portfolio/Equities/LargeCap/Finance” as the key and boolean true to get the results back as full paths. The returned paths in our example would be “"/Portfolio/Equities/LargeCap/Finance/GS" and
"/Portfolio/Equities/LargeCap/Finance/MS".

String[] financialStocks =

xspaceService.findChildrenPaths("MySpace","/Portfolio/Equities/LargeCap/Finance", true);

The following code creates a subscription for any events that occur in “MySpace”. Note that the second argument passed in is “this”, our MessageListener.

An XSpaceSubscriber object is returned. To stop receiving events, call the close() method on the this XSpaceSubscriber object. You may also create subscribers for specific keys and use * for the XSpace name to receive events for all XSpaces. (See API documentation).

XSpaceSubscriber subscriber = xspaceService.createSubscriptionForEvents("MySpace", this);

Events are delivered to the onMessage method. The code below simply prints out the XSpaceEvent object. There are three types of events: ADD, UPDATE and DELETE corresponding to when a new key is added to the XSpace, when an existing value is updated, and when a key is deleted. Note that XSpaceEvent does not contain the value only the key, so use the “get” method to get the value.

public void onMessage (Message msg) {

    ObjectMessage om = (ObjectMessage) msg;

    try {

         XSpaceEvent event = (XSpaceEvent)om.getObject();

         System.out.println (event);

         XSpaceItem item = xspaceService.get("MySpace", event.getKey());

         if (item != null) {

             System.out.println ("Value = " + item.getValue());

         }

    } catch (Exception e) {

         System.out.println (e.getMessage());

    }

}

3. Running the QuickStart example

Bring up a new terminal.
cd to the <xspace_home> directory
execute: ant runQuickStart

Notice that the program does not exit. Since it created an XSpace subscription, it is now waiting for events. Let’s start creating some events using the XSpace Browser. To run the browser:

· Bring up a new terminal

· cd to the <xspace_home> directory

· execute: ant runXSpaceBrowser

When the browser comes up do the following:

· Click on File / Open XSpace…

· In the pop-up list, select “MySpace”, and click OK.

· The tree appears on the left panel.

· Expand the nodes and click on a leaf node.

· The current value for that key appears on the right panel.

· Change the value and click on the Update Value button on the bottom left.
Notice that an UPDATE event is echoed on the QuickStart terminal.

· Right click on the node corresponding to /Portfolio/Equities/LargeCap/Tech and select Add.

· Enter “ML” and notice that an ADD event is echoed on the QuickStart terminal.

· Right click on the node you just added and select Delete.

· Notice that a DELETE event is echoed on the QuickStart terminal.

4. A tour of the XSpace API

All interactions with the XSpace server are made via an instance of the XSpaceService class.

The following describes the XSpaceService methods:

4.1 Getting an instance of the XSpaceService class.

The first thing you’ll need to do in your XSpace client is to get an instance of the XSpaceService class.

There are two ways to get an instance of the XSpaceService handle:

Method

Description

XSpaceService getInstance()

Use this method if you do not wish to authenticate access to the XSpace service.

XSpaceService getInstance(XSpaceCredential credential)

Use this method if you want to impose secure access to the XSpace service.

The argument passed in is an XSpaceCredential object, which contains a user ID and password. For a discussion on XSpace Security see, the

Developer Guide (to be done).

4.2 Creating, listing, deleting XSpaces

An XSpace server may host n number of XSpaces.

You can use the following methods to create, delete and get a list of XSpaces names available on the XSpace server.

Method

Description

int createXSpace(String xspaceName)

Instructs the server to create an XSpace with the given name. If one with the same name already exists, an exception is thrown. xspaceNames are case-sensitive! A unique numeric ID for the XSpace is returned. When an XSpace is created, the the root key, “/” is automatically created.

String[] listXSpaces()

Returns a list of XSpace names available on the server.

void deleteXSpace(String xspaceName)

Deletes an XSpace with the given name. All data in the XSpace is deleted as part of this operation.

4.3 Getting/Putting/Deleting key/values

The following methods let you put, get and delete key/values in an XSpace.

Note that the put methods will overwrite the current value if the key being put already exists in an XSpace. XSpace keys are strings but follow the path syntax, using “/” as separator. The root is denoted by “/”. Examples of XSpace keys: /a, /a/b, /x/y/z). Keys can be of any length.

Method	Description
void put(String xspaceName, String key, String value)	Puts a simple string key/value into the named XSpace
void putXML(String xspaceName, String key, Document xml)	Puts a key and an XML document as value into the named XSpace.
	Returns the contents of a key in the named XSpace. The object returned is an XSpaceItem, a wrapper for the value. Simply call getValue() if the value is a String or getXML() if the value is an XML type. Note that if you attempt to call getXML() on a value that is not of XML type, an exception will be thrown. Calling getValue() on an XML type, however is OK; it simply returns the XML document as a serialized String. If the key does not exist in the XSpace, null is returned.
void delete(String xspaceName, String key)	Deletes a key and its associated value from the named XSpace. If the key does not exist, an exception is thrown.

4.4 Key Retrieval/Search

The following methods let you search and retrieve keys from an XSpace. “Path” and “Key” are used interchangeably:

Method	Description
String[] getKeys(String xspaceName, String path)	Returns all the keys starting at the given path in a named XSpace. To get all keys in an XSpace, pass in the root, “/” as the value to the path argument. If no keys are found, an empty array is returned.
String[] getAllKeys(String xspaceName)	Returns all the keys in a named XSpace. Similar to calling getKeys passing in “/” as the path argument
String[] findChildrenPaths(String xspaceName, String path, boolean fullPath)	Returns all the immediate children of the given path in the given XSpace. If fullPath is true, the results are returned as full paths. An empty array is returned if there are no children found.
String[] findDescendantPaths(String xspaceName, String path)	Returns all descendants of a given path in the given XSpace. Full paths are returned. An empty array is returned if there are no descendants found.
String[] search (String xspaceName, String path, String searchString)	Searches all the values of a named XSpace from a given path that contains the given search string. The matching keys are returned. An empty array is returned if the search results in no matches.

4.5 Events

Use these methods to create subscriptions for XSpace events that you want to capture.

Events are encapsulated in the XSpaceEvent object and may have one of the following types:

1. ADD_XSPACE_ITEM (when a key is added)

2. UPDATE_XSPACE_ITEM (when the value for a key is updated)

3. DELETE_XSPACE_ITEM (when a key is deleted)

4. ADD_XSPACE (when an XSpace is created)

5. UPDATE_XSPACE (when an XSpace’s metadata is updated)

6. DELETE_XSPACE (when an XSpace is deleted)

Method	Description
XSpaceSubscription createSubscriptionForEvents(String xspaceName, MessageListener listener)	If you would like to capture events related to when any key is added, updated or deleted from a given XSpace, call this method. XSpace events will then be delivered to the onMessage method of the MessageListener that is passed in as the second argument. If you want to stop receiving events, call the close method on the returned XSpaceSubscription object. (One of event types 1-3 is delivered).
XSpaceSubscription createSubscriptionForEvents(String xspaceName, String key, MessageListener listener)	This is similar to the above, except that the subscription is for a specific key.
XSpaceSubscription createSubscriptionForAdminEvents(MessageListenere listener)	If you want to capture events related to when an XSpace is created, updated or deleted, call this method. (One of event types 4 – 6 is delivered).

Here is an example of a MessageListener’s onMessage method. It shows you how to extract the XSpaceEvent object from the JMS message.

public void onMessage (Message msg) {

ObjectMessage om = (ObjectMessage) msg;

try {

XSpaceEvent event = (XSpaceEvent)om.getObject();

String eventType = event.getEventType();

String key = event.getKey();

} catch (Exception e) {

}

5. Next Steps

You are now ready to write your own XSpace application. Refer to the User Guide for instructions on how to set up your class path and to configure jndi.properties (optional) and the database (optional).

You can also run the examples. Examples are found in <xspace_home>/src/org/xspace/examples. Each example has a README file containing information about the example.