ubiware.core
Class ReusableAtomicBehavior

java.lang.Object
  ubiware.core.ReusableAtomicBehavior

All Implemented Interfaces:

ParametrizedAsset

Direct Known Subclasses:

AbstractAgentCreationBehavior, BeliefsLoadBehavior, DebugBehavior, DeleteAgentBehavior, DFLookupBehavior, DFRegisterBehavior, RABRepositoryLookupBehavior

public abstract class ReusableAtomicBehavior
extends java.lang.Object
implements ParametrizedAsset

ReusableAtomicBehavior provides a base class for all behaviours which this agent is running. These behaviours are normally instantiated by the UbiwareAgent live cycle. The behaviour implements a function for the agent.
Note: when using addBeliefsN3, removeBeliefsN3, and hasBeliefsN3 with String arguments, one must either use the full URIs or include needed @prefix statements into the Notation3 string.

Author:

Michael Cochez for UBIWARE project

Field Summary

protected boolean	finished Is this RAB finished? Should it still run? Since every RAB is by default a one shot behavior, initially set to true.
(package private) java.lang.String	ID The ID of this RAB.
(package private) java.util.Set<java.lang.String>	linkedContexts If I understand correctly, the linkedcontexts keeps IDs of contexts which are referenced from inside the rab in order to prevent removal by the Ubiware Agent
protected UbiwareAgent	myAgent Deprecated. This reference is deprecated since RAB's should not depend directly on the implementation of the agent for functionality.

Constructor Summary

ReusableAtomicBehavior()
Every RAB must have at least a default constructor.

Method Summary

