OpenCOM
Class CFMetaInterface

java.lang.Object
  OpenCOM.CFMetaInterface

All Implemented Interfaces:

ICFMetaInterface, ILifeCycle, IMetaInterface, IUnknown

public abstract class CFMetaInterface
extends java.lang.Object
implements ICFMetaInterface, ILifeCycle, IUnknown, IMetaInterface

Description of an abstract class defining operations for creating a component framework. An OpenCOM component extends this behaviour to become a component framework. That is if you QI a component and it support ICFMetaInterface then you know it is a component framework rather than a primitive OpenCOM component.

See Also:

ICFMetaInterface, ILifeCycle

Nested Class Summary

class	CFMetaInterface.ConnectedComponent The framework stores connection information for use during rollback of configurations.
class	CFMetaInterface.ExposedInterface Local class definition for Exposed Interfaces that are stored in the MOPs of the framework.
class	CFMetaInterface.ExposedReceptacle

Field Summary

OCM_SingleReceptacle<IAccept>	m_PSR_IAccept Receptacle to plug-in the validation checks for this component framework.
OCM_SingleReceptacle<IMetaArchitecture>	m_PSR_IMetaArchitecture
OCM_SingleReceptacle<IMetaInterception>	m_PSR_IMetaInterception
OCM_SingleReceptacle<IMetaInterface>	m_PSR_IMetaInterface
MetaInterface	Meta Fixed reference to the OpenCOM runtime API.

Constructor Summary

CFMetaInterface(IUnknown pRuntime)
Constructor.

Method Summary

boolean	access_CF_graph_lock(int index) Each component framework implemnts a lock to prevent reconfiguration during functional operation.
boolean	break_local_bind(long connID) This method disconnects two components only if they both reside in the framework and are connected.
boolean	commit_arch_transaction() This method must be called by the reconfiguration agent at the end of the reconfiguration transaction.
boolean	connect(IUnknown pSinkIntf, java.lang.String riid, long provConnID)
IUnknown	create_component(java.lang.String componentType, java.lang.String componentName) This method creates the component within the framework.
boolean	delete_component(IUnknown pIUnknown) This method deletas the component from the framework.
boolean	disconnect(java.lang.String riid, long connID)
int	enumIntfs(java.util.Vector<java.lang.Class> ppIntfs) Returns a Vector of meta-information.
int	enumRecps(java.util.Vector<OCM_RecpMetaInfo_t> ppRecpMetaInfo) Returns a Vector of meta-information.
boolean	expose_interface(java.lang.String rintf, IUnknown pComp) This method takes the interface from one of the framework's internal components and then makes it one of its own functional interfaces.
boolean	expose_receptacle(java.lang.String rintf, IUnknown pComp, java.lang.String recpType) This method takes the receptacle from one of the framework's internal components and then makes it one of its own receptacles.
int	get_bound_components(IUnknown comp, java.util.Vector<CFMetaInterface.ConnectedComponent> ppConnections) This method produces a list of components that are connected to a particular component within the framework.
int	get_exposed_interfaces(java.util.Vector<java.lang.String> ppIntfs) This method fills the vector passed as a parameter with the list of interfaces exposed by this framework.
int	get_exposed_receptacles(java.util.Vector<CFMetaInterface.ExposedReceptacle> ppComps) This method fills the vector passed as a parameter with the list of receptacles exposed by this framework.
int	get_internal_bindings(java.util.Vector<java.lang.Long> pConnIDS) This method returns all of the internal connections between components that are wholly within the framework.
int	get_internal_components(java.util.Vector<IUnknown> ppComps) This method fills the vector passed as a parameter with the references of all the components that reside locally within this framework.
java.util.Hashtable	GetAllValues(java.lang.String Kind, java.lang.String iid) This method retrieves all the meta-data stored on the interface or receptacle.
TypedAttribute	GetAttributeValue(java.lang.String iid, java.lang.String Kind, java.lang.String Name) Meta-data can be retrieved from each interface/receptacle of a component.
boolean	init_arch_transaction() All reconfigurations must be performed as part of a transaction.
boolean	insert_component(IUnknown componentRef) This method inserts a previously instantiated component from the runtime, into the framework instance.
long	local_bind(IUnknown pIUnkSource, IUnknown pIUnkSink, java.lang.String InterfaceType) This method binds together two components only if they both reside in the framework.
java.lang.Object	QueryInterface(java.lang.String InterfaceName, java.lang.Object cfReference) This method is an extension of QueryInterface to allow exposed interfaces to be found and used.
boolean	release_CF_graph_lock(int index) Releases the lock, previously acquired.
boolean	rollback_arch_transaction() Rolls the configuration back to its previous state - ideally should not be called directly; maybe if faults are being detected is a supposedly valid architecture you may wish to try returning to a stable version.
boolean	SetAttributeValue(java.lang.String iid, java.lang.String Kind, java.lang.String Name, java.lang.String Type, java.lang.Object Value) Meta-data can be attached to each interface/receptacle of a component.
boolean	shutdown() Allows a component to take action while it is being deleted.
boolean	startup(java.lang.Object pIOCM) Allows a component to take action whenever an instance is created.
boolean	unexpose_all_interfaces() This method removes all exposed interfaces.
boolean	unexpose_all_receptacles() This method removes all exposed receptacles.
boolean	unexpose_interface(java.lang.String rintf, IUnknown pComp) This method removes the exposed interface from the outer component framework,
boolean	unexpose_receptacle(java.lang.String rintf, IUnknown pComp) This method removes the exposed receptacle from the outer component framework,
int	update_readers_count(int Value) Update the CF's locks readers count.

