OpenCOM
Class OpenCOM

java.lang.Object
  OpenCOM.OpenCOM

All Implemented Interfaces:

IDebug, IMetaArchitecture, IMetaInterception, IOpenCOM, IUnknown

public class OpenCOM
extends java.lang.Object
implements IOpenCOM, IDebug, IMetaArchitecture, IUnknown, IMetaInterception

OpenCOM is the implementation of the component runtime kernel. It should be instantiated once only - n.b. future versions may implement this class using the singleton pattern. OpenCOM provides a set of runtime services that support the creation, deletetion and binding of software components. Notably, it maintains information about the running component architectures in a system wide graph data structure. Reflective operations can then be performed on this meta-representation i.e. inspection and dynamic reconfiguration. The aim is to support the capabilities of the three meta-models proposed by the Open ORB philosopy i.e. interface, architecture and interception meta-models. Not that this is a prototype version of OpenCOM version 1 as described in Clarke,01. There is a C++ implementation offering identical operations.

See Also:

IOpenCOM, IMetaInterface, IMetaInterception, IMetaArchitecture

Constructor Summary

OpenCOM()
Constructor that creates a new instance of the OpenCOM runtime kernel

Method Summary

long	connect(IUnknown pIUnkSource, IUnknown pIUnkSink, java.lang.String iid) Connects the source component hosting the receptacle to the sink component hosting the interface on the given interface type.
java.lang.Object	createInstance(java.lang.String componentType, java.lang.String componentName) Creates a component in the OpenCOM runtime.
boolean	deleteInstance(IUnknown pCompToDelete) This method deletes the information about a component from the system graph.
boolean	disconnect(long connID) This operation disconnects two previously connected components based upon the unqiue ID of this connection.
void	dump() The dump method is useful for debugging purposes as it allows the entire state of the system graph to be outputted to the console.
int	enumComponents(java.util.Vector<IUnknown> ppComps) This method enumerates all components currently registetred with the runtime and places their references into the given vector parameter.
int	enumConnsFromRecp(IUnknown pIUnknown, java.lang.String riid, java.util.Vector<java.lang.Long> ppConnsFromRecp) This method introspects connections on existing components.
int	enumConnsToIntf(IUnknown pIUnknown, java.lang.String riid, java.util.Vector<java.lang.Long> ppConnsToIntf) This method introspects connections on existing components.
java.lang.Class	getComponentCLSID(IUnknown pIUnknown) This method returns the Component type as a java class for a given instance of a component.
java.lang.String	getComponentName(IUnknown pIUnknown) This method returns the unqiue component name for a given instance of a component.
IUnknown	getComponentPIUnknown(java.lang.String CompName) This method returns the component reference for a given unique component name.
OCM_ConnInfo_t	getConnectionInfo(long connID) Returns meta-information about a connection (i.e.
IDelegator	GetDelegator(IUnknown pIUnkParent, java.lang.String riid) This method get the delegator for a particular component interface.
java.lang.Object	QueryInterface(java.lang.String InterfaceName) This method returns a reference point to the runtime, based upon the requested interface type.

Methods inherited from class java.lang.Object

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

Constructor Detail

OpenCOM

public OpenCOM()

Constructor that creates a new instance of the OpenCOM runtime kernel

Method Detail

dump

public void dump()

The dump method is useful for debugging purposes as it allows the entire state of the system graph to be outputted to the console. Hence, you can check if component configurations are as required.

Specified by:

dump in interface IDebug

enumConnsFromRecp

public int enumConnsFromRecp(IUnknown pIUnknown,
                             java.lang.String riid,
                             java.util.Vector<java.lang.Long> ppConnsFromRecp)

This method introspects connections on existing components. It tells you how many components are connected to this particular receptacle. For single receptacles this will be 0 or 1; however, multiple receptacles can have 0 to N connections.

Specified by:

enumConnsFromRecp in interface IMetaArchitecture

Parameters:

pIUnknown - The component hosting the receptacle we wish to introspect.

riid - The interface type of the receptacle.

ppConnsFromRecp - A vector to be filled with unique connection ids of all the connections to this receptacle.

Returns:

An integer describing the number of connections to this receptacle.

enumConnsToIntf

public int enumConnsToIntf(IUnknown pIUnknown,
                           java.lang.String riid,
                           java.util.Vector<java.lang.Long> ppConnsToIntf)

This method introspects connections on existing components. It tells you how many components are connected to this particular INTERFACE.

Specified by:

enumConnsToIntf in interface IMetaArchitecture

Parameters:

pIUnknown - The component hosting the interface we wish to introspect.

riid - The interface type of the interface.

ppConnsFromRecp - A vector to be filled with unique connection ids of all the connections to this interface.

Returns:

An integer describing the number of connections to this interface.

QueryInterface

public java.lang.Object QueryInterface(java.lang.String InterfaceName)

This method returns a reference point to the runtime, based upon the requested interface type. If the interface isn't hosted then the null indicates that those operations are not available on the runtime.

Specified by:

QueryInterface in interface IUnknown

Parameters:

A - string describing the interface requested.

Returns:

A reference to the runtime if the interface is available, otherwise null is returned.

connect

public long connect(IUnknown pIUnkSource,
                    IUnknown pIUnkSink,
                    java.lang.String iid)

Connects the source component hosting the receptacle to the sink component hosting the interface on the given interface type.

Specified by:

connect in interface IOpenCOM

Parameters:

IUnkSource - The source component of the connection (hosts receptacle).

pIUnkSink - The sink component of the connection (provides interface).

iid - The interface type to make the connection on.

Returns:

A long representing the unique ID of this connection.

See Also:

IUnknown

createInstance

public java.lang.Object createInstance(java.lang.String componentType,
                                       java.lang.String componentName)

Creates a component in the OpenCOM runtime. A component is created, delegators are attached to support interface interception, and finally meta-data about the component is initialised in the system graph.

Specified by:

createInstance in interface IOpenCOM

Parameters:

componentType - This string describes the Java class type of the component to create.

componentName - The unique user-defined name for the new component.

Returns:

A reference to a newly created instance of the component.

See Also:

Object

deleteInstance

public boolean deleteInstance(IUnknown pCompToDelete)

This method deletes the information about a component from the system graph. It does not attempt to delete the instance of the component itself. At present this is left to Garbage Collection. In future versions, a reference counter a la COM may provide more control of memory management; at present it is very easy to leave references to components in place after they are no longer needed.

Specified by:

deleteInstance in interface IOpenCOM

Parameters:

pCompToDelete - Reference to the component instance to be deleted.

Returns:

A boolean describing whether the information about the component was removed from the graph or not.

See Also:

IUnknown

disconnect

public boolean disconnect(long connID)

This operation disconnects two previously connected components based upon the unqiue ID of this connection.

Specified by:

disconnect in interface IOpenCOM

Parameters:

connID - A long representing the unqie identifier of the connection to destroy.

Returns:

boolean A boolean describing whether the disconnect operation succeeded.

enumComponents

public int enumComponents(java.util.Vector<IUnknown> ppComps)

This method enumerates all components currently registetred with the runtime and places their references into the given vector parameter.

Specified by:

enumComponents in interface IOpenCOM

Parameters:

ppComps - The list to be filled with components from the graph.

Returns:

An integer describing the number of components in the graph.

getComponentCLSID

public java.lang.Class getComponentCLSID(IUnknown pIUnknown)

This method returns the Component type as a java class for a given instance of a component.

Specified by:

getComponentCLSID in interface IOpenCOM

Parameters:

pIUnknown - The reference of the component instance.

Returns:

A java class describing the component type.

See Also:

IUnknown, Class

getComponentName

public java.lang.String getComponentName(IUnknown pIUnknown)

This method returns the unqiue component name for a given instance of a component.

Specified by:

getComponentName in interface IOpenCOM

Parameters:

pIUnknown - The reference of the component instance.

Returns:

A string describing the component name.

See Also:

IUnknown

getComponentPIUnknown

public IUnknown getComponentPIUnknown(java.lang.String CompName)

This method returns the component reference for a given unique component name.

Specified by:

getComponentPIUnknown in interface IOpenCOM

Parameters:

CompName - The name of the component instance.

Returns:

A reference to the component instance.

See Also:

IUnknown

getConnectionInfo

public OCM_ConnInfo_t getConnectionInfo(long connID)

Returns meta-information about a connection (i.e. the source and sink components, and the type of interface these components are conected by.

Specified by:

getConnectionInfo in interface IOpenCOM

Parameters:

connID - The unique connection identifier of the connection to inspect.

Returns:

An object holding the meta data about the connection.

See Also:

OCM_ConnInfo_t

GetDelegator

public IDelegator GetDelegator(IUnknown pIUnkParent,
                               java.lang.String riid)

This method get the delegator for a particular component interface. This can then be used to attache pre and post methods. Each component has a set of delegators - one for each functional interface and one for the IUnknown interface. The developer uses this method to pinpoint the correct one.

Specified by:

GetDelegator in interface IMetaInterception

Parameters:

pIUnkParent - The component reference we want to get a delegator from.

riid - The interface type we want to get the delegator for.

Returns:

The IDelegator interface of the selected delegator instance.

See Also:

IDelegator