(package private) void	action() This method is called by the agent when this RAB must perform its action.
void	addBeliefs(java.lang.String contextOrStatementID, java.util.HashMap<java.lang.String,java.lang.String> vars) Deprecated. Use the version with S-APL document if possible!
void	addBeliefsN3(ubiware.util.saplbuilder.SaplDocument document) This is the advised way to add S-APL beliefs to the agent.
boolean	addBeliefsN3(java.lang.String n3string) Deprecated. use addBeliefsN3(SaplDocument) instead for type safety
boolean	addBeliefsN3(java.lang.String n3string, boolean doChecks) Deprecated. use addBeliefsN3(SaplDocument) instead for type safety
protected void	addCommand(UbiwareAgentCommand<?> command)
ubiware.util.saplbuilder.Resource	addOnBlackboard(java.lang.Object o) Add an object to blackboard, return the ID of the created object
void	block() Blocks this behaviour.
void	block(long millis) Blocks this behaviour the specified amount of time.
protected abstract void	doAction() Derived RAB's should implement this method and do their action within it.
boolean	done()
boolean	equals(java.lang.Object obj) Two rab's are only equal if they are the same RAB!
void	eraseBeliefs(java.lang.String beliefID) Erases a statement or a context specified by its ID.: ID can be of a context or a statement
java.lang.Object	getFromBlackboard(ubiware.util.saplbuilder.Resource id) returns an object from blackboard of the UbiwareAgent
java.util.List<SemanticStatement>	getStatements(java.lang.String contextID) Returns the vector of copies of statements in a context container.
java.util.List<SemanticStatement>	getStatements(java.lang.String contextID, java.util.List<java.lang.String> ids) returns the vector of copies of statements in a context container (+ a fills a vector of their original IDs)
boolean	hasBeenExecuted() Has this RAB been executed at least once?
BindingsSet	hasBeliefs(java.lang.String statementID) Same as hasBeliefs(String, String) with queryContextID set to UbiwareAgent.GENERAL_CONTEXT
BindingsSet	hasBeliefs(java.lang.String contextOrStatementID, java.lang.String queryContextID) returns possible bindings of variables to beliefs given (with ID can be of a context or a statement)
BindingsSet	hasBeliefsN3(ubiware.util.saplbuilder.SaplDocument document) Returns all possible bindings of variables (from the agents global context G) to the query specified in the S-APL document Returns possible solutions (combinations of bindings of variables) to match beliefs specified in an S-APL (Notation3) string.
BindingsSet	hasBeliefsN3(ubiware.util.saplbuilder.SaplDocument document, java.lang.String queryContextID) Returns all possible bindings of variables (from the specified queryContext) to the query specified in the S-APL document
BindingsSet	hasBeliefsN3(java.lang.String n3string) Deprecated. Use hasBeliefsN3(SaplDocument, String) instead
BindingsSet	hasBeliefsN3(java.lang.String n3string, java.lang.String queryContextID) Deprecated. Use hasBeliefsN3(SaplDocument, String) instead
int	hashCode()
boolean	hasSucceededTillNow() returns true iff the RAB has succeeded in its operation up to this point.
protected abstract void	initializeRAB(BehaviorStartParameters parameters) Derived RAB's should implement this method and initialise all the needed parameters to run the RAB.
void	moveBeliefs(java.lang.String contextID) moves all links from a context to General Context and removes the former context
(package private) int	onEnd() Callled by the ubiware agent when this RAB ends, calls in turn onRABEnd
void	onRABEnd() Method called once when this RAB is ended.
(package private) void	onStart() callled by the ubiware agent when this RAB starts, calls in turn this#onRABStart() and this initializeRAB(BehaviorStartParameters)
void	print(java.lang.Object text) Prints to the screen (and to the log) specified text.
protected void	printError(java.lang.String message) Forwards the message this.getClass().getName() + "error: " + message to print(Object)
java.lang.String	produceN3(java.lang.String contextID) Deprecated. use the version which returns a document instead.
java.lang.String	produceN3(java.lang.String contextID, ProduceN3Options options) Deprecated. use the version which returns a document instead.
ubiware.util.saplbuilder.SaplDocument	produceN3Document(java.lang.String contextID)
ubiware.util.saplbuilder.SaplDocument	produceN3Document(java.lang.String contextID, ProduceN3Options options) * Returns an S-APL (Notation3) string corresponding to a sub-graph starting with context container given.
void	removeBeliefs(java.lang.String beliefID) Deprecated. Use the version with S-APL document if possible!
void	removeBeliefsN3(ubiware.util.saplbuilder.SaplDocument document) Remove beliefs according to pattern specified in a S-APL document
void	removeBeliefsN3(java.lang.String n3string) Deprecated. Use removeBeliefsN3(SaplDocument) instead
void	removeFromBlackboard(ubiware.util.saplbuilder.Resource id) Removes an object from blackboard.
void	restart() Restarts a blocked behaviour.
protected void	sendMessage(int performative, ubiware.util.saplbuilder.Resource receiver, ubiware.util.saplbuilder.SaplDocument messageContent, java.lang.String ontology, java.lang.String conversationID)
protected void	sendMessage(int performative, ubiware.util.saplbuilder.Resource receiver, java.lang.String messageContent, java.lang.String ontology, java.lang.String conversationID) Deprecated. Use the version with sapl document instead.
(package private) void	setAgent(UbiwareAgent agent) Set the agent which is executing this RAB.
(package private) void	setEncapsulatingBehavior(jade.core.behaviours.Behaviour behavior) Set the behavior which encapsulates this RAB.
void	setFailed() Marks this RAB as being failed, this used to be done by setting the success flag to false (this.success = false) This new approach must ensure that once the RAB has been marked as failed, it cannot be marked as a success again.
void	setStartParameters(BehaviorStartParameters startParams) Set the start parameters for this behavior.
void	wakeAgent() Informs the agent that it must wake up its Live behavior to check whether new rules became applicable.

Methods inherited from class java.lang.Object

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

Field Detail

finished

protected boolean finished

Is this RAB finished? Should it still run? Since every RAB is by default a one shot behavior, initially set to true. Deriving RAB's can change this value to false to indicate that the behavior has not finished yet.

myAgent

@Deprecated
protected UbiwareAgent myAgent

Deprecated. This reference is deprecated since RAB's should not depend directly on the implementation of the agent for functionality.

Reference to the agent on which this RAB is scheduled. Enables behaviors to call public methods of UbiwareAgent such as send(), receive(), doMove() and other

ID

java.lang.String ID

The ID of this RAB.

linkedContexts

java.util.Set<java.lang.String> linkedContexts

If I understand correctly, the linkedcontexts keeps IDs of contexts which are referenced from inside the rab in order to prevent removal by the Ubiware Agent

Constructor Detail

ReusableAtomicBehavior

public ReusableAtomicBehavior()

Every RAB must have at least a default constructor. This because the agent runtime will instantiate the behavior using java reflection searching for a default constructor.

Method Detail

action

final void action()

This method is called by the agent when this RAB must perform its action. The action will only be called if this RAB was successful until now. This means that parameterinitialisation and any previous doAction call returned without trowing exceptions.

doAction

