Group

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> [ mucode overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

mucode
Class Group

java.lang.Object
  mucode.Group

All Implemented Interfaces:: MuConstants

public final class Group
extends java.lang.Object
implements MuConstants

The group is the unit of mobility provided by µCode. A group provides the programmer with a container that can be filled arbitrarily with classes and objects, and shipped altogether to another µServer.

No constructor is provided for this class. Instead, the creation of a group must be requested to a specific µServer, by invoking the method createGroup 55 . This ties a group to a specific µServer, which defines the context where classes are resolved. Thus, for instance, let us assume that a group g has been created by invoking createGroup on a µServer s. If a thread t requests the insertion in g of a class that is not present in the private class space of t, then, according to the rules defined for class loading, the class must be searched in a shared class space, and more precisely in the shared class space associated with s.

Various methods are provided to insert classes in a group. Notably, the methods that specify classes with their class name (e.g., addClass(String) 55 ) rely on the class loader associated to the calling thread, while methods that provide directly the class object (e.g., addClass(Class) 55 ) rely on the class loader that has been originally used to retrieve the class object itself.

Objects inserted in a group must implement the Serializable interface, otherwise a java.io.NotSerializableException will be raised during the group transfer. The process of serializing an object o actually determines the copy of the whole object closure. In other words, o, all the object that are fields of o, the fields of these objects, and so forth are serialized. The programmer can prevent serialization of potentially serializable object fields by declaring them as transient, as explained in the Java Object Serialization specification (that comes with Sun's JDK). Thread objects can be inserted in a group, although their execution state is lost during migration and their execution restarted from scratch at the destination.

After the content of a group has been packaged, the group can be sent at destination by invoking the ship method. There, the classes contained in the group are then inserted in a private class space associated with the group.

Then, the actions taken by the destination µServer are determined by two classes associated with the group: the handler and the root classes.
The handler class is used to instantiate an object responsible for "unpacking" the group and manipulating its contents. Programmers can define their own specialized group handlers (by implementing the GroupHandler interface), and thus define their own relocation primitives. (See for instance the implementation of mucode.abstractions.RelocationHandler and mucode.abstractions.MuAgent.)
The root class provides additional information for handling a group by specifying the class on which the relocation operation must be performed, e.g., to specify which class must be used to spawn a new thread in the destination µServer.

The handler and the root classes can be any class. They can even be the same class, and do not need to be transmitted along with the group (although in this case it is responsibility of the programmer to ensure that they are found at destination). However, in order for the root and handler classes to be correctly instantiated in the target µServer, they must:

be declared as public, and
implement a public, parameterless constructor.

Finally, there are two more methods that affect the way the processing of a group. The method setDynamicLinkSource(String) 55 allows to specify a remote µServer to be used for remote dynamic linking of classes. This way, a group can provide just a subset of the classes required for its handling. If and when additional classes are needed, they will be downloaded from the dynamic link source, and linked by the class loader. Note that classes will be downloaded from the source's shared class space, as the source is identified by a µServer. The default value of the parameter is null, which disables remote dynamic linking altogether.
The method setSynchronousTransfer(boolean) 55 determines whether the group transfer is performed synchronously or asynchronously. In the first case, the operation is blocking for the caller, that is suspended until a return value is received after group handling on the remote µServer. Otherwise, the method returns immediately after group transmission is completed.

Version:: 1.0

Field Summary

(package private) java.util.Hashtable classes
          Holds the objects that will be reconstructed on the destination site.

private java.lang.String dynLink


private java.lang.String handlerClassName


private java.lang.Class handlerClassObj


(package private) java.util.Hashtable objects


private int opCode
          Holds the code for the operation requested on the group.

private java.io.Serializable[] opPars
          Holds a parameter for the operation above.

private java.lang.String rootClassName
          Holds the name of the root of the class hierarchy for to be instantiated in order to construct the thread on the destination site.

private java.lang.Class rootClassObj


private java.lang.String sender


private MuServer server


private boolean synch


Fields inherited from interface mucode.MuConstants

COMPRESSIONkey, DEBUGkey, DYN_LINK, ERRORSkey, GROUP, MESSAGESkey, OK, PACKAGE_NAME, PORTkey, REMOTE_ERROR, SERVER_PORT, TIMEOUT, TIMEOUTkey, UBICLASSESkey, UBIPACKAGESkey, UNKNOWN

Constructor Summary

(package private) Group(MuServer aServer)
          Construct an empty group.

(package private) Group(java.net.Socket clientSocket, boolean compressionON, MuServer aServer)
          Construct a group by reading its content from the specified socket.

(package private) Group(java.lang.String root, java.lang.String handler, MuServer aServer)
          Construct an empty group by assigning root and handler classes.

Method Summary

void addClass(java.lang.Class c)
          Add the given class object to the group.

void addClass(java.lang.String className)
          Add the class with the given name to the group.

private void addClass(java.lang.String className, byte[] bytecode)


void addClasses(java.lang.Class[] classes)
          Add the given class objects to the group.

void addClasses(java.lang.String[] classNames)
          Add the classes with the given names to the group.

java.lang.Object addObject(java.lang.String key, java.lang.Object obj)
          Add an object to the group, assigning a key to it for later retrieval.

java.lang.String[] getClasses()
          Return the names of the classes contained in the group.

MuClassLoader getClassLoader()
          Retrieve the specialized class loader that is handling this group.

ClassSpace getClassSpace()
          Retrieve the (private) class space associated to this group, or null if the group has not yet been migrated.

java.lang.String getDynamicLinkSource()
          Retrieve the address of the µServer from which classes not contained in the group can be retrieved through dynamic linking.

java.lang.Class getHandlerClass()
          Return the handler class object, or null if the group has not yet been migrated.

java.lang.String getHandlerName()
          Return the name of the handler class.

java.lang.Object getObject(java.lang.String key)
          Retrieves the object in the group associated with the specified key.

int getOperation()
          Retrieve the code of the operation that must be performed on the group.

java.lang.Class getRootClass()
          Return the root class object, or null if the group has not yet been migrated.

java.lang.String getRootName()
          Return the name of the root class.

MuServer getServer()
          Return the µServer that is managing this group.

java.lang.String getSource()
          Returns the address (host:port) of the µServer that shipped the group, or null if the group has never been migrated.

boolean isSynchronousTransfer()
          Return true if, after the transfer of a group, the control returns to the caller only after the processing of the group at the destination µServer is ended; false otherwise.

void setDynamicLinkSource(java.lang.String muserver)
          Specifies the address of a µServer from which classes not contained in the group can be retrieved through dynamic linking.

(package private) void setHandler(java.lang.String className)
          Sets the handler class.

void setOperation(int opCode)
          Set the code of the operation that must be performed on the group.

(package private) void setRoot(java.lang.String className)
          Sets the root class.

void setSynchronousTransfer(boolean isSynch)
          If the parameter is true, after the transfer of a group the control returns to the caller only after the processing of the group at the destination µServer is ended; if it is false, the control is returned immediately after the transfer is complete.

int ship(java.lang.String destination)
          Sends a copy of the group to a destination µServer.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

opCode

private int opCode

Holds the code for the operation requested on the group.

opPars

private java.io.Serializable[] opPars

Holds a parameter for the operation above.

rootClassName

private java.lang.String rootClassName

Holds the name of the root of the class hierarchy for to be instantiated in order to construct the thread on the destination site.

handlerClassName

private java.lang.String handlerClassName

classes

java.util.Hashtable classes

Holds the objects that will be reconstructed on the destination site. It may contain objects subclassing from Thread or any arbitrary object. The whole object graph of an object is serialized automatically, i.e., there is no need to insert explicitly objects contents of the objects are serialized TO COMPLETE!!!!

objects

java.util.Hashtable objects

dynLink

private java.lang.String dynLink

synch

private boolean synch

sender

private java.lang.String sender

server

private transient MuServer server

rootClassObj

private transient java.lang.Class rootClassObj

handlerClassObj

private transient java.lang.Class handlerClassObj

Constructor Detail

Group

Group(MuServer aServer)

Construct an empty group.

Group

Group(java.lang.String root,
      java.lang.String handler,
      MuServer aServer)

Construct an empty group by assigning root and handler classes.

Group

Group(java.net.Socket clientSocket,
      boolean compressionON,
      MuServer aServer)
throws DuplicateClassException,
       java.lang.ClassNotFoundException,
       java.io.IOException

Construct a group by reading its content from the specified socket.

Method Detail

getServer

public MuServer getServer()

Return the µServer that is managing this group. If the group is not being unpacked after a transfer, the µServer coincides with the one that created the group. Otherwise, it is the µServer that invoked the unpack 55 method.

getRootClass

public java.lang.Class getRootClass()

Return the root class object, or null if the group has not yet been migrated.

getHandlerClass

public java.lang.Class getHandlerClass()

Return the handler class object, or null if the group has not yet been migrated.

getRootName

public java.lang.String getRootName()

Return the name of the root class.

getHandlerName

public java.lang.String getHandlerName()

Return the name of the handler class.

getDynamicLinkSource

public java.lang.String getDynamicLinkSource()

Retrieve the address of the µServer from which classes not contained in the group can be retrieved through dynamic linking. If null, remote dynamic linking is not allowed.

setDynamicLinkSource

public void setDynamicLinkSource(java.lang.String muserver)

Specifies the address of a µServer from which classes not contained in the group can be retrieved through dynamic linking. If null, remote dynamic linking is not allowed.

isSynchronousTransfer

public boolean isSynchronousTransfer()

Return true if, after the transfer of a group, the control returns to the caller only after the processing of the group at the destination µServer is ended; false otherwise.

setSynchronousTransfer

public void setSynchronousTransfer(boolean isSynch)

If the parameter is true, after the transfer of a group the control returns to the caller only after the processing of the group at the destination µServer is ended; if it is false, the control is returned immediately after the transfer is complete.

setOperation

public void setOperation(int opCode)

Set the code of the operation that must be performed on the group. Useful for programmers writing their own relocation primitives.

getOperation

public int getOperation()

Retrieve the code of the operation that must be performed on the group. Useful for programmers writing their own relocation primitives.

getObject

public java.lang.Object getObject(java.lang.String key)

Retrieves the object in the group associated with the specified key. Useful in the implementation of a group handler.

addObject

public java.lang.Object addObject(java.lang.String key,
                                  java.lang.Object obj)

Add an object to the group, assigning a key to it for later retrieval. Neither the key nor the value can be null. If a key already exists, the old object is overwritten by the new one.

addClass

public void addClass(java.lang.String className)
              throws java.lang.ClassNotFoundException

Add the class with the given name to the group. The byte code for the class is retrieved using the current class loader, i.e., the one used for the current thread.
Class loading follows the rules described in the documentation of ClassSpace. If the class definition relies on other classes, it is responsibility of the programmer to ensure that either these classes are sent along within the group, or are available on the destination site, or can be retrieved through remote dynamic linking.

addClass

public void addClass(java.lang.Class c)
              throws java.lang.ClassNotFoundException

Add the given class object to the group. The byte code for the class is retrieved using the class loader that originally loaded it.
Class loading follows the rules described in the documentation of ClassSpace. If the class definition relies on other classes, it is responsibility of the programmer to ensure that either these classes are sent along within the group, or are available on the destination site, or can be retrieved through remote dynamic linking.

addClass

private void addClass(java.lang.String className,
                      byte[] bytecode)

addClasses

public void addClasses(java.lang.String[] classNames)
                throws java.lang.ClassNotFoundException

Add the classes with the given names to the group. The byte code for the classes is retrieved using the current class loader, i.e., the one used for the current thread.
Class loading follows the rules described in the documentation of ClassSpace. If the class definition relies on other classes, it is responsibility of the programmer to ensure that either these classes are sent along within the group, or are available on the destination site, or can be retrieved through remote dynamic linking.

addClasses

public void addClasses(java.lang.Class[] classes)
                throws java.lang.ClassNotFoundException

Add the given class objects to the group. The byte code for the classes is retrieved using the class loader that originally loaded them.
Class loading follows the rules described in the documentation of ClassSpace. If the class definition relies on other classes, it is responsibility of the programmer to ensure that either these classes are sent along within the group, or are available on the destination site, or can be retrieved through remote dynamic linking.

getClasses

public java.lang.String[] getClasses()

Return the names of the classes contained in the group.

getClassLoader

public MuClassLoader getClassLoader()

Retrieve the specialized class loader that is handling this group. If such class loader is the system class loader, this is wrapped into (and accessible through) a MuClassLoader object.

getClassSpace

public ClassSpace getClassSpace()

Retrieve the (private) class space associated to this group, or null if the group has not yet been migrated.

getSource

public java.lang.String getSource()

Returns the address (host:port) of the µServer that shipped the group, or null if the group has never been migrated.

ship

public int ship(java.lang.String destination)
         throws java.io.IOException,
                java.lang.ClassNotFoundException

Sends a copy of the group to a destination µServer.

setRoot

void setRoot(java.lang.String className)

Sets the root class.

setHandler

void setHandler(java.lang.String className)

Sets the handler class.

Overview

Package

Class

Use

Deprecated

Index

Home >> All >> [ mucode overview ]

PREV CLASS NEXT CLASS

SUMMARY:

JAVADOC |

SOURCE |

DOWNLOAD | NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Field Summary
`(package private) java.util.Hashtable`	`classes` Holds the objects that will be reconstructed on the destination site.
`private java.lang.String`	`dynLink`
`private java.lang.String`	`handlerClassName`
`private java.lang.Class`	`handlerClassObj`
`(package private) java.util.Hashtable`	`objects`
`private int`	`opCode` Holds the code for the operation requested on the group.
`private java.io.Serializable[]`	`opPars` Holds a parameter for the operation above.
`private java.lang.String`	`rootClassName` Holds the name of the root of the class hierarchy for to be instantiated in order to construct the thread on the destination site.
`private java.lang.Class`	`rootClassObj`
`private java.lang.String`	`sender`
`private MuServer`	`server`
`private boolean`	`synch`

Constructor Summary
`(package private)`	`Group(MuServer aServer)` Construct an empty group.
`(package private)`	`Group(java.net.Socket clientSocket, boolean compressionON, MuServer aServer)` Construct a group by reading its content from the specified socket.
`(package private)`	`Group(java.lang.String root, java.lang.String handler, MuServer aServer)` Construct an empty group by assigning root and handler classes.

Method Summary
`void`	`addClass(java.lang.Class c)` Add the given class object to the group.
`void`	`addClass(java.lang.String className)` Add the class with the given name to the group.
`private void`	`addClass(java.lang.String className, byte[] bytecode)`
`void`	`addClasses(java.lang.Class[] classes)` Add the given class objects to the group.
`void`	`addClasses(java.lang.String[] classNames)` Add the classes with the given names to the group.
`java.lang.Object`	`addObject(java.lang.String key, java.lang.Object obj)` Add an object to the group, assigning a key to it for later retrieval.
`java.lang.String[]`	`getClasses()` Return the names of the classes contained in the group.
`MuClassLoader`	`getClassLoader()` Retrieve the specialized class loader that is handling this group.
`ClassSpace`	`getClassSpace()` Retrieve the (private) class space associated to this group, or `null` if the group has not yet been migrated.
`java.lang.String`	`getDynamicLinkSource()` Retrieve the address of the µServer from which classes not contained in the group can be retrieved through dynamic linking.
`java.lang.Class`	`getHandlerClass()` Return the handler class object, or `null` if the group has not yet been migrated.
`java.lang.String`	`getHandlerName()` Return the name of the handler class.
`java.lang.Object`	`getObject(java.lang.String key)` Retrieves the object in the group associated with the specified key.
`int`	`getOperation()` Retrieve the code of the operation that must be performed on the group.
`java.lang.Class`	`getRootClass()` Return the root class object, or `null` if the group has not yet been migrated.
`java.lang.String`	`getRootName()` Return the name of the root class.
`MuServer`	`getServer()` Return the µServer that is managing this group.
`java.lang.String`	`getSource()` Returns the address (`host:port`) of the µServer that shipped the group, or `null` if the group has never been migrated.
`boolean`	`isSynchronousTransfer()` Return `true` if, after the transfer of a group, the control returns to the caller only after the processing of the group at the destination µServer is ended; `false` otherwise.
`void`	`setDynamicLinkSource(java.lang.String muserver)` Specifies the address of a µServer from which classes not contained in the group can be retrieved through dynamic linking.
`(package private) void`	`setHandler(java.lang.String className)` Sets the handler class.
`void`	`setOperation(int opCode)` Set the code of the operation that must be performed on the group.
`(package private) void`	`setRoot(java.lang.String className)` Sets the root class.
`void`	`setSynchronousTransfer(boolean isSynch)` If the parameter is `true`, after the transfer of a group the control returns to the caller only after the processing of the group at the destination µServer is ended; if it is `false`, the control is returned immediately after the transfer is complete.
`int`	`ship(java.lang.String destination)` Sends a copy of the group to a destination µServer.

mucode Class Group

opCode

opPars

rootClassName

handlerClassName

classes

objects

dynLink

synch

sender

server

rootClassObj

handlerClassObj

Group

Group

Group

getServer

getRootClass

getHandlerClass

getRootName

getHandlerName

getDynamicLinkSource

setDynamicLinkSource

isSynchronousTransfer

setSynchronousTransfer

setOperation

getOperation

getObject

addObject

addClass

addClass

addClass

addClasses

addClasses

getClasses

getClassLoader

getClassSpace

getSource

ship

setRoot

setHandler

mucode
Class Group