si.ijs.acs.objectexplorer.engine

Class Operation

java.lang.Object

si.ijs.acs.objectexplorer.engine.Operation

Direct Known Subclasses:

BACIOperation

public abstract class Operation
extends java.lang.Object

Data structure that describes the operation declared by a given introspectable. Note that objects of this type do not describe a specific remote call (an instance of the call), but rather syntax of an operation. In that way they are analogous to Java java.lang.reflect.Method instances. A note about the convention on how parameters to the operation are described: each parameter is described by a name, a type and a mask field. These data are stored in arrays of equal length, corresponding indexes describing the same parameter. Only parameters with mask set to true should be processed by the GUI, others are used by the engine to hold "context" parameters, such as callbacks, parameters passed by reference (pointers) to the remote objects, parameters declared as OUT in CORBA etc. GUI implementations must not modify any parameter values that declare false in the mask.

Constructor Summary

Constructors

Constructor and Description
Operation(java.lang.String name, SimpleIntrospectable introspectable, DataType returnType, java.lang.String[] parameterNames, DataType[] parameterTypes, boolean[] mask, boolean invocation, boolean special) Constructs a new instance of an operation.

Method Summary

Modifier and Type	Method and Description
SimpleIntrospectable	getIntrospectable() Returns the introspectable instance that declares this method.
boolean[]	getMask() Returns the mask value for each argument / parameter to this method.
java.lang.String	getName() Returns the name of this operation, as it should be displayed to the user.
java.lang.String[]	getParameterNames() Returns the parameter names array.
DataType[]	getParameterTypes() Returns the array of parameter types for each parameter to this operation.
DataType	getReturnType() Returns the array of parameter types for each parameter to this operation.
abstract RemoteCall	invoke(java.lang.Object[] data) Invokes this operation.
abstract Invocation	invokeAsync(java.lang.Object[] data, RemoteResponseCallback cb) Invokes an asynchronous operation on the introspectable instane.
boolean	isInvocation() Returns true if this object represents an operation, that is asynchronous.
boolean	isSpecial() Returns true if this operation is "special".
java.lang.String	toString() Returns the display name of this operation with its parameter types in brackets.

Methods inherited from class java.lang.Object

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

Constructor Detail

Operation

public Operation(java.lang.String name,
                 SimpleIntrospectable introspectable,
                 DataType returnType,
                 java.lang.String[] parameterNames,
                 DataType[] parameterTypes,
                 boolean[] mask,
                 boolean invocation,
                 boolean special)

Constructs a new instance of an operation.

Parameters:

name - the name of the operation to be displayed in GUI

introspectable - the remote object that declares this operation

parameterNames - an array of string names of all parameters that the operation declares

parameterTypes - an array of DataType objects identifying the parameter types in the same sequence as in the names array

mask - an array of booleans that indicates which parameters should be requested by the GUI to be supplied by the user, when the method is invoked. The GUI should only ask for parameters that have true flag set in this array. The sequence is the same as in types and names arrays.

invocation - true iff this method is an asynchronous method. If so, it must be invoked with invokeAsync() method and will, as a response return an invocation object.

special - true iff the operation should be treated as special in the GUI (ie. displayable only if certain checkbox is checked)

Method Detail

getIntrospectable

public SimpleIntrospectable getIntrospectable()

Returns the introspectable instance that declares this method. Returns the same value as was passed to the constructor.

Returns:

introspectable instance

getMask

public boolean[] getMask()

Returns the mask value for each argument / parameter to this method. GUIs should only process (query the user for values) only those parameters that declare true. Other parameters should be left unmodified.

Returns:

a mask array

getName

public java.lang.String getName()

Returns the name of this operation, as it should be displayed to the user.

Returns:

operation name

getParameterNames

public java.lang.String[] getParameterNames()

Returns the parameter names array. This is the same value as was passed to the constructor.

Returns:

parameter names

getParameterTypes

public DataType[] getParameterTypes()

Returns the array of parameter types for each parameter to this operation. Note that if parameters are of complex types and it is desired for the GUI to be able to query users for their values and construct instances described by this classes, the classes must declare a public constructor that takes all parameters that have to be supplied to instantiate a type.

Returns:

an array of parameter types

getReturnType

public DataType getReturnType()

Returns the array of parameter types for each parameter to this operation. Note that if parameters are of complex types and it is desired for the GUI to be able to query users for their values and construct instances described by this classes, the classes must declare a public constructor that takes all parameters that have to be supplied to instantiate a type.

Returns:

a return value DataType

invoke

public abstract RemoteCall invoke(java.lang.Object[] data)

Invokes this operation. The method returns a remote call data struture that will pack the input parameters, return values and possible exceptions of the call. Note: this method should only be used to invoke synchronous operations, ie. operations that do not create Invocations as a side-effect.. The method must block for the duration of the call, although it can terminate with a timeout, if this condition can be detected.

Parameters:

data - parameters to be passed to the remote call. It is the responsibility of the GUI to initialize this array in accordance to the guidelines set forth in the documentation of this class

Returns:

remote call data structure that packs the results of the remote operation call

invokeAsync

public abstract Invocation invokeAsync(java.lang.Object[] data,
                                       RemoteResponseCallback cb)

Invokes an asynchronous operation on the introspectable instane. The method produces an invocation instance as a side-effect. Note that because invocations are asynchronous, a callback parameter is required to receive the asynchronous responses. Use this model for monitors, alarms, event notifications and similar designs.

Parameters:

data - parameters to be passed to the remote call. It is the responsibility of the GUI to initialize this array in accordance to the guidelines set forth in the documentation of this class

cb - the callback that will receive the async notifications. Must not be null.

Returns:

invocation instance that represents the started process on the remote machine; this instance contains also the familiar remote call data structure that describes the call that generated the invocation

isInvocation

public boolean isInvocation()

Returns true if this object represents an operation, that is asynchronous. If so, an invocation of such operation will produce an invocation object as a side effect. Asynchronous operations must be invoked with invokeAsync() method. Therefore the GUI should always check first the return value of this call and decide which mode of invocation (sync or async) to use.

Returns:

true if the method should be invoked through the invokeAsync() method.

isSpecial

public boolean isSpecial()

Returns true if this operation is "special". GUI decides how to handle special operations. The preferred way is not to display them until the user has checked a special checkbox allowing the GUI to display "advanced" or "dangerous" features.

Returns:

true if this operation is special

toString

public java.lang.String toString()

Returns the display name of this operation with its parameter types in brackets.

Overrides:

toString in class java.lang.Object

Returns:

name of this.