br.shob
Class SharedSpace

java.lang.Object
  |
  +--br.shob.SharedSpace

public class SharedSpace
extends Object

This class represents a connection to the global space in wich the objects are shared. Clients can share objects to other and get copies of objects shared in the global space. The idea is that once you share or get the object you interact with it through a SharedReference implementation (or subclass). Each SharedSpace instance has its own CommLayer, so a client can communicate with multiple server at once.

Version:
$Revision: 1.16 $
Author:
crolmos, dukejeffrie
See Also:
SharedReference, SharedObject
Created:
December 4, 2001

Nested Class Summary
protected static class SharedSpace.Validator
          Description of the Class
 
Constructor Summary
SharedSpace(String hostname, int port)
          Creates a new SharedSpace instance
 
Method Summary
 void addCacheListener(String globalName, StorageListener listener)
          Adds a StorageListener that listens on the cached objects storage.
 void addOwnedListener(String globalName, StorageListener listener)
          Adds a StorageListener that listens on the owned objects storage.
protected  void beginTrans(SharedReference reference)
          This method should not be called directly.
protected  void commit(SharedReference reference)
          This method should not be called directly.
 void connect(String hostname, int port)
          Conects whith the specified server.
 void disconnect()
          Disconnects from the server.
 SharedReference get(String globalName)
          Returns a SharedReference for a shared object.
 Set getCachedNames()
          Gets the cachedNames attribute of the SharedSpace object
 SharedObject getCachedObject(String globalName)
          This method should not be called by user applications.
 List getExternalDescriptors()
          Returns a list of all the objects cached by this SharedSpace .
 List getInternalDescriptors()
          Returns a list of all the objects shared by this SharedSpace .
 Logger getLogger()
          Gets the logger attribute of the SharedSpace object
 SharedObject getObject(String globalName)
          This method should not be called by user applications
 SharedReference getReference(SharedObject obj)
          Gets the reference attribute of the SharedSpace object
protected  SharedReference getRemote(String globalName)
          This method should not be called by user applications
 byte[] getRemoteClassArray(String globalName, String className)
          Gets a byte array with the class definition for className , downloading it from the owner of globalName .
 boolean isConnected()
          Checks if this SharedSpace instance is connected to a server
 boolean isDebugging()
          Gets the debugging flag of the SharedSpace object
protected  void lock(String globalName)
          This method should not be called directly.
 void put(SharedObject obj)
          This method should not be called by user applications.
protected  void remove(String globalName)
          This method should not be called.
 void removeCacheListener(String globalName, StorageListener listener)
          Removes a StorageListener that listens on the cached objects storage.
 void removeOwnedListener(String globalName, StorageListener listener)
          Removes a StorageListener that listens on the owned objects storage.
protected  void rollback(SharedReference reference)
          This method should not be called directly.
 void setDebugging(boolean flag)
          Sets the debugging flag of the SharedSpace object
 void setLogger(Logger logger)
          Sets the logger attribute of the SharedSpace object
 SharedReference share(String globalName, Serializable data)
          Shares an object with the specified globalName.
 SharedReference share(String globalName, Serializable data, String referenceClassName)
          Shares an object with the specified globalName.
protected  void unlock(String globalName)
          This method should not be called directly.
protected  void unshare(SharedReference reference)
          This method should not be called directly.
protected  void validate(SharedReference reference)
          This method should not be called directly.
protected  void validate(String globalName)
          This method should not be called directly.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SharedSpace

public SharedSpace(String hostname,
                   int port)
            throws ShobException
Creates a new SharedSpace instance

Parameters:
hostname - the host where this object will be listening.
port - the port in which this object will be listening.
Throws:
ShobException - Description of the Exception
Method Detail

addCacheListener

public void addCacheListener(String globalName,
                             StorageListener listener)
Adds a StorageListener that listens on the cached objects storage.

Parameters:
globalName - the global name that the listener wants to listen to
listener - The listener to be added

addOwnedListener

public void addOwnedListener(String globalName,
                             StorageListener listener)
Adds a StorageListener that listens on the owned objects storage.

Parameters:
globalName - the global name that the listener wants to listen to
listener - The listener to be added

connect

public void connect(String hostname,
                    int port)
             throws ShobException,
                    AlreadyLoggedInException
Conects whith the specified server.

Parameters:
hostname - the hostname of the server.
port - the port used for login.
Throws:
ShobException - thrown when an unexpected error occurs
AlreadyLoggedInException - if this SharedSpace is already logged to the server

disconnect

public void disconnect()
                throws ShobException,
                       NotLoggedInException
Disconnects from the server.

Throws:
ShobException - thrown when an unexpected error occurs
NotLoggedInException - if this SharedSpace is not logged to the server

get

public SharedReference get(String globalName)
                    throws ShobException,
                           NotSharedException
Returns a SharedReference for a shared object.

Parameters:
globalName - the global name of the object.
Returns:
a SharedReference for this object.
Throws:
ShobException - Description of the Exception
NotSharedException - Description of the Exception

getCachedNames

public Set getCachedNames()
Gets the cachedNames attribute of the SharedSpace object

Returns:
The cachedNames value

getCachedObject

public SharedObject getCachedObject(String globalName)
This method should not be called by user applications.

Parameters:
globalName - Description of the Parameter
Returns:
The cachedObject value

getExternalDescriptors

public List getExternalDescriptors()
                            throws ShobException
Returns a list of all the objects cached by this SharedSpace .

Returns:
the list of external descriptors
Throws:
ShobException - thrown when an unexpected error occurs

