org.openmi.standard
Interface ILinkableComponent

All Superinterfaces:

IPublisher

public interface ILinkableComponent
extends IPublisher

The ILinkableComponent is the key interface in the OpenMI standard. Any OpenMI compliant component must implement ILinkableComponent.

OpenMI compliance definition:

1) An OpenMI compliant component must implement the ILinkableComponent interface according to specifications provided as comments in the org.openmi.standard interface source code.

2) An OpenMI compliant component must, when compiled, reference the org.openmi.standard.jar, which is released and compiled by the OpenMI Association.

3) An OpenMI compliant component must be associated with a XML file, which complies to (can be validated with) the LinkableComponent.xsd schema.

4) An OpenMI compliant component must be associated with a XML file, which complies to (can be validated with) the OpenMICompliancyInfo.xsd schema. This file must be submitted to the OpenMI Association.

5) The OpenMI Association provides two additional interfaces which OpenMI compliant components may or may not implement; the IManageState interface and the IDiscreteTimes interface. However, if these interfaces are implemented, each method and property must implemented according to the comments given in the org.openmi.standard interface source code.

§ 6) The OpenMI Association’s downloadable standard zip file provides the only recognized version of source files, xml schemas and assembly file.

Method Summary

void	addLink(ILink link) Adds a Link to the LinkableComponent This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked.
void	dispose() This method is and must be invoked as the last of any methods in the ILinkableComponent interface.
void	finish() This method is and must be invoked as the second last of any methods in the ILinkableComponent interface.
java.lang.String	getComponentDescription() Describes the ILinkableComponent implementation (the class not the instance/Object) This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.
java.lang.String	getComponentID() Identifies the specific ILinkableComponent implementation (the class not the instance/Object) This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.
ITimeStamp	getEarliestInputTime() The earliestInputTime property defines earliest time for which the LinkableComponent will invoke the GetValues on other LinkableComponent.
IInputExchangeItem	getInputExchangeItem(int inputExchangeItemIndex) Returns the InputExchangeItem corresponding to the inputExchangeItemIndex provided in the method arguments.
int	getInputExchangeItemCount() Defines the number of input exchange items that can be retrieves with the GetInputExchangeItem( ) method.
java.lang.String	getModelDescription() Describes the instance of the LinkableComponent (the instantiated and populated Object) This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.
java.lang.String	getModelID() Identifies the instance of the LinkableComponent (the instantiated and populated Object) This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.
IOutputExchangeItem	getOutputExchangeItem(int outputExchangeItemIndex) Returns the OutputExchangeItem corresponding to the outputExchangeItemIndex provided in the method arguments.
int	getOutputExchangeItemCount() Defines the number of output exchange items that can be retrieves from the GetOutputExchangeItem( ) method.
ITimeSpan	getTimeHorizon() Defines the time span within which the LinkableComponent can return values without using temporal extrapolation.
IValueSet	getValues(ITime time, java.lang.String linkID) Returns a ValuesSet, which is either a ScalarSet or a VectorSet, where the values applies to the time (TimeStamp or TimeSpan) defined in the method arguments and corresponds to the previously added Link, which is identified by the LinkID provided in the method arguments.
void	initialize(IArgument[] properties) Initializes the LinkableComponent.
void	prepare() Prepare for GetValues invocation This method must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.
void	removeLink(java.lang.String linkID) Removes a Link from the LinkableComponent This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked.
java.lang.String	validate() Validates the populated instance of the LinkableComponent This method must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked.

Methods inherited from interface org.openmi.standard.IPublisher

getPublishedEventType, getPublishedEventTypeCount, sendEvent, subscribe, unSubscribe

Method Detail

initialize

void initialize(IArgument[] properties)

Initializes the LinkableComponent.

The Initialize method will and must be invoked before any other method or property in the ILinkableComponent interface is invoked.

When the Initialize methods has been invoked the properties ModelID, ModelDescription, ComponentID, ComponentDescription, InputExchangeItemCount, OutExchangeItemCount, TimeHorizon, and the methods GetInputExchangeItem( ), GetOutputExchangeItem( ), AddLink( ), RemoveLink( ), Validate( ), and Prepare( ) must be prepared for invocation.

It is only required that the method Initialize can be invoked once. If the Initialize method is invoked more that once and the LinkableComponent cannot handle this; an exception must be thrown.

REMARKS:

The properties argument is typically generated based on the information given in the OMI file. The arguments typically contain information about name and location of input files.