protected abstract void doAction()
                          throws java.lang.Exception

Derived RAB's should implement this method and do their action within it. The derived RAB can assume that doAction is never called without a successful call to initializeRAB(BehaviorStartParameters)

Throws:

java.lang.Exception

setAgent

final void setAgent(UbiwareAgent agent)

Set the agent which is executing this RAB. This is done by the ubiware agent itself once this RAB is added to the agent.

Parameters:

agent -

setEncapsulatingBehavior

final void setEncapsulatingBehavior(jade.core.behaviours.Behaviour behavior)

Set the behavior which encapsulates this RAB. This is done by the ubiware agent itself once this RAB is added to the agent.

Parameters:

behavior -

setFailed

public final void setFailed()

Marks this RAB as being failed, this used to be done by setting the success flag to false (this.success = false) This new approach must ensure that once the RAB has been marked as failed, it cannot be marked as a success again. (The flag can only be set, not unset)

hasSucceededTillNow

public final boolean hasSucceededTillNow()

returns true iff the RAB has succeeded in its operation up to this point. (The setFailed() method has not been called)

Returns:

only true as long as setfailed has not been called.

block

public final void block()

Blocks this behaviour. If this method is called from within action() method, behaviour suspension occurs as soon as action() returns. And as long as no new message arrives or no explicit restart is called on the behavior.

block

public final void block(long millis)

Blocks this behaviour the specified amount of time. If this method is called from within action() method, behaviour suspension occurs as soon as action() returns. The behaviour will be restarted when among the three following events happens. A time of millis milliseconds has passed since the call to block(). An ACL message is received by the agent this behaviour belongs to. Method restart() is called explicitly on this behaviour object.

Parameters:

millis - How many milliseconds should this behavior be blocked.

restart

public final void restart()

Restarts a blocked behaviour.

setStartParameters

public final void setStartParameters(BehaviorStartParameters startParams)

Set the start parameters for this behavior.

Specified by:

setStartParameters in interface ParametrizedAsset

Parameters:

startParams - the parameters.

onStart

final void onStart()

callled by the ubiware agent when this RAB starts, calls in turn this#onRABStart() and this initializeRAB(BehaviorStartParameters)

initializeRAB

protected abstract void initializeRAB(BehaviorStartParameters parameters)
                               throws IllegalParameterConfigurationException

Derived RAB's should implement this method and initialise all the needed parameters to run the RAB. The supplied parameters object might become invalid after this call.

Parameters:

parameters - The parameters specified by the user of this RAB.

Throws:

IllegalParameterConfigurationException - If one of the parameters isn't correctly given.

onEnd

final int onEnd()

Callled by the ubiware agent when this RAB ends, calls in turn onRABEnd

onRABEnd

public void onRABEnd()

Method called once when this RAB is ended. Hook to be overridden if desired for example if resources have to be cleaned up. This method will also be called if the initialisation of the RAB failed.

done

public final boolean done()

Returns:

Has this behavior finished its job and can it be removed from the agent scheduler.

print

public void print(java.lang.Object text)

Prints to the screen (and to the log) specified text. Text is printed preceded by �[] :"

Parameters:

text - The Object from which the text must be made (using Object.toString())

wakeAgent

public final void wakeAgent()

Informs the agent that it must wake up its Live behavior to check whether new rules became applicable.

addBeliefs

@Deprecated
public final void addBeliefs(java.lang.String contextOrStatementID,
                                        java.util.HashMap<java.lang.String,java.lang.String> vars)

Deprecated. Use the version with S-APL document if possible!

adds beliefs (copies a sub-graph given with ID can be of a context or a statement) with binding variables (if given)

Parameters:

contextOrStatementID - the the statement or context which should be copied

vars - The variable association which should be used in the copy action.

addBeliefsN3

@Deprecated
public final boolean addBeliefsN3(java.lang.String n3string,
                                             boolean doChecks)

Deprecated. use addBeliefsN3(SaplDocument) instead for type safety

adds beliefs defined by a N3 string

Parameters:

n3string - the S-APL string which must be added to the agent.

doChecks - should checks be performed for joining containers

Returns:

true is beliefs are added. False if either adding beliefs failed or no beliefs where added.

addBeliefsN3

@Deprecated
public final boolean addBeliefsN3(java.lang.String n3string)

Deprecated. use addBeliefsN3(SaplDocument) instead for type safety

Same as addBeliefsN3(String, boolean) with doChecks set to true

