org.primordion.xholon.base
Interface IPort

All Superinterfaces:
IXholon
All Known Implementing Classes:
Port

public interface IPort
extends IXholon

IPort defines the abstract services that ports provide. A port is a window into the world external to its owning xholon, or to some part or parts of the xholon. A port has three basic responsibilites: (1) Locate other xholons with which this xholon can interact and establish one-way links, (2) Send messages from a sender xholon to one or more receiver xholons through a link, (3) Know what message types can be sent and received across a particular link and optionally use this knowledge to validate and restrict link establishment and/or message traffic.

Since:
0.4 (Created on August 21, 2006)
Author:
Ken Webb

Field Summary
static int XPATH_EXPR_NO_INDEX
          XPath expression, no index
static char XPATH_EXPR_WILDCARD
          XPath expression template wildcard.
 
Fields inherited from interface org.primordion.xholon.base.IXholon
DEFAULT_SIZE_MSG_Q, NINCLUDE_PSC, NINCLUDE_PSx, NINCLUDE_PxC, NINCLUDE_Pxx, NINCLUDE_xSC, NINCLUDE_xSx, NINCLUDE_xxC, NINCLUDE_xxx
 
Method Summary
 boolean getIsConjugated()
          Get whether or not this is a conjugated port.
 IXholon getLink(int index)
          Get the link from a local port replication to a remote port or xholon.
 IPortInterface getProvidedInterface()
          Get the provided interface of this port.
 IPortInterface getRequiredInterface()
          Get the required interface of this port.
 void sendMessage(int signal, java.lang.Object data, IXholon sender, int index)
          Send a ROOM/UML2 message through a local instance of a replicated port to a remote replicated port instance or directly to a remote xholon, or from a remote port replication to its owning xholon.
 void setIsConjugated(boolean isConjugated)
          Set whether or not this is a conjugated port.
 boolean setLink(int index, IXholon context, java.lang.String xpathExpression)
          Set the link from a local port replication to a remote port or xholon.
 boolean setLink(int index, IXholon context, java.lang.String xpathExprTemplate, int xholonIx, int portIx, int replicationIx)
          Set the link from a local port replication to a remote port or xholon.
 void setProvidedInterface(IPortInterface providedInterface)
          Set the provided interface of this port.
 void setReplications(int multiplicity)
          Set the replication factor of a remote port, and create the remote port.
 void setRequiredInterface(IPortInterface requiredInterface)
          Set the required interface of this port.
 
Methods inherited from interface org.primordion.xholon.base.IXholon
act, appendChild, appendChild, appendChild, cleanup, configure, configure, createStructure, decVal, decVal, depth, draw, getChildNodes, getFirstChild, getFirstSibling, getId, getLastChild, getLastSibling, getName, getNeighbors, getNextSibling, getNthChild, getNthSibling, getNumChildren, getNumSiblings, getParentNode, getPort, getPreviousSibling, getRoleName, getRootNode, getSiblings, getUid, getVal_boolean, getVal_byte, getVal_char, getVal_double, getVal_float, getVal_int, getVal_long, getVal_Object, getVal_short, getVal_String, getVal, getXhc, getXhcId, getXhcName, getXhType, handleNodeSelection, hasAncestor, hasChildNodes, hasChildOrSiblingNodes, hasNextSibling, hasParentNode, height, incVal, incVal, initialize, initStatics, inOrderPrint, insertAfter, insertBefore, insertFirstChild, isActiveObject, isBound, isContainer, isExternal, isInternal, isLeaf, isPassiveObject, isRootNode, performActivity, performActivity, performBooleanActivity, performBooleanActivity, performDoubleActivity, performGuard, performVoidActivity, postAct, postConfigure, postOrderPrint, postReconfigure, preAct, preConfigure, preOrderPrint, preReconfigure, print, println, processMessageQ, processReceivedMessage, reconfigure, remove, removeChild, sendMessage, sendMessage, setAttributeVal, setFirstChild, setId, setNextSibling, setParentChildLinks, setParentNode, setParentSiblingLinks, setPorts, setRoleName, setUid, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVal, setVariableValue, setXhc, swapNode, terminate, treeSize, writeXml
 

Field Detail

XPATH_EXPR_WILDCARD

public static final char XPATH_EXPR_WILDCARD
XPath expression template wildcard.

See Also:
Constant Field Values

XPATH_EXPR_NO_INDEX

public static final int XPATH_EXPR_NO_INDEX
XPath expression, no index

See Also:
Constant Field Values
Method Detail

setProvidedInterface