getInternalDescriptors

public List getInternalDescriptors()
                            throws ShobException
Returns a list of all the objects shared by this SharedSpace .

Returns:
The list of internal descriptors
Throws:
ShobException - thrown when an unexpected error occurs

getLogger

public Logger getLogger()
Gets the logger attribute of the SharedSpace object

Returns:
The logger value

getObject

public SharedObject getObject(String globalName)
This method should not be called by user applications

Parameters:
globalName - Description of the Parameter
Returns:
The object value

getReference

public SharedReference getReference(SharedObject obj)
Gets the reference attribute of the SharedSpace object

Parameters:
obj - Description of the Parameter
Returns:
The reference value

getRemoteClassArray

public byte[] getRemoteClassArray(String globalName,
                                  String className)
                           throws ShobException
Gets a byte array with the class definition for className , downloading it from the owner of globalName . See the documentation on remote class downloading

Parameters:
globalName - Description of the Parameter
className - Description of the Parameter
Returns:
The remoteClass value
Throws:
ShobException - thrown when an unexpected error occurs

isConnected

public boolean isConnected()
Checks if this SharedSpace instance is connected to a server

Returns:
true if its CommLayer is connected, false otherwise.
See Also:
ClientCommLayer.isLoggedIn()

isDebugging

public boolean isDebugging()
Gets the debugging flag of the SharedSpace object

Returns:
The debugging value

put

public void put(SharedObject obj)
This method should not be called by user applications. It puts a SharedObject into the owned objects map

Parameters:
obj - the shared object to be put in

removeCacheListener

public void removeCacheListener(String globalName,
                                StorageListener listener)
Removes a StorageListener that listens on the cached objects storage.

Parameters:
globalName - the global name that the listener wants to listen to
listener - The listener to be removed

removeOwnedListener

public void removeOwnedListener(String globalName,
                                StorageListener listener)
Removes a StorageListener that listens on the owned objects storage.

Parameters:
globalName - the global name that the listener wants to listen to
listener - The listener to be removed

setDebugging

public void setDebugging(boolean flag)
Sets the debugging flag of the SharedSpace object

Parameters:
flag - The new debugging value

setLogger

public void setLogger(Logger logger)
Sets the logger attribute of the SharedSpace object

Parameters:
logger - The new logger value

share

public SharedReference share(String globalName,
                             Serializable data,
                             String referenceClassName)
                      throws ShobException,
                             AlreadySharedException
Shares an object with the specified globalName.

Parameters:
globalName - the global name of the shared object.
data - the object to be shared.
referenceClassName - the class of the SharedReference that should be returned when the method get is called.
Returns:
a shared reference for this object.
Throws:
ShobException - thrown when an unexpected error occurs
AlreadySharedException - thrown when the object is alread shared

share

public SharedReference share(String globalName,
                             Serializable data)
                      throws ShobException,
                             AlreadySharedException
Shares an object with the specified globalName.

Parameters:
globalName - the global name of the shared object.
data - the object to be shared.
Returns:
a shared reference for this object.
Throws:
ShobException - thrown when an unexpected error occurs
AlreadySharedException - when the object is already shared

beginTrans

protected void beginTrans(SharedReference reference)
                   throws ShobException,
                          AlreadyLockedException
This method should not be called directly. It begins a transaction on the object referenced by the parameter.

Parameters:
reference - a SharedReference instance
Throws:
ShobException - thrown when an unexpected error occurs
AlreadyLockedException - when the object is already locked

commit

protected void commit(SharedReference reference)
               throws ShobException,
                      NotLockedException
This method should not be called directly. It commits a transaction started on the object referenced by the parameter

Parameters:
reference - A SharedReference instance
Throws:
ShobException - thrown when an unexpected error occurs
NotLockedException - when the object is not locked

getRemote

protected SharedReference getRemote(String globalName)
                             throws ShobException
This method should not be called by user applications

Parameters:
globalName - the global name of a shared object
Returns:
a reference to the shared object
Throws:
ShobException - thrown when an unexpected error occurs

lock

protected void lock(String globalName)
This method should not be called directly. It locks a shared object owned by this instance

Parameters:
globalName - Description of the Parameter

remove

protected void remove(String globalName)
This method should not be called. It removes an object from the "owned" list

Parameters:
globalName - Description of the Parameter

rollback

protected void rollback(SharedReference reference)
                 throws ShobException,
                        NotLockedException
This method should not be called directly. It rolls back a transaction started on the sharedobject referenced by the parameter

Parameters:
reference - a SharedReference instance
Throws:
ShobException - thrown when an unexpected error occurs
NotLockedException - when the object is not locked

unlock

protected void unlock(String globalName)
This method should not be called directly. It removes the synchronization lock used by this SharedSpace instance

Parameters:
globalName - Description of the Parameter

unshare

protected void unshare(SharedReference reference)
                throws ShobException
This method should not be called directly. It unshares an object owned by this instance

Parameters:
reference - Description of the Parameter
Throws:
ShobException - thrown when an unexpected error occurs

validate

protected void validate(SharedReference reference)
                 throws ShobException
This method should not be called directly. It validates the cached copy of the object referenced by the parameter

Parameters:
reference - a SharedReference instance
Throws:
ShobException - thrown when an unexpected error occurs

validate

protected void validate(String globalName)
                 throws ShobException
This method should not be called directly. It validates the cached copy of the object referenced by the parameter

Parameters:
globalName - Description of the Parameter
Throws:
ShobException - thrown when an unexpected error occurs