Parameters:

n3string - The string of S-APL which should get added to the agent's beliefs structure.

Returns:

true if beliefs are added. False if either adding beliefs failed or no beliefs where added.

addBeliefsN3

public final void addBeliefsN3(ubiware.util.saplbuilder.SaplDocument document)

This is the advised way to add S-APL beliefs to the agent. Create an S-APL document and feed it to this function from within the agent's thread. For example from inside an RAB.

Parameters:

document - The S-APL beliefs' structure which should be added to the agent.

removeBeliefs

@Deprecated
public final void removeBeliefs(java.lang.String beliefID)

Deprecated. Use the version with S-APL document if possible!

remove beliefs by pattern given (ID can be of a context or a statement)

Parameters:

beliefID - the ID of the context or statement specifying the beliefs to be removed.

removeBeliefsN3

@Deprecated
public final void removeBeliefsN3(java.lang.String n3string)

Deprecated. Use removeBeliefsN3(SaplDocument) instead

Removes beliefs according to pattern specified in an S-APL (Notation3) string.

Parameters:

n3string - The String containing the S-APL code to be added to the agent.

removeBeliefsN3

public final void removeBeliefsN3(ubiware.util.saplbuilder.SaplDocument document)

Remove beliefs according to pattern specified in a S-APL document

Parameters:

document - The document containing the S-APL pattern to be removed to the agent.

eraseBeliefs

public final void eraseBeliefs(java.lang.String beliefID)

Erases a statement or a context specified by its ID.: ID can be of a context or a statement

Parameters:

beliefID -

hasBeliefs

public final BindingsSet hasBeliefs(java.lang.String contextOrStatementID,
                                    java.lang.String queryContextID)

returns possible bindings of variables to beliefs given (with ID can be of a context or a statement)

Parameters:

contextOrStatementID -

queryContextID -

Returns:

The set with bindings for the query.

hasBeliefs

public final BindingsSet hasBeliefs(java.lang.String statementID)

Same as hasBeliefs(String, String) with queryContextID set to UbiwareAgent.GENERAL_CONTEXT

Parameters:

statementID -

Returns:

The set with bindings for the query.

hasBeliefsN3

public final BindingsSet hasBeliefsN3(ubiware.util.saplbuilder.SaplDocument document,
                                      java.lang.String queryContextID)

Returns all possible bindings of variables (from the specified queryContext) to the query specified in the S-APL document

Parameters:

document - The document containing the query

queryContextID - The context into which matches to the query must be searched.

Returns:

A BindingsSet containing all possible bindings to the variables specified.

hasBeliefsN3

public final BindingsSet hasBeliefsN3(ubiware.util.saplbuilder.SaplDocument document)

Returns all possible bindings of variables (from the agents global context G) to the query specified in the S-APL document Returns possible solutions (combinations of bindings of variables) to match beliefs specified in an S-APL (Notation3) string. Returns null if no match is found.

Parameters:

document - The document containing the query

Returns:

A BindingsSet containing all possible bindings to the variables specified.

hasBeliefsN3

@Deprecated
public final BindingsSet hasBeliefsN3(java.lang.String n3string,
                                                 java.lang.String queryContextID)

Deprecated. Use hasBeliefsN3(SaplDocument, String) instead

Returns all possible bindings of variables (from the specified queryContext) to the query specified in the S-APL string Returns possible solutions (combinations of bindings of variables) to match beliefs specified in an S-APL (Notation3) string. Returns null if no match is found.

Parameters:

n3string - The String containing the query

queryContextID - The context into which matches to the query must be searched.

Returns:

A BindingsSet containing all possible bindings to the variables specified.

hasBeliefsN3

@Deprecated
public final BindingsSet hasBeliefsN3(java.lang.String n3string)

Deprecated. Use hasBeliefsN3(SaplDocument, String) instead

Returns all possible bindings of variables (from the agents global context G) to the query specified in the S-APL document Returns possible solutions (combinations of bindings of variables) to match beliefs specified in an S-APL (Notation3) string. Returns null if no match is found.

Parameters:

n3string - The String containing the query

Returns:

A BindingsSet containing all possible bindings to the variables specified.

moveBeliefs

public final void moveBeliefs(java.lang.String contextID)

moves all links from a context to General Context and removes the former context

Parameters:

contextID -

produceN3

@Deprecated
public final java.lang.String produceN3(java.lang.String contextID)

