From 0cd028c5b234f10757010531e79728f01857d2b7 Mon Sep 17 00:00:00 2001 From: jprocter Date: Wed, 14 Sep 2005 13:41:41 +0000 Subject: [PATCH] first version sent out to Iain and Pierre git-svn-id: https://svn.lifesci.dundee.ac.uk/svn/repository/trunk@7 be28352e-c001-0410-b1a7-c7978e42abec --- .classpath | 6 ++ .project | 17 +++++ build.xml | 84 +++++++++++------------ src/org/vamsas/client/ClientDocument.java | 19 ++++++ src/org/vamsas/client/ClientHandle.java | 70 +++++++++++++++++++ src/org/vamsas/client/Events.java | 50 +++++++++++--- src/org/vamsas/client/IClientDocument.java | 83 ++++++++++++++++++++++ src/org/vamsas/client/Iapp.java | 2 +- src/org/vamsas/client/Iclient.java | 102 +++++++++++++++++++++------- src/org/vamsas/client/IclientFactory.java | 47 +++++++++++++ src/org/vamsas/client/SessionHandle.java | 31 +++++++++ src/org/vamsas/client/UserHandle.java | 42 ++++++++++++ src/org/vamsas/client/VorbaId.java | 29 ++++++++ src/org/vamsas/client/VorbaIdFactory.java | 28 ++++++++ src/org/vamsas/client/object.java | 57 ++++++++++++++-- 15 files changed, 581 insertions(+), 86 deletions(-) create mode 100644 .classpath create mode 100644 .project create mode 100644 src/org/vamsas/client/ClientDocument.java create mode 100644 src/org/vamsas/client/ClientHandle.java create mode 100644 src/org/vamsas/client/IClientDocument.java create mode 100644 src/org/vamsas/client/IclientFactory.java create mode 100644 src/org/vamsas/client/SessionHandle.java create mode 100644 src/org/vamsas/client/UserHandle.java create mode 100644 src/org/vamsas/client/VorbaId.java create mode 100644 src/org/vamsas/client/VorbaIdFactory.java diff --git a/.classpath b/.classpath new file mode 100644 index 0000000..2061450 --- /dev/null +++ b/.classpath @@ -0,0 +1,6 @@ + + + + + + diff --git a/.project b/.project new file mode 100644 index 0000000..2c66c73 --- /dev/null +++ b/.project @@ -0,0 +1,17 @@ + + + VamsasClient + + + + + + org.eclipse.jdt.core.javabuilder + + + + + + org.eclipse.jdt.core.javanature + + diff --git a/build.xml b/build.xml index c8d6513..10f8e49 100644 --- a/build.xml +++ b/build.xml @@ -1,12 +1,12 @@ - - - - + + + + - - + + @@ -20,54 +20,54 @@ - + - - + + - - + + - - - - - - - - - - - - - + + - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + - - + + - + diff --git a/src/org/vamsas/client/ClientDocument.java b/src/org/vamsas/client/ClientDocument.java new file mode 100644 index 0000000..85014e0 --- /dev/null +++ b/src/org/vamsas/client/ClientDocument.java @@ -0,0 +1,19 @@ +/* + * + */ +package org.vamsas.client; + +import java.util.Vector; + +/** + * @author jimp + * Contains a collection of vamsas objects and reference + * to a specified ClientHandle's information. + */ +public class ClientDocument implements IClientDocument { + /** + * collection of org.vamsas.client.objects + */ + Vector VamsasObjects; + byte[] appData; +} diff --git a/src/org/vamsas/client/ClientHandle.java b/src/org/vamsas/client/ClientHandle.java new file mode 100644 index 0000000..0269af4 --- /dev/null +++ b/src/org/vamsas/client/ClientHandle.java @@ -0,0 +1,70 @@ +/* + */ +package org.vamsas.client; + +/** + * Uniquely describes a vamsas client application. + * @author jimp + */ +public class ClientHandle { + /** + * (non-unique) human readable vamsas client name + */ + String clientName; + + /** + * the unambiguous client identifier + */ + String clientUrn; + + /** + * version modifier to tag application space + */ + String version; + + /** + * @return Returns the clientUrn. + */ + public String getClientUrn() { + return clientUrn; + } + + /** + * @param clientUrn + * The clientUrn to set. + */ + public void setClientUrn(String clientUrn) { + this.clientUrn = clientUrn; + } + + /** + * @return Returns the version. + */ + public String getVersion() { + return version; + } + + /** + * @param version + * The version to set. + */ + public void setVersion(String version) { + this.version = version; + } + + + /** + * @return Returns the clientName. + */ + public String getClientName() { + return clientName; + } + + /** + * @param clientName + * The clientName to set. + */ + public void setClientName(String clientName) { + this.clientName = clientName; + } +} diff --git a/src/org/vamsas/client/Events.java b/src/org/vamsas/client/Events.java index 1864790..2532427 100644 --- a/src/org/vamsas/client/Events.java +++ b/src/org/vamsas/client/Events.java @@ -1,14 +1,44 @@ package org.vamsas.client; +/** + * Enumerates the event types generated + * during the lifecycle of a Vamsas session. + */ public class Events { - /** - * Event types generated during the lifecycle of a Vamsas session. - */ - - public static final String DOCUMENT_UPDATE="org.vamsas.client.documentUpdateEvent"; - public static final String DOCUMENT_CREATE="org.vamsas.client.documentCreateEvent"; - public static final String CLIENT_CREATION="org.vamsas.client.clientCreateEvent"; - public static final String CLIENT_FINALIZATION="org.vamsas.client.clientFinalizationEvent"; - public static final String SESSION_SHUTDOWN; // - public static final String DOCUMENT_CLOSE; // + /** + * Generated when a client has finished updating the document. + * Passes applicationHandle of client so the updating client can recognise its own updates. + */ + public static final String DOCUMENT_UPDATE="org.vamsas.client.documentUpdateEvent"; + /** + * Generated when a new vamsas document is created + * so an application may do its own data space initialization + */ + public static final String DOCUMENT_CREATE="org.vamsas.client.documentCreateEvent"; + /** + * Generated when a new vamsas client is attached to a session (Handle is passed) + * Note: the newly created client does not receive the event. + */ + public static final String CLIENT_CREATION="org.vamsas.client.clientCreateEvent"; + /** + * Generated when a vamsas client leaves a session (Handle is passed). + */ + public static final String CLIENT_FINALIZATION="org.vamsas.client.clientFinalizationEvent"; + /** + * Generated prior to session Shutdown, after the last participating vamsas client has finalized. + */ + public static final String SESSION_SHUTDOWN="org.vamsas.client.SessionShutdownEvent"; + /** + * Generated by Vorba stub after the penultimate client makes a call to closeDocument(). + * Sequence is as follows : + * 1. All other vamsas clients have called closeDocument() + * 2. Final living client monitors closures, and realises that it is last. + * 3. Final client generates event to prompt associated application to inquire if + * the user wishes to save the document for future reference. + * + * * Any call to closeDocument in a thread other than the registered EventListener + * will block until the RequestToClose handler has exited. + * + */ + public static final String DOCUMENT_REQUESTTOCLOSE="org.vamas.client.DocumentRequestToCloseEvent"; } diff --git a/src/org/vamsas/client/IClientDocument.java b/src/org/vamsas/client/IClientDocument.java new file mode 100644 index 0000000..df20713 --- /dev/null +++ b/src/org/vamsas/client/IClientDocument.java @@ -0,0 +1,83 @@ +/* + * Created on 13-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.client; + +import java.util.Vector; + +/** + * Defines the API for the Vamsas XML Document + * as accessed by a Vamsas Client Application. + * An instance of this interface is valid for a + * particular set of user, session and application + * handles. + * + * It initially represents a snapshot of the + * XML document at a particular time - queriable by + * reference or by retrieval of root objects. + * It provides methods to make new object references, + * These are guaranteed to be unique amongst existing + * objects in the document, all other references created + * by this object's instance and all other references + * constructed by any other vamsas agents in the session. + * TODO: Since a clientDocument is created for a particular + * UserHandle, there is scope for fine grain data access + * control based on user identity. + * A user may also want to make private notes, not + * available to other people using the same application + * in the same session. + * + * @author jimp + */ +public interface IClientDocument { + + /** + * Get a single object. + * @param id + * @return object referred to by id or null if it doesn't exist. + */ + object getObject(VorbaId id); + /** + * Get a list of objects. + * @param ids + * @return array of objects using a vector of VorbaId ids. + */ + object[] getObjects(VorbaId[] ids); + /** + * Returns all root objects in document. All objects inherit + * from org.vamsas.client.object and have valid VorbaIds. + * @return array of root Vamsas element objects. (TODO: insert correct class here) + */ + object[] getVamsasRoots(); + /** + * Returns an object with a valid VorbaId so the + * application may refer to it in its own dataspace. + * Note: An object with valid VorbaId will not be reregistered. + * @param unregistered unregistered vamsas object + * @return registered vamsas object + */ + object registerObject(object unregistered); + /** + * Returns an array of objects, each with a valid VorbaId. + * Note: An object with valid VorbaId will not be reregistered. + * @param unregistered array of unregistered objects. + * @return array of registered objects + */ + object[] registerObjects(object[] unregistered); + /** + * Gets the application data associated with this session's + * vamsas document that is accessible by the client + * application (and user) + * @return applicationData field + */ + byte[] getApplicationData(); + /** + * Sets the application data entry associated with + * the application and user participating in this vamsas session. + * @param newData new contents of applicationData field. + */ + void setApplicationData(byte[] newData); +} \ No newline at end of file diff --git a/src/org/vamsas/client/Iapp.java b/src/org/vamsas/client/Iapp.java index cba2637..a74eb28 100644 --- a/src/org/vamsas/client/Iapp.java +++ b/src/org/vamsas/client/Iapp.java @@ -2,7 +2,7 @@ * org.vamsas.client.Iapp */ package org.vamsas.client; -Interface Iapp { +public interface Iapp { /** * Define core callback functionality that a fully * fledged vamsas application object must implement diff --git a/src/org/vamsas/client/Iclient.java b/src/org/vamsas/client/Iclient.java index 96a7711..d8ec50d 100644 --- a/src/org/vamsas/client/Iclient.java +++ b/src/org/vamsas/client/Iclient.java @@ -3,46 +3,96 @@ * */ package org.vamsas.client; -Interface Iclient { + +import java.beans.EventHandler; +import java.beans.PropertyChangeListener; +import java.util.EventListener; + +/** + * Defines the methods availabable to a vamsas + * application for interacting with its Vorba agent + * created by an IclientFactory instance for a particular session, + * user, and application handle. + * (it's VORBA, not CORBA!) + */ + +public interface Iclient { + + /** + * Self-documenting/describing info for the application to present + * to the user. + * TODO: formalise this for describing VAMSAS system, a particular + * Vorba client agent, and a particular session. + * @returns string like VamsasClient v.1.1.1 (GPL) and whatever + */ + String getAbout(); + + /** + * TODO: Is this not be the same as the SessionUrn ? + * @return current SessionUrn + */ + public String getSessionUrn(); /** - * Define the methods availabable to a vamsas - * application for interacting with the vamsas - * object broker - * (it's VORBA, not CORBA!) + * Returns a valid URN for other applications to connect to + * the vamsas session. + * @return session handle for this session. */ + public SessionHandle getSessionHandle(); /** - * static methods for returning a new instance - * of vorba with or without a session urn. + * Included for applications with several ClientHandle + * identities. + * @return ClientHandle used to interact with + * other Vamsas applications. */ - Iclient getVorba(String ApplicationHandle); - Iclient getVorba(String ApplicationHandle, String SessionUrn); + public ClientHandle getClientHandle(); /** - * Extend to multi-user. By default is to use current username - * - * Iclient getVorba(String ApplicationHandle, String UserUrn); + * + * @return UserHandle used when interacting + * with other Vamsas applications. */ - + public UserHandle getUserHandle(); /** - * Instance methods + * Method called by client application on exit. + * Vorba will inform other clients if they exist. + * If this is the last application in the session + * then the session will be closed. + * Note: The application should be ready to handle + * 'RequestToCloseDocument' events from the Vorba + * agent in the latter case and so prompt the user + * to save the session locally. + * TODO: pick a better name ? */ + void finalizeClient(); /** - * Return current SessionUrni + * register handler for updates for the current session */ - String getSessionUrn(); + void addDocumentUpdateHandler(EventListener evt); /** - * get vamsas document with app specific data + * get vamsas document with + * user and app specific data */ - VamsasClientDocument getDocument(); + IClientDocument getClientDocument(); /** - * register handler for updates for the current session + * Queue new Vorba objects for storage and propagation + * to other clients (via Event.DOCUMENT_UPDATE based + * notification of document change) */ - void addDocumentUpdateHandler(java.util.EventHandler evt); + void updateDocument(IClientDocument newdoc); /** - * Self-documenting/describing info for presenting to user - * returns string like VamsasClient v.1.1.1 (GPL) and whatever + * Any application may call storeDocument to + * save a local copy of the current vamsas document + * including all application specific entries. + * + * @param location to write zip file */ - String getAboutVamsasClient(); - - void closeVamsasDocument(); - + void storeDocument(java.io.File location); + /** + * Add a listener to a particular event chain. + * See org.vamsas.client.Events for allowed values for EventChain. + * The EventChain value is passed as the propertyName in the java.bean.PropertyChangeEvent + * TODO: build our own vamsas Event/Listener model. + * @param EventChain Name of event. Blank/null registers handler for all events. + * @param evt - event handler function. + */ + void addVorbaEventHandler(String EventChain, PropertyChangeListener evt); } diff --git a/src/org/vamsas/client/IclientFactory.java b/src/org/vamsas/client/IclientFactory.java new file mode 100644 index 0000000..67d62a9 --- /dev/null +++ b/src/org/vamsas/client/IclientFactory.java @@ -0,0 +1,47 @@ +/* + * Created on 13-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.client; + +/** + * Defines methods for instantiating Vorba client application agents + * @author jimp + * + * (it's VORBA, not CORBA!) + */ + + public interface IclientFactory { + + /** + * Create a new Vorba Session + * @param ApplicationHandle is the application's VAMSAS handle string + */ + Iclient getIclient(ClientHandle ApplicationHandle); + /** + * returns new Vorba for a given session. + * @param ApplicationHandle + * @param SessionUrn locates the session that the client should attach to + * @return + */ + Iclient getIclient(ClientHandle ApplicationHandle, String SessionUrn); + /** + * returns new vorba for a given session acting as a particular identity + * @param ApplicationHandle + * @param UserId + * @param SessionUrn + * @return + */ + Iclient getIclient(ClientHandle ApplicationHandle, UserHandle UserId, String SessionUrn); + /** + * New session for application and specific user + * @param ApplicationHandle + * @param UserId + * @return + */ + Iclient getIclient(ClientHandle ApplicationHandle, UserHandle UserId); + + +} diff --git a/src/org/vamsas/client/SessionHandle.java b/src/org/vamsas/client/SessionHandle.java new file mode 100644 index 0000000..1c26bfe --- /dev/null +++ b/src/org/vamsas/client/SessionHandle.java @@ -0,0 +1,31 @@ +/* + * Created on 12-Sep-2005 + * + */ +package org.vamsas.client; + +/** + * Uniquely locates a particular VAMSAS session. + * @author jimp + * + */ +public class SessionHandle { + + /** + * @return Returns the sessionUrn. + */ + public String getSessionUrn() { + return SessionUrn; + } + /** + * @param sessionUrn The sessionUrn to set. + */ + public void setSessionUrn(String sessionUrn) { + SessionUrn = sessionUrn; + } + /** + * The path to the vamsas session file. + */ + String SessionUrn; + +} diff --git a/src/org/vamsas/client/UserHandle.java b/src/org/vamsas/client/UserHandle.java new file mode 100644 index 0000000..0408ae2 --- /dev/null +++ b/src/org/vamsas/client/UserHandle.java @@ -0,0 +1,42 @@ +/* + * Created on 12-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.client; + +/** + * Unique user identifier for a vamsas session. + * Used to write user provenance information, and + * track view/access control in multiuser sessions. + * @author jimp + */ +public class UserHandle { + String fullName; + String Organization; + /** + * @return Returns the fullName. + */ + public String getFullName() { + return fullName; + } + /** + * @param fullName The fullName to set. + */ + public void setFullName(String fullname) { + fullName = fullname; + } + /** + * @return Returns the organization. + */ + public String getOrganization() { + return Organization; + } + /** + * @param organization The organization to set. + */ + public void setOrganization(String organization) { + Organization = organization; + } +} diff --git a/src/org/vamsas/client/VorbaId.java b/src/org/vamsas/client/VorbaId.java new file mode 100644 index 0000000..f1ada9b --- /dev/null +++ b/src/org/vamsas/client/VorbaId.java @@ -0,0 +1,29 @@ +/* + * Created on 12-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.client; + +/** + * The unique reference id for a Vamsas document object, + * used by applications to refer to the vamsas object + * within their own data space in the vamsas document. + * @author jimp + */ +public class VorbaId { + protected String id; + public static VorbaId newId(VorbaIdFactory vorbaObject) { + // Make unique id from appSpace info in vorbaObject + synchronized (vorbaObject) { + return vorbaObject.makeVorbaId(); + } + } + /** + * @return Returns the id. + */ + public String getId() { + return id; + } +} diff --git a/src/org/vamsas/client/VorbaIdFactory.java b/src/org/vamsas/client/VorbaIdFactory.java new file mode 100644 index 0000000..2573310 --- /dev/null +++ b/src/org/vamsas/client/VorbaIdFactory.java @@ -0,0 +1,28 @@ +/* + * Created on 12-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.client; + +/** + * @author jimp + * + * TODO To change the template for this generated type comment go to + * Window - Preferences - Java - Code Style - Code Templates + */ +public interface VorbaIdFactory { + /** + * construct a new id appropriate for this + * client in the vamsas session. + * @return valid VorbaId for session, or null if VorbaIdFactory not configured correctly. + */ + public VorbaId makeVorbaId(); + void setSession(SessionHandle sessionHandle); + public SessionHandle getSession(); + void setClient(ClientHandle appHandle); + public ClientHandle getClient(); + void setUser(UserHandle userHandle); + public UserHandle getUser(); +} diff --git a/src/org/vamsas/client/object.java b/src/org/vamsas/client/object.java index c34d771..9d8bdb4 100644 --- a/src/org/vamsas/client/object.java +++ b/src/org/vamsas/client/object.java @@ -1,10 +1,15 @@ /** - * org.vamsas.client.object * */ - package org.vamsas.client; - +/** + * Base class for all Vamsas objects extracted + * from an IClientDocument. + * An object maybe registered or unregistered. + * + * @author jimp + * + */ public abstract class object { /** @@ -12,17 +17,55 @@ public abstract class object { * allows unambiguous referencing * to any object in the vamsas document */ - - protected String __vorba_id; + protected boolean __stored_in_document=false; + protected VorbaId __vorba__id=null; + protected VorbaIdFactory __vorba=null; + /** + * + * @return true if object is registered + */ + public boolean isRegistered() { + return (__vorba__id!=null); + } /** * Method to get fixed reference for * the object in the vamsas document. + * @returns null if object is neither registered + * or not associated with a properly instantiated + * VorbaIdFactory. */ - public string getVorbaId(); + public String getId() { + if (__vorba__id==null) { + // Try to use the associated factory. + if (__vorba!=null) + if ((__vorba__id = __vorba.makeVorbaId())==null) + return null; // Factory not valid. + else + return null; + } + return __vorba__id.getId(); + } /** * used by the Iclient implementation * to generate unique Id based on * client applications current namespace. */ - protected string setVorbaId(); + protected void setVorbaId(VorbaId newid) { + __vorba__id = newid; + } + + /** + * @return true if object is present in Vamsas Document. + */ + public boolean is__stored_in_document() { + return __stored_in_document; + } + /** + * for use by Vorba agent to reflect state of + * vamsas object to client application. + * @param __stored_in_document The __stored_in_document to set. + */ + protected void set__stored_in_document(boolean __stored_in_document) { + this.__stored_in_document = __stored_in_document; + } } -- 1.7.10.2