Methods inherited from class java.lang.Object

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

Methods inherited from interface OpenCOM.IUnknown

QueryInterface

Field Detail

Meta

public MetaInterface Meta

Fixed reference to the OpenCOM runtime API.

See Also:

IOpenCOM

m_PSR_IAccept

public OCM_SingleReceptacle<IAccept> m_PSR_IAccept

Receptacle to plug-in the validation checks for this component framework.

m_PSR_IMetaInterface

public OCM_SingleReceptacle<IMetaInterface> m_PSR_IMetaInterface

m_PSR_IMetaInterception

public OCM_SingleReceptacle<IMetaInterception> m_PSR_IMetaInterception

m_PSR_IMetaArchitecture

public OCM_SingleReceptacle<IMetaArchitecture> m_PSR_IMetaArchitecture

Constructor Detail

CFMetaInterface

public CFMetaInterface(IUnknown pRuntime)

Constructor. Creates a new instance of CFMetaInterface

Method Detail

QueryInterface

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

This method is an extension of QueryInterface to allow exposed interfaces to be found and used. Basically the outer component framework's IUnknown QI method will call this method if it is yet to find the required interface

Parameters:

InterfaceName - A string describing the interface we are looking for

cfReference - A reference to the outer component framework instance

Returns:

A Reference of the component hosting the required interface

shutdown

public boolean shutdown()

Description copied from interface: ILifeCycle

Allows a component to take action while it is being deleted. This method SHOULD NOT be directly called by the programmer but it is called by the OpenCOM runtime when a component it deleted by calling deleteInstance().

Specified by:

shutdown in interface ILifeCycle

Returns:

A boolean indicating the success of the operation

startup

public boolean startup(java.lang.Object pIOCM)

Description copied from interface: ILifeCycle

Allows a component to take action whenever an instance is created. A pointer to the IOCM of the runtime is passed to allow the instance to store it as a member variable, thus allowing convenient access from member methods. This method should be called directly by the programmer after an instance is created. This separation between creation and initialisation is needed because startup() typically invokes receptacle-based intarfaces, which must be connected after a component instance has been created by the runtime, i.e. before startup can be invoked.

Specified by:

startup in interface ILifeCycle

Parameters:

pIOCM - Any startup data to be passed to the component when it is activated.

Returns:

A boolean indicating the success of the operation

See Also:

IOpenCOM

create_component

public IUnknown create_component(java.lang.String componentType,
                                 java.lang.String componentName)

This method creates the component within the framework. The component is created, stored in the runtime, and inserted into this framework's meta-data.

Specified by:

create_component in interface ICFMetaInterface

Parameters:

componentType - The type of the component to create.

componentName - The unique name of the component to create.

Returns:

A reference to the newly created component instance.

See Also:

IUnknown

insert_component

public boolean insert_component(IUnknown componentRef)

This method inserts a previously instantiated component from the runtime, into the framework instance.

Specified by:

insert_component in interface ICFMetaInterface

Parameters:

pCompReference - The reference of the component instance.

componentName - The unique name of the component to create.

Returns:

A boolean indicating if the insert occured or not.

See Also:

IUnknown

delete_component

public boolean delete_component(IUnknown pIUnknown)

This method deletas the component from the framework. The component is disconnected, deleted from the runtime, and this framework's meta-data is updated.

Specified by:

delete_component in interface ICFMetaInterface

Parameters:

pIUnknown - The component instance to delete

Returns:

A boolean indicating if the component was deleted or not.

See Also:

IUnknown

local_bind

public long local_bind(IUnknown pIUnkSource,
                       IUnknown pIUnkSink,
                       java.lang.String InterfaceType)

This method binds together two components only if they both reside in the framework.

Specified by:

local_bind in interface ICFMetaInterface

Parameters:

pIUnkSource - The source component with the receptacle.

pIUnkSink - The sink component with the interface.

InterfaceType - The interface type to make the connection on.

Returns:

