From bdf67676f72c1ec0730e07906ae52391d26bbd85 Mon Sep 17 00:00:00 2001 From: jprocter Date: Wed, 14 Sep 2005 16:24:26 +0000 Subject: [PATCH] separate some interface methods into abstract classes to enforce access control git-svn-id: https://svn.lifesci.dundee.ac.uk/svn/repository/trunk@10 be28352e-c001-0410-b1a7-c7978e42abec --- src/org/vamsas/client/ClientDocument.java | 53 ++++++++++++++- src/org/vamsas/client/Events.java | 10 +-- src/org/vamsas/client/IClient.java | 97 +++++++++++++++++++++++++++ src/org/vamsas/client/IVorbaIdFactory.java | 29 ++++++++ src/org/vamsas/client/VorbaId.java | 9 ++- src/org/vamsas/client/VorbaIdFactory.java | 40 +++++++---- src/org/vamsas/client/object.java | 2 +- src/org/vamsas/test/ExampleApplication.java | 35 ++++++++++ 8 files changed, 252 insertions(+), 23 deletions(-) create mode 100644 src/org/vamsas/client/IClient.java create mode 100644 src/org/vamsas/client/IVorbaIdFactory.java create mode 100644 src/org/vamsas/test/ExampleApplication.java diff --git a/src/org/vamsas/client/ClientDocument.java b/src/org/vamsas/client/ClientDocument.java index 85014e0..4a78bd4 100644 --- a/src/org/vamsas/client/ClientDocument.java +++ b/src/org/vamsas/client/ClientDocument.java @@ -3,7 +3,7 @@ */ package org.vamsas.client; -import java.util.Vector; +import java.util.Hashtable; /** * @author jimp @@ -11,9 +11,58 @@ import java.util.Vector; * to a specified ClientHandle's information. */ public class ClientDocument implements IClientDocument { + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#getApplicationData() + */ + public byte[] getApplicationData() { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#getObject(org.vamsas.client.VorbaId) + */ + public object getObject(VorbaId id) { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#getObjects(org.vamsas.client.VorbaId[]) + */ + public object[] getObjects(VorbaId[] ids) { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#getVamsasRoots() + */ + public object[] getVamsasRoots() { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#registerObject(org.vamsas.client.object) + */ + public VorbaId registerObject(object unregistered) { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#registerObjects(org.vamsas.client.object[]) + */ + public VorbaId[] registerObjects(object[] unregistered) { + // TODO Auto-generated method stub + return null; + } + /* (non-Javadoc) + * @see org.vamsas.client.IClientDocument#setApplicationData(byte[]) + */ + public void setApplicationData(byte[] newData) { + // TODO Auto-generated method stub + + } /** * collection of org.vamsas.client.objects */ - Vector VamsasObjects; + Hashtable VamsasObjects; byte[] appData; } diff --git a/src/org/vamsas/client/Events.java b/src/org/vamsas/client/Events.java index 2532427..277316d 100644 --- a/src/org/vamsas/client/Events.java +++ b/src/org/vamsas/client/Events.java @@ -9,25 +9,25 @@ public class Events { * 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"; + public static final String DOCUMENT_UPDATE="org.vamsas.client.events.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"; + public static final String DOCUMENT_CREATE="org.vamsas.client.events.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"; + public static final String CLIENT_CREATION="org.vamsas.client.events.clientCreateEvent"; /** * Generated when a vamsas client leaves a session (Handle is passed). */ - public static final String CLIENT_FINALIZATION="org.vamsas.client.clientFinalizationEvent"; + public static final String CLIENT_FINALIZATION="org.vamsas.client.events.clientFinalizationEvent"; /** * Generated prior to session Shutdown, after the last participating vamsas client has finalized. */ - public static final String SESSION_SHUTDOWN="org.vamsas.client.SessionShutdownEvent"; + public static final String SESSION_SHUTDOWN="org.vamsas.client.events.SessionShutdownEvent"; /** * Generated by Vorba stub after the penultimate client makes a call to closeDocument(). * Sequence is as follows : diff --git a/src/org/vamsas/client/IClient.java b/src/org/vamsas/client/IClient.java new file mode 100644 index 0000000..ae7f175 --- /dev/null +++ b/src/org/vamsas/client/IClient.java @@ -0,0 +1,97 @@ +/** + * org.vamsas.client.IClient + * + */ +package org.vamsas.client; + +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 + */ + public String getAbout(); + + /** + * TODO: Is this not be the same as the SessionUrn ? + * @return current SessionUrn + */ + public String getSessionUrn(); + /** + * Returns a valid URN for other applications to connect to + * the vamsas session. + * @return session handle for this session. + */ + public SessionHandle getSessionHandle(); + /** + * Included for applications with several ClientHandle + * identities. + * @return ClientHandle used to interact with + * other Vamsas applications. + */ + public ClientHandle getClientHandle(); + /** + * + * @return UserHandle used when interacting + * with other Vamsas applications. + */ + public UserHandle getUserHandle(); + /** + * 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 ? + */ + public void finalizeClient(); + /** + * register handler for updates for the current session + */ + public void addDocumentUpdateHandler(EventListener evt); + /** + * get vamsas document with + * user and app specific data + */ + public IClientDocument getClientDocument(); + /** + * Queue new Vorba objects for storage and propagation + * to other clients (via Event.DOCUMENT_UPDATE based + * notification of document change) + */ + public void updateDocument(IClientDocument newdoc); + /** + * 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 + */ + public 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. + */ + public void addVorbaEventHandler(String EventChain, PropertyChangeListener evt); +} diff --git a/src/org/vamsas/client/IVorbaIdFactory.java b/src/org/vamsas/client/IVorbaIdFactory.java new file mode 100644 index 0000000..3107378 --- /dev/null +++ b/src/org/vamsas/client/IVorbaIdFactory.java @@ -0,0 +1,29 @@ +/* + * Created on 14-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 IVorbaIdFactory { + /** + * 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 abstract VorbaId makeVorbaId(); + + public abstract SessionHandle getSession(); + + public abstract ClientHandle getClient(); + + public abstract UserHandle getUser(); +} \ No newline at end of file diff --git a/src/org/vamsas/client/VorbaId.java b/src/org/vamsas/client/VorbaId.java index f1ada9b..bc0fd37 100644 --- a/src/org/vamsas/client/VorbaId.java +++ b/src/org/vamsas/client/VorbaId.java @@ -10,11 +10,18 @@ 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. + * TODO: decide if VorbaId should contain a reference + * to either the IVorbaIdFactory that made it or the + * IClient that defines the session (it might be + * convenient). * @author jimp */ public class VorbaId { protected String id; - public static VorbaId newId(VorbaIdFactory vorbaObject) { + private VorbaId(String Id) { + id = Id; + } + protected static VorbaId newId(IVorbaIdFactory vorbaObject) { // Make unique id from appSpace info in vorbaObject synchronized (vorbaObject) { return vorbaObject.makeVorbaId(); diff --git a/src/org/vamsas/client/VorbaIdFactory.java b/src/org/vamsas/client/VorbaIdFactory.java index 2573310..9207e45 100644 --- a/src/org/vamsas/client/VorbaIdFactory.java +++ b/src/org/vamsas/client/VorbaIdFactory.java @@ -7,22 +7,34 @@ package org.vamsas.client; /** + * A VorbaIdFactory is constructed by an IClient instance. + * It guarantees that any new VorbaId objects are unique + * within the VAMSAS session. + * * @author jimp - * - * TODO To change the template for this generated type comment go to - * Window - Preferences - Java - Code Style - Code Templates */ -public interface VorbaIdFactory { +public abstract class VorbaIdFactory implements IVorbaIdFactory { /** - * construct a new id appropriate for this - * client in the vamsas session. - * @return valid VorbaId for session, or null if VorbaIdFactory not configured correctly. + * 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(); + public abstract VorbaId makeVorbaId(); + /** + * TODO: decide if these are needed. + * + * @param sessionHandle + */ + protected abstract void setSession(SessionHandle sessionhandle); + + public abstract SessionHandle getSession(); + + protected abstract void setClient(ClientHandle appHandle); + + public abstract ClientHandle getClient(); + + protected abstract void setUser(UserHandle userHandle); + + public abstract UserHandle getUser(); } diff --git a/src/org/vamsas/client/object.java b/src/org/vamsas/client/object.java index c1a13da..8fbb2e8 100644 --- a/src/org/vamsas/client/object.java +++ b/src/org/vamsas/client/object.java @@ -19,7 +19,7 @@ public abstract class object { */ protected boolean __stored_in_document=false; protected VorbaId __vorba__id=null; - protected VorbaIdFactory __vorba=null; + protected IVorbaIdFactory __vorba=null; /** * * @return true if object is registered diff --git a/src/org/vamsas/test/ExampleApplication.java b/src/org/vamsas/test/ExampleApplication.java new file mode 100644 index 0000000..a0c1ec2 --- /dev/null +++ b/src/org/vamsas/test/ExampleApplication.java @@ -0,0 +1,35 @@ +/* + * Created on 14-Sep-2005 + * + * TODO To change the template for this generated file go to + * Window - Preferences - Java - Code Style - Code Templates + */ +package org.vamsas.test; + +/** + * Toy vamsas client application demonstrating the API. + * + * @author jimp + */ + +public class ExampleApplication { + public static String Usage="ExampleApplication [+]\n is one of :"; + private static boolean parseArgs(String args[]) { + return true; // incorrect arguments. + } + public static void main(String[] args) { + if ((args.length<=1) || parseArgs(args)) { + System.err.print(Usage); + } + // get IClientFactory + // get an Iclient with session data + // register an update listener and a close listener. + // get document data + // do something with data + // , update document, or something. + // .. + // call finalizeClient + // { meanwhile, eventHandlers are called to do any saves if need be } + // finish + } +} -- 1.7.10.2