The Initialize method will typically populate the component by reading input files, allocate memory, and organize the input exchange items and output exchange items.

Parameters:

properties - see OpenMI.Standard.IArgument interface .

getComponentID

java.lang.String getComponentID()

Identifies the specific ILinkableComponent implementation (the class not the instance/Object)

This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this and exception must be thrown.

EXAMPLE:

"MODFLOW", "Mike 11", "Hydroworks RS", "Sobek", "HEC RAS"

getComponentDescription

java.lang.String getComponentDescription()

Describes the ILinkableComponent implementation (the class not the instance/Object)

This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

EXAMPLE:

"MODFLOW Ground water model", "Mike 11 riveer model", "Hydroworks RS river model", "Sobek river model"

getModelID

java.lang.String getModelID()

Identifies the instance of the LinkableComponent (the instantiated and populated Object)

This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this and exception must be thrown.

EXAMPLE:

"The Rhine river model", "Catchment 23A"

getModelDescription

java.lang.String getModelDescription()

Describes the instance of the LinkableComponent (the instantiated and populated Object)

This property must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this and exception must be thrown.

EXAMPLE:

"The Rhine river model hydrodynamic model, wet season scenario"

getInputExchangeItemCount

int getInputExchangeItemCount()

Defines the number of input exchange items that can be retrieves with the GetInputExchangeItem( ) method.

This property must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

getInputExchangeItem

IInputExchangeItem getInputExchangeItem(int inputExchangeItemIndex)

Returns the InputExchangeItem corresponding to the inputExchangeItemIndex provided in the method arguments.

This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

This method basically returns a reference to the InputExchangeItem Object. There is no guarantee that this Object is not altered by other components after it has been returned. It is the responsibility of the LinkableComponent to make sure that such possible alterations does not subsequently corrupt the LinkableComponent.

Parameters:

inputExchangeItemIndex - Identifies the index-number of the requested InputExchangeItem (indexing starts from zero) This method must accept values of inputExchangeItemIndex in the interval [0, InputExchangeItemCount - 1]. If the inputExchangeItemIndex is outside this interval an exception must be thrown.

Returns:

The InputExchangeItem as identified by inputExchangeItemIndex.

getOutputExchangeItemCount

int getOutputExchangeItemCount()

Defines the number of output exchange items that can be retrieves from the GetOutputExchangeItem( ) method.

This property must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

getOutputExchangeItem

IOutputExchangeItem getOutputExchangeItem(int outputExchangeItemIndex)

Returns the OutputExchangeItem corresponding to the outputExchangeItemIndex provided in the method arguments.

This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

This method basically returns a reference to the OutputExchangeItem Object. There is no guarantee that this Object is not altered by other components after it has been returned. It is the responsibility of the LinkableComponent to make sure that such possible alterations does not subsequently corrupt the LinkableComponent.

Parameters:

outputExchangeItemIndex - Identifies the index-number of the requested OutputExchangeItem (indexing starts from zero) This method must accept values of outputExchangeItemIndex in the interval [0, OutputExchangeItemCount - 1]. If the outputExchangeItemIndex is outside this interval an exception must be thrown.

Returns:

The OutputExchangeItem as identified by inputExchangeItemIndex.

getTimeHorizon

ITimeSpan getTimeHorizon()

Defines the time span within which the LinkableComponent can return values without using temporal extrapolation. For numerical models this is typically the time horizon of the available input data. If the LinkableComponent does not know time at all or of the LinkableComponent can provide data at any time null should be returned.

Note that the GetValues( ) method may be invoked with time arguments that outside the time horizon defined in this method. In this case the linkable component may return extrapolated values or throw an exception if the sound values cannot be generated by means of extrapolation.

This property must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

addLink

void addLink(ILink link)

Adds a Link to the LinkableComponent

This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

Parameters:

link - Link to be added.

removeLink

void removeLink(java.lang.String linkID)

Removes a Link from the LinkableComponent