A long describing the unique ID of this new connection. -1 indicates failure to connect.

See Also:

IUnknown

break_local_bind

public boolean break_local_bind(long connID)

This method disconnects two components only if they both reside in the framework and are connected.

Specified by:

break_local_bind in interface ICFMetaInterface

Parameters:

connID - The unique ID of the connection to break.

Returns:

A boolean indicating if the disconnection was made.

expose_interface

public boolean expose_interface(java.lang.String rintf,
                                IUnknown pComp)

This method takes the interface from one of the framework's internal components and then makes it one of its own functional interfaces.

Specified by:

expose_interface in interface ICFMetaInterface

Parameters:

rintf - The interface type that will be exposed.

pComp - The internal component hosting the the interface.

Returns:

A boolean describing if the interface was exposed.

See Also:

IUnknown

expose_receptacle

public boolean expose_receptacle(java.lang.String rintf,
                                 IUnknown pComp,
                                 java.lang.String recpType)

This method takes the receptacle from one of the framework's internal components and then makes it one of its own receptacles.

Specified by:

expose_receptacle in interface ICFMetaInterface

Parameters:

rintf - The interface type that will be exposed.

pComp - The internal component hosting the the interface.

recpType - The type of the receptacle.

Returns:

A boolean describing if the receptacle was exposed.

See Also:

IUnknown

unexpose_all_interfaces

public boolean unexpose_all_interfaces()

This method removes all exposed interfaces.

Specified by:

unexpose_all_interfaces in interface ICFMetaInterface

Returns:

A boolean describing if all the interfaces have been removed.

unexpose_all_receptacles

public boolean unexpose_all_receptacles()

This method removes all exposed receptacles.

Specified by:

unexpose_all_receptacles in interface ICFMetaInterface

Returns:

A boolean describing if all the receptacle have been removed.

unexpose_interface

public boolean unexpose_interface(java.lang.String rintf,
                                  IUnknown pComp)

This method removes the exposed interface from the outer component framework,

Specified by:

unexpose_interface in interface ICFMetaInterface

Parameters:

rintf - The interface type that will be removed.

pComp - The internal component hosting the the interface.

Returns:

A boolean describing if the interface has been removed.

See Also:

IUnknown

unexpose_receptacle

public boolean unexpose_receptacle(java.lang.String rintf,
                                   IUnknown pComp)

This method removes the exposed receptacle from the outer component framework,

Specified by:

unexpose_receptacle in interface ICFMetaInterface

Parameters:

rintf - The interface type that will be removed.

pComp - The internal component hosting the the receptacle.

Returns:

A boolean describing if the receptacle has been removed.

See Also:

IUnknown

get_bound_components

public int get_bound_components(IUnknown comp,
                                java.util.Vector<CFMetaInterface.ConnectedComponent> ppConnections)

This method produces a list of components that are connected to a particular component within the framework.

Specified by:

get_bound_components in interface ICFMetaInterface

Parameters:

comp - Instance of the component we wish to find what is connected to it.

ppConnections - Vector to be filled with the list of components that are connected to this component.

Returns:

An integer describing the number of components connected to this component.

See Also:

IUnknown

get_exposed_interfaces

public int get_exposed_interfaces(java.util.Vector<java.lang.String> ppIntfs)

This method fills the vector passed as a parameter with the list of interfaces exposed by this framework. Its behaviour is similar to that provided by enumIntfs of OpenCOM.

Specified by:

get_exposed_interfaces in interface ICFMetaInterface

Parameters:

ppIntfs - A vector to be filled with the list of interfaces.

Returns:

The number of interfaces exposed by this framework.

get_exposed_receptacles

public int get_exposed_receptacles(java.util.Vector<CFMetaInterface.ExposedReceptacle> ppComps)

This method fills the vector passed as a parameter with the list of receptacles exposed by this framework. Its behaviour is similar to that provided by enumRecps of OpenCOM.

Specified by:

get_exposed_receptacles in interface ICFMetaInterface

Parameters:

ppComps - A vector to be filled with the list of receptacles.

Returns:

The number of interfaces exposed by this framework.

get_internal_bindings

public int get_internal_bindings(java.util.Vector<java.lang.Long> pConnIDS)

This method returns all of the internal connections between components that are wholly within the framework.

Specified by:

get_internal_bindings in interface ICFMetaInterface

Parameters:

pConnIDS - A vector to be filled with long values describing the unique id of each connection.

Returns:

An integer describing the number of connections within the framework.

get_internal_components

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

This method fills the vector passed as a parameter with the references of all the components that reside locally within this framework.

Specified by:

get_internal_components in interface ICFMetaInterface

Parameters:

ppComps - A vector to be filled with the references of inner components.

Returns:

The number of components within the framework.

init_arch_transaction

public boolean init_arch_transaction()

