org.objectweb.fractal.rmi.stub
Class RmiStubFactory

java.lang.Object
  org.objectweb.fractal.rmi.stub.RmiStubFactory

All Implemented Interfaces:

org.objectweb.asm.Opcodes, org.objectweb.fractal.api.control.BindingController, SkeletonFactory, StubFactory

public class RmiStubFactory
extends java.lang.Object
implements org.objectweb.asm.Opcodes, StubFactory, SkeletonFactory, org.objectweb.fractal.api.control.BindingController

A stub and skeleton factory based on ASM. This factory generates the stub and skeleton classes dynamically, when they are needed. It is therefore not necessary for the user to statically generate these classes with a tool such as rmic or idlc.
The stubs and skeletons created by this factory marshall and unmarshall the method invocations by using the following format: a method invocation message contains a four bytes method index, which uniquely and unambiguously identifies a method among the methods provided by a Java interface, followed by the method's arguments, marshalled in the order of their declaration in the method's signature.

In order to be able to manually generate stubs and skeletons before execution and avoid their generation at runtime (typically for performance reasons, although no real testing has been performed), this class can be used as a kind of a stub compiler through its main method, giving as arguments the Java interfaces you want to compile stubs for. Note that this generation is performed at byte code level only, i.e. it takes compiled interfaces as input and generates compiled stubs and skeletons classes. In other words, the interfaces (fully-qualified) names you specify must be compiled and reachable in the classpath, and the result is a corresponding set of stub and skeleton compiled classes (taking current directory as base directory).

Field Summary

protected org.objectweb.util.monolog.api.Logger	logger The logger used to log messages.
protected org.objectweb.util.monolog.api.LoggerFactory	loggerFactory The optional logger factory used to get a logger for this component.
protected MarshallerFactory	marshallerFactory The marshaller factory to be used by the stubs created by this factory.

Fields inherited from interface org.objectweb.asm.Opcodes

AALOAD, AASTORE, ACC_ABSTRACT, ACC_ANNOTATION, ACC_BRIDGE, ACC_DEPRECATED, ACC_ENUM, ACC_FINAL, ACC_INTERFACE, ACC_NATIVE, ACC_PRIVATE, ACC_PROTECTED, ACC_PUBLIC, ACC_STATIC, ACC_STRICT, ACC_SUPER, ACC_SYNCHRONIZED, ACC_SYNTHETIC, ACC_TRANSIENT, ACC_VARARGS, ACC_VOLATILE, ACONST_NULL, ALOAD, ANEWARRAY, ARETURN, ARRAYLENGTH, ASTORE, ATHROW, BALOAD, BASTORE, BIPUSH, CALOAD, CASTORE, CHECKCAST, D2F, D2I, D2L, DADD, DALOAD, DASTORE, DCMPG, DCMPL, DCONST_0, DCONST_1, DDIV, DLOAD, DMUL, DNEG, DREM, DRETURN, DSTORE, DSUB, DUP, DUP_X1, DUP_X2, DUP2, DUP2_X1, DUP2_X2, F2D, F2I, F2L, FADD, FALOAD, FASTORE, FCMPG, FCMPL, FCONST_0, FCONST_1, FCONST_2, FDIV, FLOAD, FMUL, FNEG, FREM, FRETURN, FSTORE, FSUB, GETFIELD, GETSTATIC, GOTO, I2B, I2C, I2D, I2F, I2L, I2S, IADD, IALOAD, IAND, IASTORE, ICONST_0, ICONST_1, ICONST_2, ICONST_3, ICONST_4, ICONST_5, ICONST_M1, IDIV, IF_ACMPEQ, IF_ACMPNE, IF_ICMPEQ, IF_ICMPGE, IF_ICMPGT, IF_ICMPLE, IF_ICMPLT, IF_ICMPNE, IFEQ, IFGE, IFGT, IFLE, IFLT, IFNE, IFNONNULL, IFNULL, IINC, ILOAD, IMUL, INEG, INSTANCEOF, INVOKEINTERFACE, INVOKESPECIAL, INVOKESTATIC, INVOKEVIRTUAL, IOR, IREM, IRETURN, ISHL, ISHR, ISTORE, ISUB, IUSHR, IXOR, JSR, L2D, L2F, L2I, LADD, LALOAD, LAND, LASTORE, LCMP, LCONST_0, LCONST_1, LDC, LDIV, LLOAD, LMUL, LNEG, LOOKUPSWITCH, LOR, LREM, LRETURN, LSHL, LSHR, LSTORE, LSUB, LUSHR, LXOR, MONITORENTER, MONITOREXIT, MULTIANEWARRAY, NEW, NEWARRAY, NOP, POP, POP2, PUTFIELD, PUTSTATIC, RET, RETURN, SALOAD, SASTORE, SIPUSH, SWAP, T_BOOLEAN, T_BYTE, T_CHAR, T_DOUBLE, T_FLOAT, T_INT, T_LONG, T_SHORT, TABLESWITCH, V1_1, V1_2, V1_3, V1_4, V1_5