public void setProvidedInterface(IPortInterface providedInterface)
Set the provided interface of this port. These are the behavioral features that the owning xholon provides to its environment through this port. In practical terms, on a non-conjugated port, these are the signals that are allowed in incoming messages received at this port. On a conjugated port, these are the signals that are allowed in outoing messages.

Parameters:
providedInterface - An array of zero or more signal IDs.

getProvidedInterface

public IPortInterface getProvidedInterface()
Get the provided interface of this port. These are the behavioral features that the owning xholon provides to its environment through this port. In practical terms, on a non-conjugated port, these are the signals that are allowed in incoming messages received at this port. On a conjugated port, these are the signals that are allowed in outoing messages.

Returns:
An array of zero or more signal IDs.

setRequiredInterface

public void setRequiredInterface(IPortInterface requiredInterface)
Set the required interface of this port. These are the services that the owning xholon expects from its environment through this port. In practical terms, on a non-conjugated port, these are the signals that are allowed in outgoing messages sent from this port. On a conjugated port, these are the signals that are allowed in incoming messages.

Parameters:
requiredInterface - An array of zero or more signal IDs.

getRequiredInterface

public IPortInterface getRequiredInterface()
Get the required interface of this port. These are the services that the owning xholon expects from its environment through this port. In practical terms, on a non-conjugated port, these are the signals that are allowed in outgoing messages sent from this port. On a conjugated port, these are the signals that are allowed in incoming messages.

Returns:
An array of zero or more signal IDs.

setIsConjugated

public void setIsConjugated(boolean isConjugated)
Set whether or not this is a conjugated port. In a non-conjugated port, the provided and required interfaces are as set. In a conjugated port, they are reversed.

Parameters:
isConjugated - true (conjugated) or false (non-conjugated). default: false

getIsConjugated

public boolean getIsConjugated()
Get whether or not this is a conjugated port.

Returns:
true (conjugated) or false (non-conjugated).

setReplications

public void setReplications(int multiplicity)
Set the replication factor of a remote port, and create the remote port.

Parameters:
multiplicity - The maximum number of instances of the remote port.

setLink

public boolean setLink(int index,
                       IXholon context,
                       java.lang.String xpathExprTemplate,
                       int xholonIx,
                       int portIx,
                       int replicationIx)
Set the link from a local port replication to a remote port or xholon.

Parameters:
index - Index of the local replicated port on which the link is to be set.
context - The xholon that owns the port and port replication.
xpathExprTemplate - XPath expression template.
xholonIx - Remote xholon index, used to fill in a value in the template. If there is no index, then the value must be XPATH_EXPR_NO_INDEX.
portIx - Remote port index, used to fill in a value in the template. If there is no index, then the value must be XPATH_EXPR_NO_INDEX.
replicationIx - Remote replication index, used to fill in a value in the template. If there is no index, then the value must be XPATH_EXPR_NO_INDEX.

setLink

public boolean setLink(int index,
                       IXholon context,
                       java.lang.String xpathExpression)
Set the link from a local port replication to a remote port or xholon. Only a client can set up a link, which must be a link to a server. A client is a port specified in UML as isService=false, and in Xholon as isConjugated=true. A server is a port specified in UML as isService=true, and in Xholon as isConjugated=false. A link will consist of two one-directional connections if both ends can legally send signals. The provided and required interfaces are specified in terms of the server. If a server has one or more signals specified for its provided interface, then a connection will be established from its client(s) to the server. If a server has one or more signals specified for its required interface, then a connection will be established from the server to its client(s). TODO How to handle a symmetrical link where provided and required IF are equal.

Parameters:
index - Index of the local replicated port on which the link is to be set.
context - The xholon that owns the port and port replication.
xpathExpression - Complete XPath expression.
Returns:
false (remote port or xholon can't be found) or true (can be found)

getLink

public IXholon getLink(int index)
Get the link from a local port replication to a remote port or xholon. Hide the internal details of how this is done. Currently the nextSibling is being used internally to store the link, but this may change.

Parameters:
index - Index of the local replicated port.
Returns:
The remote port or xholon, or null if there is none.

sendMessage

public void sendMessage(int signal,
                        java.lang.Object data,
                        IXholon sender,
                        int index)
Send a ROOM/UML2 message through a local instance of a replicated port to a remote replicated port instance or directly to a remote xholon, or from a remote port replication to its owning xholon.

Specified by:
sendMessage in interface IXholon
Parameters:
signal - A distinguishing identifier for this message.
data - Any data that needs to be sent (optional).
sender - The sender of the message.
index - Index of a replicated port (0 indexed).