jcama
Class Scope

java.lang.Object
  jcama.Scope

public final class Scope
extends java.lang.Object

Provides scoping and communication operations to agents. It implements all the basic Linda operations and a set of additional tuple space operations. Along with data input/output through tuple space this class provide interface to CAMA scoping mechanism.

Field Summary

protected java.io.ByteArrayOutputStream	buffer
static int	BUFFER_SIZE_INIT
protected int	contextNum
protected int	eKey
protected java.lang.String	litName
protected Location	location
protected ScopeName	name

Method Summary

Scope	CreateScope(java.lang.String name, ScopeDescr descr) Creates a new scope with the given scope requirements.
void	DeleteScope() Deletes a scope.
void	Disengage() Disconnect from the location
void	gd(int roleid, java.lang.String templ)
void	gd(int roleid, Templ templ)
ScopeName	GetScopes(CamaKey scopeType) Returns all the public sub-scopes of the curent scope
void	gr(int roleid, java.lang.String templ)
void	gr(int roleid, Templ templ)
void	gw(int roleid, java.lang.String templ)
void	gw(int roleid, Templ templ)
Tuple	in(java.lang.String templ)
Tuple	in(Templ templ) Reads and removes a tuple from the scope, blocks and waits if there are no matching tuples
Tuple[]	ina(Templ templ) Reads and removes all the matching tuples from the scope, blocks and waits until there is at least one matching tuple
Tuple	inn(Templ templ) Reads and removes a fresh tuple from the scope, blocks and waits if there are no fresh matching tuples
Tuple	inp(Templ templ) Reads and removes a tuple from the scope, returns an empty tuple if there are no matching tuples available immediately
Tuple[]	inpa(Templ templ) Reads and removes all the matching tuples from the scope, returns an empty tuple list if there are no matching tuples available immediately
Tuple	inpn(Templ templ) Reads and removes a fresh tuple from the scope, returns an empty tuple if there are no fresh matching tuples available immediately
Scope	JoinScope(ScopeName name, int roleid, CamaKey key) Joins a scope with the specified role.
void	LeaveScope() Leaves the current scope
void	out(Tuple tuple) Outputs a single tuple
void	outa(Tuple[] tuple_list) Atomically outputs a list of tuples
void	pd(int roleid, java.lang.String templ)
void	pd(int roleid, Templ templ)
void	pr(int roleid, java.lang.String templ)
void	pr(int roleid, Templ templ)
void	PutScope() Make the curent scope public.
void	pw(int roleid, java.lang.String templ)
void	pw(int roleid, Templ templ)
void	raise(Tuple t, AgentException exc) Exception raising Throws an exception E to the producer of a tuple t.
Tuple	rd(Pred pr)
Tuple	rd(java.lang.String templ)
Tuple	rd(Templ templ) Reads a tuple without removing it from the scope, blocks and waits if there are no matching tuples
Tuple[]	rda(Templ templ) Reads all the matching tuples without removing them from the scope, blocks and waits until there is at least one matching tuple
Tuple	rdn(Templ templ) Reads a fresh tuple (such that is produced at the same time or after the last read tuple) without removing it from the scope, blocks and waits if there are no fresh matching tuples
Tuple	rdp(Templ templ) Reads a tuple without removing it from the scope, returns an empty tuple if there are no matching tuples available immediately
Tuple[]	rdpa(Templ templ) Reads all the matching tuples without removing them from the scope, returns an empty tuple list if there are no matching tuples available immediately
Tuple	rdpn(Templ templ) Reads a fresh tuple without removing it from the scope, returns an empty tuple if there are no fresh matching tuples available immediately
ScopeName	scopeName() Returns literal name of the scope.

Methods inherited from class java.lang.Object

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

Field Detail

BUFFER_SIZE_INIT

public static final int BUFFER_SIZE_INIT

See Also:

Constant Field Values

location

protected Location location

buffer

protected java.io.ByteArrayOutputStream buffer

litName

protected java.lang.String litName

contextNum

protected int contextNum

name

protected ScopeName name

eKey

protected int eKey

Method Detail

scopeName

public ScopeName scopeName()

Returns literal name of the scope. This is an optional attribute and it may be null (empty string)

Disengage

public void Disengage()
               throws CamaException

Disconnect from the location

Throws:

CamaException

CreateScope

public Scope CreateScope(java.lang.String name,
                         ScopeDescr descr)
                  throws CamaException

Creates a new scope with the given scope requirements.

This operation requests CAMA server middleware to create a new sub-scope of the current scope. The creating agent becomes owner of the scope and can later detroy with DeleteScope opeartion. A scope is created in private mode, that is it is not visible by to other agents. Creating agent may make the scope public with PutScope operation.

Sample usage:
// Create scope description with the single role
ScopeDescr sd = new ScopeDescr(2, new CamaKey("Messageboard")).add(new ScopeRoleRest(1, 0, 100), new CamaKey("Client"));
// Create new scope Scope ms = sc.CreateScope("MyBoard", sd);


Parameters:

name - arbitrary string. Literal name of the scope. May be used to distinguish between several scopes of the same type

descr - the scope requirements structure.

Returns:

the context of the newly created scope. This context cannot be used for communication yet. Agent must first join the scope and possible wait for other required participants to join.

Throws:

CamaExceptionNoAccess - this exception is thrown if the agent has no rights to create a sub-scope in a given scope (e.g. it is not a member of that scope)

CamaExceptionInvalidReqs - CAMA server may reject scope create request if it finds that scope requirements are malformed or unconsistent

CamaException

See Also:

ScopeDescr, DeleteScope, PutScope, JoinScope

DeleteScope

public void DeleteScope()
                 throws CamaException

Deletes a scope. The requesting agent must be the owner of the scope. The scope is removed from the location and all the contained tuples are destroyed. If there were any agents connected to the scope they receive CamaExceptionScopeDeleted exception for any operations issued for the scope. Sample usage:
ms.DeleteScope();

Throws:

CamaExceptionNotInScope - if there is no current scope associated with the agent

CamaExceptionBadName - if the name of the scope to delete is invalid (e.g. scope is was already removed)

CamaExceptionNoPriviledges - when the requesting agent is not the owner of the scope

CamaException

JoinScope

public Scope JoinScope(ScopeName name,
                       int roleid,
                       CamaKey key)
                throws CamaException

Joins a scope with the specified role. After an agent joins a scope it can communicate with other agents throw this scope, assuming that all the required roles are present. If some required roles are missing the calling agent is blocked until all the required agents join the scope or the scope is deleted.

Parameters:

name - canonical scope name

roleid - id of role to take in the scope

key - associated with the role

Throws:

CamaExceptionInvalidRole - the supplied role id is invalid for the scope

CamaExceptionInvalidRoleKey - the supplied role is not compatible with the scope (key mismatch)

CamaExceptionNoAccess - if the calling agent is not part of the parent scope of the scope to join.

CamaExceptionBadName - if the supplied scope name is invalid

CamaExceptionClosed - if the scope cannot accept any more agent

CamaExceptionNoRoles - when there no vacant places for the requested role

CamaException

LeaveScope

public void LeaveScope()
                throws CamaException

Leaves the current scope

Throws:

CamaException

GetScopes

public ScopeName GetScopes(CamaKey scopeType)
                    throws CamaException

Returns all the public sub-scopes of the curent scope

Throws:

CamaException

PutScope

public void PutScope()
              throws CamaException

Make the curent scope public. The requesting agents must be the scope owner

Throws:

CamaException

out

public void out(Tuple tuple)
         throws CamaException

Outputs a single tuple

Throws:

CamaException

outa

public void outa(Tuple[] tuple_list)
          throws CamaException

Atomically outputs a list of tuples

Throws:

CamaException

gr

public void gr(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

gw

public void gw(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

gd

public void gd(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

pr

public void pr(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

pw

public void pw(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

pd

public void pd(int roleid,
               Templ templ)
        throws CamaException

Throws:

CamaException

gr

public void gr(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

gw

public void gw(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

gd

public void gd(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

pr

public void pr(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

pw

public void pw(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

pd

public void pd(int roleid,
               java.lang.String templ)
        throws CamaException

Throws:

CamaException

rd

public Tuple rd(Templ templ)
         throws CamaException

Reads a tuple without removing it from the scope, blocks and waits if there are no matching tuples

Throws:

CamaException

rd

public Tuple rd(java.lang.String templ)
         throws CamaException

Throws:

CamaException

rd

public Tuple rd(Pred pr)
         throws CamaException

Throws:

CamaException

rdp

public Tuple rdp(Templ templ)
          throws CamaException

Reads a tuple without removing it from the scope, returns an empty tuple if there are no matching tuples available immediately

Throws:

CamaException

in

public Tuple in(Templ templ)
         throws CamaException

Reads and removes a tuple from the scope, blocks and waits if there are no matching tuples

Throws:

CamaException

in

public Tuple in(java.lang.String templ)
         throws CamaException

Throws:

CamaException

inp

public Tuple inp(Templ templ)
          throws CamaException

Reads and removes a tuple from the scope, returns an empty tuple if there are no matching tuples available immediately

Throws:

CamaException

rdn

public Tuple rdn(Templ templ)
          throws CamaException

Reads a fresh tuple (such that is produced at the same time or after the last read tuple) without removing it from the scope, blocks and waits if there are no fresh matching tuples

Throws:

CamaException

rdpn

public Tuple rdpn(Templ templ)
           throws CamaException

Reads a fresh tuple without removing it from the scope, returns an empty tuple if there are no fresh matching tuples available immediately

Throws:

CamaException

inn

public Tuple inn(Templ templ)
          throws CamaException

Reads and removes a fresh tuple from the scope, blocks and waits if there are no fresh matching tuples

Throws:

CamaException

inpn

public Tuple inpn(Templ templ)
           throws CamaException

Reads and removes a fresh tuple from the scope, returns an empty tuple if there are no fresh matching tuples available immediately

Throws:

CamaException

rda

public Tuple[] rda(Templ templ)
            throws CamaException

Reads all the matching tuples without removing them from the scope, blocks and waits until there is at least one matching tuple

Throws:

CamaException

rdpa

public Tuple[] rdpa(Templ templ)
             throws CamaException

Reads all the matching tuples without removing them from the scope, returns an empty tuple list if there are no matching tuples available immediately

Throws:

CamaException

inpa

public Tuple[] inpa(Templ templ)
             throws CamaException

Reads and removes all the matching tuples from the scope, returns an empty tuple list if there are no matching tuples available immediately

Throws:

CamaException

ina

public Tuple[] ina(Templ templ)
            throws CamaException

Reads and removes all the matching tuples from the scope, blocks and waits until there is at least one matching tuple

Throws:

CamaException

raise

public void raise(Tuple t,
                  AgentException exc)
           throws CamaException,
                  jCamaException

Exception raising Throws an exception E to the producer of a tuple t. The producer will get the exception as soon as it tries to read or write something to the location where t was produced, or it may poll or wait for an exception explicitly.

Throws:

CamaException

jCamaException