Constructor Summary

RmiStubFactory()
Constructs a new RmiStubFactory.

Method Summary

void	bindFc(java.lang.String clientItfName, java.lang.Object serverItf)
protected void	generateConstructor(org.objectweb.asm.ClassVisitor cv, java.lang.String superClass) Generates an empty constructor for the given class.
protected void	generateSkeletonClass(org.objectweb.asm.ClassVisitor cv, java.lang.Class itf) Generates a skeleton class for the given Java interface.
protected void	generateSkeletonMethod(org.objectweb.asm.ClassVisitor cv, java.lang.String name, java.lang.Class itf) Generates a skeleton's send method.
protected void	generateStubClass(org.objectweb.asm.ClassVisitor cv, java.lang.Class itf) Generates a stub class for the given Java interface.
protected void	generateStubMethod(org.objectweb.asm.ClassVisitor cv, java.lang.String name, java.lang.reflect.Method m, int index) Generates a stub method.
protected boolean	isClassParameter(java.lang.reflect.Method m, int p) Returns true if the specified parameter contains the name of a class.
java.lang.String[]	listFc()
java.lang.Object	lookupFc(java.lang.String clientItfName)
static void	main(java.lang.String[] interfaces) FractalRMI stub and skeleton generator.
RequestSession	newSkeleton(java.lang.Object target) Creates a new skeleton implementing the RequestSession interface.
java.lang.Object	newStub(SessionIdentifier sessionId, Identifier[] ids, Context hints) Creates a new stub.
protected static void	sort(java.lang.reflect.Method[] methods) Sorts the given methods.
void	unbindFc(java.lang.String clientItfName)

Methods inherited from class java.lang.Object

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

Field Detail

marshallerFactory

protected MarshallerFactory marshallerFactory

The marshaller factory to be used by the stubs created by this factory.

loggerFactory

protected org.objectweb.util.monolog.api.LoggerFactory loggerFactory

The optional logger factory used to get a logger for this component.

logger

protected org.objectweb.util.monolog.api.Logger logger

The logger used to log messages. May be null.

Constructor Detail

RmiStubFactory

public RmiStubFactory()

Constructs a new RmiStubFactory.

Method Detail

main

public static void main(java.lang.String[] interfaces)
                 throws java.lang.Exception

FractalRMI stub and skeleton generator.

Parameters:

interfaces - a list of interface fully qualified names. These interfaces must be compiled already and reachable through the classpath. Stubs and skeletons are generated as compiled classes taking current directory as base directory.

Throws:

java.lang.Exception

listFc

public java.lang.String[] listFc()

Specified by:

listFc in interface org.objectweb.fractal.api.control.BindingController

lookupFc

public java.lang.Object lookupFc(java.lang.String clientItfName)

Specified by:

lookupFc in interface org.objectweb.fractal.api.control.BindingController

bindFc

public void bindFc(java.lang.String clientItfName,
                   java.lang.Object serverItf)

Specified by:

bindFc in interface org.objectweb.fractal.api.control.BindingController

unbindFc

public void unbindFc(java.lang.String clientItfName)

Specified by:

unbindFc in interface org.objectweb.fractal.api.control.BindingController

newStub

public java.lang.Object newStub(SessionIdentifier sessionId,
                                Identifier[] ids,
                                Context hints)
                         throws JonathanException

Creates a new stub. A stub plays two roles:

• It is the local representative of a (remote) object, and thus should bear a set of identifiers for that remote object;
• It is part of the binding between the client and the server, and is thus related to a given protocol. The session identifier provided as an argument is the manifestation of this relation. It can be used to obtain a session allowing the stub to send data to the remote object.

Specified by:

newStub in interface StubFactory

Parameters:

sessionId - a session identifier, to be used to send marshalled data to the object represented by the stub;

ids - the set of identifiers of the stub;

hints - other data possibly used to create the stub. This method requires the fully qualified name of the Java interface to which the stub will gives access. This name must be associated to the "interface_type" key.

Returns:

an instance of a sub class of the Stub class.

Throws:

JonathanException - if something goes wrong.

newSkeleton

public RequestSession newSkeleton(java.lang.Object target)
                           throws JonathanException

Description copied from interface: SkeletonFactory