All reconfigurations must be performed as part of a transaction. Therefore, the reconfigure agent must first call this method before subsequent write operations.

Specified by:

init_arch_transaction in interface ICFMetaInterface

Returns:

A boolean describing if the transaction can continue.

commit_arch_transaction

public boolean commit_arch_transaction()

This method must be called by the reconfiguration agent at the end of the reconfiguration transaction. It forces a check on the new configuration, which is commited or not based upon the result.

Specified by:

commit_arch_transaction in interface ICFMetaInterface

Returns:

The boolean describes of the new configuration was commited. A false means that the last good configuration was rolled back to.

rollback_arch_transaction

public boolean rollback_arch_transaction()

Rolls the configuration back to its previous state - ideally should not be called directly; maybe if faults are being detected is a supposedly valid architecture you may wish to try returning to a stable version.

Specified by:

rollback_arch_transaction in interface ICFMetaInterface

Returns:

A boolean describing if the roll back was a success.

access_CF_graph_lock

public boolean access_CF_graph_lock(int index)

Each component framework implemnts a lock to prevent reconfiguration during functional operation. This method attempts to get read or write access to the lock based upon the input. The locking mechanism is readers, writers with priority for readers.

Specified by:

access_CF_graph_lock in interface ICFMetaInterface

Parameters:

index - An integer describing acces type: 0 for read, 1 for write.

Returns:

A boolean describing if the lock has processed this request or not.

release_CF_graph_lock

public boolean release_CF_graph_lock(int index)

Releases the lock, previously acquired.

Specified by:

release_CF_graph_lock in interface ICFMetaInterface

Parameters:

index - An integer describing acces type: 0 for read, 1 for write.

Returns:

A boolean describing if the lock has processed this request or not.

update_readers_count

public int update_readers_count(int Value)

Update the CF's locks readers count. Do not use - only used by runtime.

Specified by:

update_readers_count in interface ICFMetaInterface

Parameters:

Value - increment amount.

Returns:

An integer describing the new reader count.

enumIntfs

public int enumIntfs(java.util.Vector<java.lang.Class> ppIntfs)

Returns a Vector of meta-information. Each elements of the Vector is a String describing that interface's type.

Specified by:

enumIntfs in interface IMetaInterface

Parameters:

ppRecpMetaInfo - a Vector to be filled with interface meta-information.

Returns:

an Integer describing the number of interfaces on the component.

enumRecps

public int enumRecps(java.util.Vector<OCM_RecpMetaInfo_t> ppRecpMetaInfo)

Returns a Vector of meta-information. Each elements of the Vector is an object of type OCM_RecpMetaInfo_t, which describes the attributes of indiviudal receptacles including: type (single or multiple) & interface type.

Specified by:

enumRecps in interface IMetaInterface

Parameters:

ppRecpMetaInfo - a Vector to be filled with receptacle meta-information.

Returns:

an Integer describing the number of receptacles on the component.

SetAttributeValue

public boolean SetAttributeValue(java.lang.String iid,
                                 java.lang.String Kind,
                                 java.lang.String Name,
                                 java.lang.String Type,
                                 java.lang.Object Value)

Meta-data can be attached to each interface/receptacle of a component. This method adds a name value pair to a given interface or receptacle instance.

Specified by:

SetAttributeValue in interface IMetaInterface

Parameters:

iid - the type of the interface or receptacle.

Kind - a string saying whether to attach to an interface or a receptacle.

Name - A String describing the attribute name.

Type - A String describing the attribute type.

Value - An object representing the attribute value.

Returns:

A boolean indicating the success of the operation.

GetAttributeValue

public TypedAttribute GetAttributeValue(java.lang.String iid,
                                        java.lang.String Kind,
                                        java.lang.String Name)

Meta-data can be retrieved from each interface/receptacle of a component. This method retrieves the value of a name attribute on a receptacle or interface.

Specified by:

GetAttributeValue in interface IMetaInterface

Parameters:

iid - the type of the interface or receptacle.

Kind - a string saying whether to attach to an interface or a receptacle.

Name - A String describing the attribute name.

Returns:

A TypedAttribute object containing the value and type of the meta-data attribute.

GetAllValues

public java.util.Hashtable GetAllValues(java.lang.String Kind,
                                        java.lang.String iid)

This method retrieves all the meta-data stored on the interface or receptacle.

Specified by:

GetAllValues in interface IMetaInterface

Parameters:

iid - the type of the interface or receptacle.

Kind - a string saying whether to attach to an interface or a receptacle.

Returns:

A hashatable containing all of the attribute-value pairs for the receptacle or interface.

connect

public boolean connect(IUnknown pSinkIntf,
                       java.lang.String riid,
                       long provConnID)

disconnect

public boolean disconnect(java.lang.String riid,
                          long connID)