From: jprocter <jprocter@compbio.dundee.ac.uk>
Date: Wed, 14 Sep 2005 16:24:26 +0000 (+0000)
Subject: separate some interface methods into abstract classes to enforce access control
X-Git-Tag: Release_0.2~510
X-Git-Url: http://source.jalview.org/gitweb/?a=commitdiff_plain;h=bdf67676f72c1ec0730e07906ae52391d26bbd85;p=vamsas.git

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
---

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 <vamsasSessionURN> <action> [+<arguments>]\n<action> 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
+  }
+}