Creates a new skeleton implementing the RequestSession interface.

Specified by:

newSkeleton in interface SkeletonFactory

Parameters:

target - the remote object.

Returns:

the created skeleton.

Throws:

JonathanException - if something goes wrong.

generateStubClass

protected void generateStubClass(org.objectweb.asm.ClassVisitor cv,
                                 java.lang.Class itf)

Generates a stub class for the given Java interface. This method generates a sub class of the Stub class that implements the given interface, by using the given class visitor.

Parameters:

cv - the class visitor to be used to generate the stub class.

itf - the Java interface that the stub class must implement.

generateSkeletonClass

protected void generateSkeletonClass(org.objectweb.asm.ClassVisitor cv,
                                     java.lang.Class itf)

Generates a skeleton class for the given Java interface. This method generates a sub class of the Skeleton class whose target is an object implementing the given interface, by using the given class visitor.

Parameters:

cv - the class visitor to be used to generate the stub class.

itf - the Java interface implemented by the skeleton's target.

generateConstructor

protected void generateConstructor(org.objectweb.asm.ClassVisitor cv,
                                   java.lang.String superClass)

Generates an empty constructor for the given class.

Parameters:

cv - the class visitor to be used to generate the constructor.

superClass - the internal name of the super class of the generated class. This name is used to generate a call to the super constructor.

generateStubMethod

protected void generateStubMethod(org.objectweb.asm.ClassVisitor cv,
                                  java.lang.String name,
                                  java.lang.reflect.Method m,
                                  int index)

Generates a stub method. A stub method is of the following form:

 public T m (T0 arg0, ...) throws E0, ... {
   try {
     Marshaller marshaller = request();
     ReplyInterface reply = prepareInvocation(marshaller);
     marshaller.writeInt(methodIndex);
     marshaller.writeXXX(arg0);
     ...
     invoke(marshaller);
     UnMarshaller unmarshaller = reply.listen();
     T result = (T)unmarshaller.readXXX();
     unmarshaller.close();
     return result;
   } catch (Exception e) {
     e = handleException(e);
     if (e instanceof E0) throw (E0)e;
     ...
     if (e instanceof RuntimeException) throw (RuntimeException)e;
     throw new RemoteException("server side exception", e);
   }
 }
 

Parameters:

cv - the class visitor to be used to generate the stub method.

name - the internal name of the generated stub class.

m - the signature of the method that must be generated.

index - the index of this method. This index will be marshalled by the generated stub method in each invocation message, to specify the method that must be called on the server side. This index is the index of the method in the sorted array of all the methods implemented by the stub.

generateSkeletonMethod

protected void generateSkeletonMethod(org.objectweb.asm.ClassVisitor cv,
                                      java.lang.String name,
                                      java.lang.Class itf)

Generates a skeleton's send method. The generated method is of the following form:

 public void send (UnMarshaller unmarshaller, ReplySession session)
   throws JonathanException
 {
   int methodIndex = unmarshaller.readInt();
   try {
     switch (methodIndex) {
       case 0:
         T0 arg0 = unmarshaller.readXXX();
         ...
         unmarshaller.close();
         T result = ((I)target).m0(arg0, ... );
         Marshaller marshaller = session.prepareReply();
         marshaller.writeXXX(result);
         session.send(marshaller);
         session.close();
         return;
       ...
       default:
         handleInterfaceMethods(unmarshaller, session, methodIndex);
     }
   } catch (Exception e) {
     handleException(e, session);
   }
 }
 

Parameters:

cv - the class visitor to be used to generate the stub method.

name - the internal name of the generated stub class.

itf - the target object's interface that must be exported by the skeleton.

isClassParameter

protected boolean isClassParameter(java.lang.reflect.Method m,
                                   int p)

Returns true if the specified parameter contains the name of a class. This method is used to marshall a Class object, instead of a String, for parameters that contains class names, in order to enable these classes to be downloaded from the network if needed. The default implementation of this method returns true for:

• the return value of Factory.getFcContentDesc.
• the second parameter of GenericFactory.newFcInstance.
• the return value of InterfaceType.getFcItfSignature.
• the second parameter of TypeFactory.createFcItfType.

Parameters:

m - a method.

p - index of a parameter of this method, or -1 to designate the return value.

Returns:

true if the specified parameter contains the name of a class.

sort

protected static void sort(java.lang.reflect.Method[] methods)

Sorts the given methods. This method is used to assign an unambiguous index to each method of an interface (the index of a method in the array returned by getMethods cannot directly be used for this purpose, since this method returns the methods in any order).

Parameters:

methods - the method array to be sorted.