This method must be accessible after the Initialize( ) method has been invoked and until the Prepare( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Prepare( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

If the LinkID is not recognized an exception must be thrown

Parameters:

linkID - LinkID for the link to be removed.

validate

java.lang.String validate()

Validates the populated instance of the LinkableComponent

This method must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

Returns:

Returns an empty String if the component is valid otherwise returns a message

prepare

void prepare()

Prepare for GetValues invocation

This method must be accessible after the Initialize( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Initialize( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

It is only required that the Prepare( ) method can be invoked once. If the Prepare method is invoked more that once and the LinkableComponent cannot handle this an exception must be thrown.

getValues

IValueSet getValues(ITime time,
                    java.lang.String linkID)

Returns a ValuesSet, which is either a ScalarSet or a VectorSet, where the values applies to the time (TimeStamp or TimeSpan) defined in the method arguments and corresponds to the previously added Link, which is identified by the LinkID provided in the method arguments.

The number of Scalars or Vectors must match the number of elements in the target ElementSet as defined in Link.TargetElementSet.ElementCount

The GetValues method must accept requests for data for any previously added link. If the LinkID is not recognized an exception must be thrown.

If the Unit conversion factor and/or the Unit offset of the provided quantity does not match the Unit conversion factor and/or the Unit offset of the accepting quantity, unit conversion must be performed so the provided values corresponds to the unit of the accepting quantity.

If the accepting ElementSet is geo-referenced the provided values must be converted to apply to the geometry of the elements in the accepting ElementSet.

If the LinkableComponent at the time when the GetValues method is invoked has invoked the GetValues method on the invoking LinkableComponet and this component has not yet return the values, the LinkableComponent may not re-invoke the GetValues method again on that component until it has returned the values.

The GetValues method is not required to return values for times outside the TimeHorizon of the LinkableComponent. If the GetValues method is invoked with a time argument that is outside the TimeHorizon of the LinkableComponent and the LinkableComponent cannot handle such invocation an exception must be thrown.

The GetValues method is not required to return values before the time defined by the EarliestInputTime property of the accepting component. If the GetValues method is invoked with a time argument that is before this time and the LinkableComponent cannot handle this an exception must be thrown

The LinkableComponent must send the SourceAfterGetValuesCall event immediately after the GetValues method is invoked. The LinkableComponent must send the SourceBeforeGetValuesReturn event immediately preceding it returns the values. If the LinkableComponent invokes GetValues in an other LinkableComponents it must send the TargetBeforeGetValuesCall event immediately preceding the GetValues invocation and the TargetAfterGetValuesReturn event immediately after the invoked LinkableComponent has retuned the values. If the LinkableComponent is progressing time steps or changing state the TimeStepProgress event and/or the DataChange event, respectively must be send.

The GetValues method must be accessible after the Prepare( ) method has been invoked and until the Finish( ) method has been invoked. If this Method is accessed before the Prepare( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

This method basically returns a reference to the ValueSet Object. There is no guarantee that this Object is not altered by other components after it has been returned. It is the responsibility of the LinkableComponent to make sure that such possible alterations does not subsequently corrupt the LinkableComponent.

Parameters:

time - The time for which the values are requested.

linkID - ID for the previously added link Object.

Returns:

ValueSet corresponding the the time and LinkID argument (ScalarSet or VectorSet)

getEarliestInputTime

ITimeStamp getEarliestInputTime()

The earliestInputTime property defines earliest time for which the LinkableComponent will invoke the GetValues on other LinkableComponent. The LinkableComponent must ensure that earliestInputTime property always reflects the latest possible time. When the earliestInputTime property is updated the updated time must always be later than any previous times exposed by this property

This property must be accessible after the Prepare( ) method has been invoked and until the Finish( ) method has been invoked. If this property is accessed before the Prepare( ) method has been invoked or after the Finish( ) method has been invoked and the LinkableComponent cannot handle this an exception must be thrown.

REMARKS:

Most time stepping numerical models keeps typically only the calculated values corresponding to the current time step and the previous time step in memery. In order to enable the LinkableComponent to return values before that an internal buffer is typically established for each link added to this component. The earliestInputTime property on the LinkableComponent to which such component is linked is typically used to detect which time related data that can be removed from these buffers.

finish

void finish()

This method is and must be invoked as the second last of any methods in the ILinkableComponent interface.

This method must be accessible after the Initialize( ) method has been invoked and before the Dispose( ) method has been invoked. If this method is invoked before the Initialize( ) method has been invoked or after the Dispose( ) methods has been invoked and the LinkableComponent cannot handled this an exception must be thrown.

dispose

void dispose()

This method is and must be invoked as the last of any methods in the ILinkableComponent interface.

This method must be accessible after the Finish( ) method has been invoked. If this method is invoked before the Finish( ) method has been invoked and the LinkableComponent cannot handled this an exception must be thrown.