org.elkoserver.server.context.caps
Class Cap

java.lang.Object
  org.elkoserver.server.context.Mod
      org.elkoserver.server.context.caps.Cap

All Implemented Interfaces:

Cloneable, DispatchTarget, Encodable, ObjectCompletionWatcher

Direct Known Subclasses:

ContextKeyCap, Definer

public abstract class Cap
extends Mod
implements ObjectCompletionWatcher

Base class for implementing capability mods that grant access to privileged operations.

Constructor Summary

Cap(JSONObject desc)
JSON-driven constructor.

Method Summary

void	delete(User from) Handle a 'delete' message.
protected void	encodeDefaultParameters(JSONLiteral lit) Encode the basic capability parameters as part of encoding this capability mod.
void	ensureValid(User from) Guard function to guarantee that an operation being attempted by a user is being applied to a capability that is actually available to that user.
boolean	isExpired() Test if this capability has expired.
void	objectIsComplete() Mark the item as visible only to its holder.
void	setlabel(User from, String label) Handle a 'setlabel' message.
void	spawn(User from, OptString dest, OptBoolean transferrable, OptBoolean deleteable, OptInteger duration, OptInteger expiration) Handle a 'spawn' message.
void	transfer(User from, String destRef) Handle a 'transfer' message.

Methods inherited from class org.elkoserver.server.context.Mod

attachTo, clone, context, ensureHolding, ensureInContext, ensureReachable, ensureSameContext, ensureSameUser, holder, isEphemeral, markAsChanged, markAsEphemeral, object

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.elkoserver.json.Encodable

encode

Constructor Detail

Cap

public Cap(JSONObject desc)
    throws JSONDecodingException

JSON-driven constructor. Note that there are no JSON parameters declared. This constructor must be called from the subclass and will extract its own parameters from the JSON object directly. It looks for three parameters, two booleans and a timestamp: transferrable true (default) if cap is transferrable deletable true (default) if cap is deletable expiration time after which cap no longer operates (default value is 0, i.e., cap is permanent), expressed as milliseconds past the epoch, exactly as returned by System.currentTimeMillis().

Parameters:

desc - The parsed JSON object describing this capability mod.

Throws:

JSONDecodingException

Method Detail

objectIsComplete

public final void objectIsComplete()

Mark the item as visible only to its holder.

Application code should not call this method.

Specified by:

objectIsComplete in interface ObjectCompletionWatcher

encodeDefaultParameters

protected final void encodeDefaultParameters(JSONLiteral lit)

Encode the basic capability parameters as part of encoding this capability mod. This method must be called by the encode() method of each subclass.

Parameters:

lit - The JSONLiteral into which this capability mod is being encoded.

ensureValid

public final void ensureValid(User from)
                       throws MessageHandlerException

Guard function to guarantee that an operation being attempted by a user is being applied to a capability that is actually available to that user. To be available, the capability must be attached to an object that is reachable by the user and it must not be expired. If this capability is not available, this method with throw a MessageHandlerException.

Throws:

MessageHandlerException - if the test fails.

isExpired

public final boolean isExpired()

Test if this capability has expired.

Returns:

true if this capability has expired, false if it is still OK to use.

delete

@JSONMethod
public final void delete(User from)
                  throws MessageHandlerException

Handle a 'delete' message. This is a request from a client to delete the capability object.

This request will be rejected if the capability is marked as undeletable and is not expired.

recv: { to:REF, op:"delete" }
send: { to:REF, op:"delete" }

Parameters:

from - The user who sent the message.

Throws:

MessageHandlerException

setlabel

@JSONMethod(value="label")
public void setlabel(User from,
                                     String label)
              throws MessageHandlerException

Handle a 'setlabel' message. This is a request from a client to change the label of the capability object.

recv: { to:REF, op:"setlabel", label:STR }
send: no reply is sent.

Parameters:

from - The user who sent the message.

label - The new label string.

Throws:

MessageHandlerException

transfer

@JSONMethod(value="dest")
public final void transfer(User from,
                                           String destRef)
                    throws MessageHandlerException

Handle a 'transfer' message. This is a request from a client to pass possession of the capability object to somebody else.

This request will be rejected if the capability is marked as untransferrable. Yes, this is unenforceable due to the possibility of proxying, but marketing solipsism must be served.

recv: { to:REF, op:"transfer", dest:DESTREF }
send: { to:REF, op:"delete" }
send: { to:DESTREF, op:"make", ... }

Parameters:

from - The user who sent the message.

destRef - Reference to user or context that is to receive the capability.

Throws:

MessageHandlerException

spawn

@JSONMethod(value={"dest","transferrable","deletable","duration","expiration"})
public void spawn(User from,
                                  OptString dest,
                                  OptBoolean transferrable,
                                  OptBoolean deleteable,
                                  OptInteger duration,
                                  OptInteger expiration)
           throws MessageHandlerException

Handle a 'spawn' message. This is a request from a client to create a copy of the capability object, with possibly reduced scope of powers.

This method will reject, as an illegal rights amplification, any attempt to spawn a capability that is undeletable when the base capability is deletable, transferrable when the base capability is untransferrable, or which has a later expiration time than the base capability.

If 'dest' designates a different holder, the operation will also be regarded as a transfer and subjected to all the same checks as a call to transfer().

recv: { to:REF, op:"spawn", dest:optDESTREF, transferrable:optBOOL, duration:optLONG, expiration:optLONG }
send: { to:DESTREF, op:"make", ... }

Parameters:

from - The user who sent the message.

dest - Reference to container into which the new capability is to be placed. If omitted, defaults to the sending user. If this capability is non-transferrable, must refer to the sending user or a container contained by the sending user.

transferrable - Flag indicating whether the new capability is to be transferrable. If omitted, defaults to the same value as this capability. It is not permitted to set this parameter to true if this capability is not itself transferrable.

deleteable - Flag indicating whether the new capability is to be deleteable. If omitted, defaults to true. It is not permitted to set this parameter to false if this capability is itself deletable.

duration - Expiration time of the new capability, expressed as an offset (in milliseconds) from the present. A value of 0 (the default) indicates that the capability is permanent.

expiration - Expiration time of the new capability, expressed as an absolute system time (in milliseconds).

Throws:

MessageHandlerException