spki
Class Subject

java.lang.Object
  |
  +--spki.BaseObj
        |
        +--spki.Subject

Direct Known Subclasses:

SubjectAttribute, SubjectCapability, SubjectName, SubjectRole, SubjectTransfer

public abstract class Subject

extends BaseObj

SPKI Subject abstract class.

Formal definitions:

 <integer>:: {<byte-string> representing an integer value in network byte-order} ;
 <k-val>:: {<integer> that's always > 1} ;
 <scheme-id>:: <byte-string> ;
 <threshold>:: "(" "thresh" <k-val> <scheme-id> ")" ;
 <subject>:: <subject-rule> | <subject-role> |
 <subject-name> | <subject-transfer> | <subject-attr> ;
 

Version:

$Id: Subject.java,v 1.24 2002/07/16 18:29:46 tep Exp $

Author:

Tep Narula <tep@win.trlabs.ca>

See Also:

SubjObj

Field Summary

private static String	__ME This class's full name.
(package private) boolean	dirty Do we need to re-build the SExpression?
static int	MIN_THRESHOLD The minimum meaningful threshold value (2).
private boolean	reduceonly Is this object created for threshold reduction only? Used by the Subject.toSExpression() method.
static String	SEXP_NAME This class S-Expression type name, used by toSExpression() and other methods.
private SubjObj	subj_obj The <subj-obj>.
(package private) SList	subj_obj_sexp The <subj-obj>'s S-Expression, set by the Subject(SExpression) constructor to be parsed by the implementing subclass.
private Object[]	subj_objs The list of subj-objs.
private int	thresh The subject's threshold value (<k-val>), default to MIN_THRESHOLD-1.
private Sexp	thresh_scheme The threshold scheme-id.
static String	THRESHOLD_SEXP_NAME The threshold field S-Expression type name, used by toSExpression() and other methods.

Fields inherited from class spki.BaseObj

__ME, cache_sexp, cached_sexp, DEFAULT_HASH_ALG, locked, SEXP_NAME

Constructor Summary

protected	Subject() Don't use me.
(package private)	Subject(int threshold, Sexp thresh_scheme, Object[] subjects) Create and immutalbe Subject object from the given threshold and list of subj-objs.
protected	Subject(int threshold, Sexp thresh_scheme, SubjObj subject) Create an immutable Subject object from the given threshold and subj-obj.
protected	Subject(SExpression sexp) Create an immutable Subject object from an S-Expression.

Method Summary

static SubjACL	getSubjACL(SExpression sexp) Get an instance of a SubjACL from given S-Expression.
SubjObj	getSubjObj() Get this subject's subj-obj.
(package private) Object[]	getSubjObjs() Get an array of this subject's subj-objs.
(package private) int	getSubjObjsLength() Get the number of this subject's subj-objs.
int	getThreshold() Get this subject's threshold value.
Sexp	getThresholdSchemeId() Get this subject's threshold scheme-id, if available.
private static void	rSubjObjs2SExpression(SList list, Object[] objs) Recursively walk through the given array of subj-objs, which may contain n-level of sub-arrays, and construct the SExpression representation of them into the given SList.
protected void	setSubjObj(SubjObj subj_obj) Set this subject's subj-obj.
private void	setThreshold(int thresh, Sexp thresh_scheme) Set this subject's threshold value.
SExpression	toSExpression() Build an SExpression representing this object.

Methods inherited from class spki.BaseObj

disableSExpressionCaching, enableSExpressionCaching, extractHashAlgId, getCachedSExpression, isLocked, isSListOfType, lock, providerToSPKI, setCachedSExpression, spkiToProvider, toString

Methods inherited from class java.lang.Object

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

Field Detail

__ME

private static final String __ME

This class's full name.

SEXP_NAME

public static final String SEXP_NAME

This class S-Expression type name, used by toSExpression() and other methods.

See Also:

toSExpression()

THRESHOLD_SEXP_NAME

public static final String THRESHOLD_SEXP_NAME

The threshold field S-Expression type name, used by toSExpression() and other methods.

See Also:

toSExpression()

MIN_THRESHOLD

public static final int MIN_THRESHOLD

The minimum meaningful threshold value (2).

thresh

private int thresh

The subject's threshold value (<k-val>), default to MIN_THRESHOLD-1.

See Also:

MIN_THRESHOLD

thresh_scheme

private Sexp thresh_scheme

The threshold scheme-id.

subj_obj

private SubjObj subj_obj

The <subj-obj>.

See Also:

SubjObj

subj_obj_sexp

SList subj_obj_sexp

The <subj-obj>'s S-Expression, set by the Subject(SExpression) constructor to be parsed by the implementing subclass.

See Also:

Subject(SExpression)

dirty

boolean dirty

Do we need to re-build the SExpression?

See Also:

toSExpression(), setThreshold(int,Sexp), setSubjObj(SubjObj)

subj_objs

private Object[] subj_objs

The list of subj-objs. For use in threshold reduction only.

See Also:

Subject(int,Sexp,Object[])

reduceonly

private boolean reduceonly

Is this object created for threshold reduction only? Used by the Subject.toSExpression() method.

See Also:

Subject(int,Sexp,Object[]), toSExpression()

Constructor Detail

Subject

protected Subject()

Don't use me. To be called by each subclass' equivalent constructor.

See Also:

Subject(SExpression), Subject(int,Sexp,SubjObj)

Subject

protected Subject(SExpression sexp)
           throws SPKIException,
                  ParseException

Create an immutable Subject object from an S-Expression. To be called by each subclass' equivalent constructor. This constructor implements general sanity checks on the arguments, stores the threshold value if available, then caches a copy of the S-Expression of the subj-obj in the subj_obj_sexp field.

The overriding constructor should first call this constructor, then verify the threshold value with the getThreshold() method, parse the subj_obj_sexp field and store the result using the setSubjObj() method, cache the S-Expression with the setCachedSExpression() method, set the dirty field to false, and finish by making the object immutable with the lock() method.

See Also:

BaseObj.BaseObj(SExpression), subj_obj_sexp, getThreshold(), setSubjObj(SubjObj), BaseObj.setCachedSExpression(SExpression), BaseObj.lock()

Subject

protected Subject(int threshold,
                  Sexp thresh_scheme,
                  SubjObj subject)
           throws SPKIException

Create an immutable Subject object from the given threshold and subj-obj. The subclass' equivalent constructor is supposed to pass up the instance of one of SubjObj's child interfaces and, optionally, the threshold value.

Parameters:

threshold - the optional threshold value, ignored if < MIN_THRESHOLD.

thresh_scheme - the threshold scheme-id, ignored if the threshold argument is ignored.

subject - the subj-obj.

See Also:

MIN_THRESHOLD, SubjObj

Subject

Subject(int threshold,
        Sexp thresh_scheme,
        Object[] subjects)
  throws SPKIException

Create and immutalbe Subject object from the given threshold and list of subj-objs. For use in threshold reduction only.

Parameters:

threshold - the optional threshold value, ignored if < MIN_THRESHOLD.

thresh_scheme - the threshold scheme-id, ignored if the threshold argument is ignored.

subjects - the list of subj-objs.

Throws:

SPKIException - if something went wrong.

See Also:

Tuple.SUnion(Subject,Subject), Tuple.tEliminate(Subject)

Method Detail

toSExpression

public SExpression toSExpression()
                          throws SPKIException

Description copied from interface: SPKIObject

Build an SExpression representing this object.

Overrides:

toSExpression in class BaseObj

Tags copied from interface: SPKIObject

Returns:

SExpression object representing this object, or null.

Throws:

SPKIException - if something went wrong during conversion.

getThreshold

public int getThreshold()

Get this subject's threshold value.

Returns:

the threshold value.

getThresholdSchemeId

public Sexp getThresholdSchemeId()
                          throws SPKIException

Get this subject's threshold scheme-id, if available.

Returns:

the threshold scheme-id, or null.

Throws:

SPKIException - if something went wrong.

getSubjObj

public SubjObj getSubjObj()

Get this subject's subj-obj.

Returns:

a SubjObj object, or null if this subject contains more than one subj-objs.

See Also:

SubjObj, Subject(int,Sexp,Object[])

getSubjACL

public static final SubjACL getSubjACL(SExpression sexp)
                                throws ParseException,
                                       SPKIException

Get an instance of a SubjACL from given S-Expression.

Parameters:

sexp - the SExpression containing a SubjACL.

Returns:

An object instance implementing SubjACL.

Throws:

ParseException - if the argument doesn't contain a SubjACL.

SPKIException - if something went wrong.

setSubjObj

protected void setSubjObj(SubjObj subj_obj)
                   throws IllegalStateException,
                          SPKIException

Set this subject's subj-obj. Used by subclass' constructor(s).

Parameters:

subj_obj - the subj-obj.

Throws:

IllegalStateException - if the object is immutable.

SPKIException - if something went wrong.

See Also:

Subject(SExpression), SubjObj

getSubjObjsLength

final int getSubjObjsLength()

Get the number of this subject's subj-objs. For use in threshold reduction only.

See Also:

Subject(int,Sexp,Object[]), Tuple.SUnion(Subject,Subject), Tuple.tEliminate(Subject)

getSubjObjs

final Object[] getSubjObjs()

Get an array of this subject's subj-objs. For use in threshold reduction only. TODO: implement recursive walk-through to build and return a fresh copy of the sub-objs.

See Also:

Subject(int,Sexp,Object[]), Tuple.SUnion(Subject,Subject), Tuple.tEliminate(Subject)

setThreshold

private void setThreshold(int thresh,
                          Sexp thresh_scheme)
                   throws IllegalStateException,
                          SPKIException

Set this subject's threshold value. Used by the constructors.

Parameters:

thresh - the threshold value, ignored if < MIN_THRESHOLD.

thresh_scheme - the threshold scheme-id, ignored of threshold value is ignored.

Throws:

IllegalStateException - if the object is immutable.

SPKIException - something went wrong.

See Also:

Subject(SExpression), Subject(int,Sexp,SubjObj), Subject(int,Sexp,Object[]), MIN_THRESHOLD

rSubjObjs2SExpression

private static void rSubjObjs2SExpression(SList list,
                                          Object[] objs)
                                   throws SPKIException

Recursively walk through the given array of subj-objs, which may contain n-level of sub-arrays, and construct the SExpression representation of them into the given SList. Used by the Subject.toSExpression() method for debugging purpose only.

See Also:

Subject(int,Sexp,Object[]), toSExpression()