Deprecated. use the version which returns a document instead.

Same as produceN3(String, ProduceN3Options) with the default options.

Parameters:

contextID - The context for which S-APL must be generated.

Returns:

The produced S-APL code

produceN3

@Deprecated
public final java.lang.String produceN3(java.lang.String contextID,
                                                   ProduceN3Options options)

Deprecated. use the version which returns a document instead.

Returns an S-APL (Notation3) string corresponding to a sub-graph starting with context container given. The class ProduceN3Options has following boolean fields: indents (default true), cleanContent (default false), and useNameSpaces (default true). If indents = true, the line breaks and indentation are used. If cleanContent = true, the content is cleaned in the sense that potential query constructs such as Optional, or, filtering are not included. If useNameSpaces = true, the known namespaces are substituted with their prefixes.

Parameters:

contextID - The context ID for which N3 must be produced.

options - The options for production.

Returns:

The produced N3

produceN3Document

public final ubiware.util.saplbuilder.SaplDocument produceN3Document(java.lang.String contextID)

produceN3Document

public final ubiware.util.saplbuilder.SaplDocument produceN3Document(java.lang.String contextID,
                                                                     ProduceN3Options options)

* Returns an S-APL (Notation3) string corresponding to a sub-graph starting with context container given. The class ProduceN3Options has following boolean fields: indents (default true), cleanContent (default false), and useNameSpaces (default true). If indents = true, the line breaks and indentation are used. If cleanContent = true, the content is cleaned in the sense that potential query constructs such as Optional, or, filtering are not included. If useNameSpaces = true, the known namespaces are substituted with their prefixes.

Parameters:

contextID - The context ID for which N3 must be produced.

options - The options for production.

Returns:

The produced N3

getStatements

public final java.util.List<SemanticStatement> getStatements(java.lang.String contextID,
                                                             java.util.List<java.lang.String> ids)

returns the vector of copies of statements in a context container (+ a fills a vector of their original IDs)

Parameters:

contextID - the context which should be copied.

ids - This is an in-out parameter! To this list, the IDs of the original statements will be added.

Returns:

The copies.

getStatements

public final java.util.List<SemanticStatement> getStatements(java.lang.String contextID)

Returns the vector of copies of statements in a context container. SemanticStaments objects have three String data members: subject, predicate and object.

Parameters:

contextID - The context ID which should eb copied.

Returns:

The list of semantic statements. Keep in mind that this list is in unspecified order.

addOnBlackboard

public final ubiware.util.saplbuilder.Resource addOnBlackboard(java.lang.Object o)

Add an object to blackboard, return the ID of the created object

Parameters:

o - the Object which should be put on the Blackboard of the UbiwareAgent

Returns:

The ID of the created object which can be used for later retrieval.

removeFromBlackboard

public final void removeFromBlackboard(ubiware.util.saplbuilder.Resource id)

Removes an object from blackboard.

Parameters:

id - The ID of the Blackboard object

getFromBlackboard

public final java.lang.Object getFromBlackboard(ubiware.util.saplbuilder.Resource id)

returns an object from blackboard of the UbiwareAgent

Parameters:

id - the id of the Blackboard object

Returns:

The Object associated with this ID.

hasBeenExecuted

public final boolean hasBeenExecuted()

Has this RAB been executed at least once?

Returns:

only true if this RAB has been executed before.

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

See Also:

Object.hashCode()

equals

public boolean equals(java.lang.Object obj)

Two rab's are only equal if they are the same RAB!

Overrides:

equals in class java.lang.Object

See Also:

Object.equals(java.lang.Object)

printError

protected final void printError(java.lang.String message)

Forwards the message this.getClass().getName() + "error: " + message to print(Object)

sendMessage

protected void sendMessage(int performative,
                           ubiware.util.saplbuilder.Resource receiver,
                           ubiware.util.saplbuilder.SaplDocument messageContent,
                           java.lang.String ontology,
                           java.lang.String conversationID)

sendMessage

@Deprecated
protected void sendMessage(int performative,
                                      ubiware.util.saplbuilder.Resource receiver,
                                      java.lang.String messageContent,
                                      java.lang.String ontology,
                                      java.lang.String conversationID)

Deprecated. Use the version with sapl document instead.

Same as the other send message, but with string content

Parameters:

performative -

receiver -

messageContent -

ontology -

conversationID -

addCommand

protected void addCommand(UbiwareAgentCommand<?> command)