--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<classpath>
+ <classpathentry kind="src" path="src"/>
+ <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
+ <classpathentry kind="output" path="classes"/>
+</classpath>
--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+ <name>VamsasClient</name>
+ <comment></comment>
+ <projects>
+ </projects>
+ <buildSpec>
+ <buildCommand>
+ <name>org.eclipse.jdt.core.javabuilder</name>
+ <arguments>
+ </arguments>
+ </buildCommand>
+ </buildSpec>
+ <natures>
+ <nature>org.eclipse.jdt.core.javanature</nature>
+ </natures>
+</projectDescription>
-<xml version="1.0" />
- <project name="vamsas-client" default="build" basedir=".">
- <target name="init">
- <property name="libDir" value="lib"/>
+<?xml version="1.0"?>
+<project name="vamsas-client" default="build" basedir=".">
+ <target name="init">
+ <property name="libDir" value="lib"/>
<property name="resourceDir" value="resources"/>
<property name="sourceDir" value="src" />
<property name="outputDir" value="classes" />
- <property name="packageDir" value="packages" />
-
+ <property name="packageDir" value="packages" />
+
<!--
Build classpath
-->
<include name="*.jar"/>
<include name="**/*.jar"/>
</fileset>
- <!-- <path refid="axis.classpath"/> --->
+ <!-- path refid="axis.classpath" -->
</path>
- </target>
-
+ </target>
+
<target name="prepare" depends="init">
- <mkdir dir="${packageDir}"/>
- <mkdir dir="${outputDir}"/>
+ <mkdir dir="${packageDir}"/>
+ <mkdir dir="${outputDir}"/>
<copy todir="${outputDir}">
<fileset dir="${resourceDir}" />
</copy>
</target>
- <target name="clean" depends="init">
- <delete>
- <fileset dir="${outputDir}">
- <include name="*"/>
- <include name="*.*"/>
- <include name="**/*"/>
- <include name="**/*.*"/>
- </fileset>
- </delete>
- <delete dir="${axisbuild}"/>
-<!-- <ant dir="test" antfile="build.xml" target="clean"
+ <target name="clean" depends="init">
+ <delete>
+ <fileset dir="${outputDir}">
+ <include name="*"/>
+ <include name="*.*"/>
+ <include name="**/*"/>
+ <include name="**/*.*"/>
+ </fileset>
+ </delete>
+ <delete dir="${axisbuild}"/>
+ <!-- <ant dir="test" antfile="build.xml" target="clean"
inheritRefs="true"/> -->
- </target>
- <target name="realclean" depends="init, clean">
+ </target>
+ <target name="realclean" depends="init, clean">
<delete dir="${packageDir}"/>
- </target>
- <target name="distclean" depends="init, realclean">
- <echo message="REMOVING ALL BACKUP/AUTOSAVES!"/>
- <delete>
- <fileset dir=".">
- <include name="#*#"/>
- <include name="#*.*#"/>
- <include name="**/#*#"/>
- <include name="**/#*.*#"/>
- <include name="*~"/>
- <include name="*.*~"/>
- <include name="**/*~"/>
- <include name="**/*.*~"/>
- </fileset>
- </delete>
+ </target>
+ <target name="distclean" depends="init, realclean">
+ <echo message="REMOVING ALL BACKUP/AUTOSAVES!"/>
+ <delete>
+ <fileset dir=".">
+ <include name="#*#"/>
+ <include name="#*.*#"/>
+ <include name="**/#*#"/>
+ <include name="**/#*.*#"/>
+ <include name="*~"/>
+ <include name="*.*~"/>
+ <include name="**/*~"/>
+ <include name="**/*.*~"/>
+ </fileset>
+ </delete>
</target>
<target name="build" depends="init, prepare">
- <!-- not efficient yet. : use excludes="*/localtest/*.java" if local tests are not building -->
- <javac classpathref="build.classpath" debug="on" srcdir="${sourceDir}" destdir="${outputDir}" />
+ <!-- not efficient yet. : use excludes="*/localtest/*.java" if local tests are not building -->
+ <javac classpathref="build.classpath" debug="on" srcdir="${sourceDir}" destdir="${outputDir}" />
</target>
- </project>
+</project>
--- /dev/null
+/*
+ *
+ */
+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;
+}
--- /dev/null
+/*
+ */
+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;
+ }
+}
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";
}
--- /dev/null
+/*
+ * 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
* 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
*
*/
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);
}
--- /dev/null
+/*
+ * 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);
+
+
+}
--- /dev/null
+/*
+ * 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;
+
+}
--- /dev/null
+/*
+ * 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;
+ }
+}
--- /dev/null
+/*
+ * 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;
+ }
+}
--- /dev/null
+/*
+ * 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();
+}
/**
- * 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 {
/**
* 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;
+ }
}
git://source.jalview.org / vamsas.git / commitdiff