com.waveset.object
Class PersistentObject

java.lang.Object
  extended bycom.waveset.object.PersistentObject
All Implemented Interfaces:
java.lang.Comparable, javax.naming.Referenceable, XmlObject
Direct Known Subclasses:
AbstractXmlData, AccessScan, Account, AttributeDefinition, AttrParse, AuditConfig, AuditPolicy, AuditQuery, ComplianceViolation, CompositeObject, Configuration, Discovery, EmailTemplate, EncryptionKey, Event, Extract, Fake, LoadConfig, LoginApp, LoginConfig, LoginModGroup, LogRecord, MetaView, Miscellaneous, ObjectGroup, Policy, Principal, RemedyConfig, ReportCounter, ResourceAccount, ResourceAction, Rule, SecureCounter, Server, Service, SyslogRecord, TaskDefinition, TaskInstance, TaskResult, TaskResultPage, TaskSchedule, TaskTemplate, TestItem, UsageReport, UserEntitlement, WorkItem

public abstract class PersistentObject
extends java.lang.Object
implements XmlObject, java.lang.Comparable, javax.naming.Referenceable

The base class of all objects that can be stored in the repository.

We define a number of common fields such as type, id and name. We also define behavior that all persistent objects share. Once such behavior is the interaction with an ObjectCache that provides automated resolution of references between objects.

Implements JNDI's Referenceable interface. This allows us to store a PersistentObject in any JNDI service provider.


Nested Class Summary
static class PersistentObject.Comparator
          Implement the Comparator interface to sort PersistentObject instances by type and name.
static class PersistentObject.InitialInstance
          An inner class describing an "initial instance" of a persistent object that is to be automatically added to a repository when it is created.
 
Field Summary
protected  boolean _trace
          Debug flag
static java.lang.String code_id
           
protected static Trace trace
           
 
Constructor Summary
  PersistentObject()
          Base constructor for persistent objects.
protected PersistentObject(PersistentObject src)
          A subclass constructor that does a simple clone.
protected PersistentObject(java.lang.String name)
          A subclass constructor that assigns the name.
 
Method Summary
protected  void addCommonElements(java.lang.StringBuffer b)
          Add elements common to all persistent objects.
protected  void addEndTag(java.lang.StringBuffer b)
          Add the end tag for this object.
 void addMemberObjectGroup(ObjectGroup og)
          Add a new object group, declaring this object as a member of that group.
 void addMemberObjectGroup(ObjectRef og)
          Add a new object group, declaring this object as a member of that group.
protected  void addPersistentAttributes(java.lang.StringBuffer b)
          Emit the persistent attributes assuming an open start tag.
protected  void addStartTag(java.lang.StringBuffer b, boolean close)
          Emit a start tag and persistent attributes.
protected  void addSubclassAttributes(java.lang.StringBuffer b)
          Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist).
protected  void addSubclassElements(java.lang.StringBuffer b)
          Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist).
protected  void addSummaryAttributes(java.lang.StringBuffer b)
           
static void addXmlHeader(java.lang.StringBuffer b, java.lang.String element)
          Adds a standard XML header, DOCTYPE statement and element start tag.
 boolean attributesMatch(AttributeCondition[] attrConds)
          Return true if the attributes exposed by this object meet the supplied list of attribute conditions.
 boolean attributesMatch(LogicalExpression filter)
          Return true if the attributes exposed by this object satisfy the specified logical expression.
 boolean attributesMatch(WSAttributes extatts)
          Return true if the supplied list of attributes match attributes exposed by this object.
 void checkReference(ObjectRef ref)
          Checks a reference owned by an object to make sure that the referenced object is in the same cache as the referencing object.
 void checkReferences(java.util.List refs)
          Check a list of references.
 void clearId()
          Removes the ID from an object.
 PersistentObject cloneAs(java.lang.String newName)
          Clones an object, changing the name in the process.
 PersistentObject cloneObject()
          Clones an object.
 int compareTo(java.lang.Object o)
          Implement the Comparable interface so that lists of these will have a reasonable contains() implementation
static PersistentObject create(org.w3c.dom.Element element)
           
static PersistentObject create(java.lang.String xml)
          Build a persistent object from an XML string.
static PersistentObject create(java.lang.String xml, boolean validate)
          Build a persistent object from an XML string.
static PersistentObject create(Type type)
          Creates an empty object of the given type.
static PersistentObject.InitialInstance createLastModItem(PersistentObject obj)
          Build an InitialInstance for a special object used to hold the last modification time of all objects of a particular type.
static PersistentObject.InitialInstance createLastModItem(Type type)
           
static PersistentObject.InitialInstance[] createLastModItemList(PersistentObject obj)
          Build an InitialInstance array containing a single instance for the special "last mode time" marker.
 boolean directObjectGroupMember(ObjectGroup og)
          Test to see if this object is a direct member of the given object group.
 void dump()
          for consistency with XmlObjectFactory & AbstractXmlObject
 void dumpFile(java.lang.String file)
           
 boolean equals(java.lang.Object obj)
          Compares two objects for equality of identity.
static java.lang.String fakeId(Type type, java.lang.String name)
          Generate a "fake" ID (e.g., for an initial instance).
 java.lang.String getAttribute(java.lang.String name)
          Return the value of an abstract attribute if the class supports it.
protected  WSAttributes getAttributeValues(java.util.List requestedAttributes)
           
protected  WSAttribute getAttributeValues(java.lang.String attrName)
           
 java.util.ArrayList getAuthReferences()
          Returns the list of all references in this object that are subject to CONNECT/DISCONNECT Right authorization checks.
 java.lang.String getAuthType()
          Return the authorization type of this object.
 javax.naming.directory.BasicAttributes getBasicAttributes()
           
static javax.naming.directory.BasicAttributes getBasicAttributes(PersistentObject po, java.lang.String[] attrIds)
           
 javax.naming.directory.BasicAttributes getBasicAttributes(java.lang.String[] attrIds)
           
 ObjectCache getCache()
          Gets the cache this object is referencing.
 long getCounterValue()
           
 java.util.Date getCreateDate()
           
 java.lang.String getCreator()
           
 java.lang.String getDisplayableName()
          Return the displayable name of this object.
 java.lang.String getDisplayName()
          Return the display name of this object.
 java.lang.String getElementName()
          Return the XML element name of this object.
 java.util.List getEncryptedValues()
           
 java.lang.String getId()
          Get the internally generated unique id for this object.
 java.lang.String getIdOrName()
          Get the id if one has been assigned, otherwise the name.
static PersistentObject.InitialInstance[] getInitialInstances()
          Returns the set of initial instances that should be created for this object type when a repository is created.
 long getLastMod()
          Return the modification count for this object at the time this object was last modified.
 java.util.Date getLastModDate()
          Return the date/time this object was created
 java.lang.String getLastModifier()
           
static java.lang.String getLastModItemId(Type type)
           
 LockInfo getLockInfo()
          Return information about any lock held on this object.
 java.util.List getMemberObjectGroupRefs()
          Return the list of references to object groups this object is a member of.
 java.util.List getMemberObjectGroupRefsUpTo(ObjectGroup og)
          Returns the list of references to object groups this object is a member of up the hierarchy to the specified object group (e.g.
 ObjectGroup[] getMemberObjectGroups()
          Get an array of resolved object groups to which this object is a member.
 java.lang.String getName()
          Return the name of this object.
 java.lang.String getNameOrId()
          Get the name if it has been assigned, otherwise the id.
 java.util.Properties getProperties()
           
 java.lang.Object getProperty(java.lang.String name)
           
 java.lang.String getPropertyAsString(java.lang.String name)
           
 PropertyList getPropertyList()
           
 WSAttributes getQueryableAttributes()
           
 javax.naming.Reference getReference()
           
 java.util.ArrayList getReferences()
          Returns the list of all references in this object.
 java.util.List getRuleDrivenMemberObjectGroupRefs()
          Return the list of references to object groups this object is a member of based on the evaluation of user members rules associated with the object groups controlled by the current subject.
 java.util.List getRuleDrivenMemberObjectGroupRefsUpTo(ObjectGroup og, ObjectGroup[] mogs)
          Returns the list of references to object groups this object is a member of up the hierarchy to the specified object group (e.g.
 ObjectGroup[] getRuleDrivenMemberObjectGroups()
          Get an array of resolved object groups to which this object is a member.
 java.lang.String getSubtype()
          Return the subtype of this object.
 WSAttributes getSummaryAttributes()
           
 java.lang.String getSummaryString()
          Get the summary string for this object.
abstract  Type getType()
          Return the type of this object.
static boolean hasEncryptedData()
           
 int hashCode()
          Implement the hashCode for efficient map insertion
 boolean identityEquals(PersistentObject pobj)
          Helper for the equals method, compares the identity of this object with another persistent object.
 boolean isAlias()
           
 boolean isHidden()
           
static boolean isId(java.lang.String id)
          Determine whether a string smells like an id.
 boolean isProtected()
           
 boolean isProtectedFromDelete()
           
 boolean isReferencedIn(java.util.Collection coll)
          Returns true if an ObjectRef reference to this object is contained within the collection.
 void listOperationalAttributes(java.util.List attrs)
          Add to the specified list the "built-in" attributes that are queryable just because the IDM Repository needs them in order to operate.
 java.util.List listQueryableAttributes()
           
 java.util.List listQueryableReferenceAttributes()
           
 java.util.List listSummaryAttributes()
          Returns the complete list of defined attributes that this type of persistent object exposes as summary attributes (regardless of whether this particular object has a value for each).
 boolean objectGroupMember(ObjectGroup og)
          Test to see if this object is a member of the given object group.
 ObjectRef objectGroupMemberRef(ObjectGroup og)
          Test to see if this object is a member of the given object group.
protected  void parseCommonElement(org.w3c.dom.Element e)
          Handle a body element that the subclass didn't want.
protected  void parseCommonElements(org.w3c.dom.Element wrapper)
          Examine all body elements and treat them as common elements.
protected  void parsePersistentAttributes(org.w3c.dom.Element e)
          Parse the common set of XML attributes that all persistent object serializations should have.
protected  void parseSubclassAttributes(org.w3c.dom.Element e)
          Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer).
protected  void parseSubclassElements(org.w3c.dom.Element e)
          Each concrete subclass should parse from the XML buffer any persisted subclass-specific elements (generally, the same ones that it writes into the buffer).
protected  void parseXml(org.w3c.dom.Element e)
          A concrete subclass can implement the required constructor that takes a single XML Element (fully qualified class name here) by invoking this method and implementing the abstract method to parse any subclass-specific fields.
protected  void parseXml(java.lang.String xml)
          A concrete subclass can implement the required constructor that takes a single String (containing XML) simply by invoking this method.
 void prepareForSerialization()
          Prepare for serialization by doing anything that involves resolving references, leaving behind in the object anything that will be needed for toXml, getSummaryAttributes, getQueryableAttributes.
 void prepareToSerialize()
          Update the structure of the object prior to serialization.
protected static void println(java.lang.Object o)
          Ubiquitous macro.
 void reEncrypt()
           
protected  void reEncryptSubclassAttributes()
          Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer).
 void removeMemberObjectGroup(ObjectGroup og)
          Remove an object group from this object.
 void removeProperty(java.lang.String name)
           
 int resolve(java.util.List refs)
          Resolve a list of references, filtering out elements that no longer resolve.
 boolean resolve(java.util.List refs, java.lang.Object[] array)
          Resolve a list of references, storing pointers to the resolved objects in an array as a side effect.
 PersistentObject resolve(ObjectRef ref)
          Resolve a single reference.
 java.lang.Object resolveArray(java.util.List refs, java.lang.Object[] array, java.lang.Class elClass)
          Resolve a list of references, creating a typed array of PersistentObject pointers.
 java.lang.Object resolveArrayByFetching(java.util.List refs, java.lang.Object[] array, java.lang.Class elClass)
          Now that users can also be administrators that can be approvers or be notified, together with the fact that users are a supressed type meaning they never get cached, we need a way to ensure that we alway resolve these list of refs by hitting the repo.
protected  void resolveObjectReference(ObjectRef ref, PersistentObject owner, ObjectCache cache)
           
 void resolveObjectReferences(ObjectCache cache)
          Walk over an object looking for ObjectRefs without ids and resolve them.
 PersistentObject resolveReference(ObjectRef ref)
          DEPRECATED: like resolve above but throws an exception if it can't find it, try to weed these out.
static void resolveSummaryAttributes(ObjectCache cache, WSAttributes attrs)
          Walk the summary attributes, translating the embedded IDs to names.
static void resolveSummaryAttributes(Type type, ObjectCache cache, WSAttributes attrs)
          Map the type to an implementation class, then call its resolveSummaryAttributes method.
 ObjectRef ruleDrivenObjectGroupMemberRef(ObjectGroup og, java.util.List memberObjectGroupRefs)
          Test to see if this object is a member of the given object group.
 void setAuthType(AuthType t)
          Set the authorization type of this object.
 void setAuthType(java.lang.String s)
          Set the authorization type of this object.
 void setCache(ObjectCache c)
          Sets the object cache.
protected  void setCreateDate(java.util.Date createDate)
          Set the value of Attribute.CREATE_DATE.
protected  void setCreator(java.lang.String creator)
          Replace the value of Attribute.CREATOR.
 void setDisplayName(Message m)
          Set the display name to an unresolved message.
 void setDisplayName(java.lang.String s)
          Replaces the value of the displayName attribute.
 void setHidden(boolean b)
           
 void setIsAlias(boolean isAlias)
           
protected  void setLastMod(long lastMod)
          Replaces the value of the "modified" attribute.
protected  void setLastMod(java.lang.String lmtString)
          Replaces the value of the "modified" attribute.
protected  void setLastModDate(java.util.Date lastModDate)
          Set the date/time this object was last modified.
protected  void setLastModifier(java.lang.String lastModifier)
          Replaces the value of the "lastModifier" attribute.
 void setMemberObjectGroupRef(ObjectRef og)
          Set a single member object group ref
 void setMemberObjectGroupRefs(java.util.List refs)
          Set the list of references to object groups to which this object is a member (say that 10 times fast).
 void setMemberObjectGroups(ObjectGroup[] ogarray)
          Set the object groups to which this object is a member.
 void setName(java.lang.String s)
          Replaces the value of the name attribute.
 void setProperties(java.util.Properties p)
           
 void setProperty(java.lang.String name, java.lang.Object value)
           
 void setPropertyList(PropertyList p)
           
protected  void setProtected(boolean b)
           
protected  void setProtectedFromDelete(boolean b)
           
 void setRuleDrivenMembersCache(RuleDrivenMembersCache cache)
           
 void setSubtype(java.lang.String subtype)
          Set the subtype of this object (e.g., Messages.ACCOUNT_CORRELATION_RULE within Type.RULE).
 void setTrace(boolean b)
           
 java.lang.String toString()
           
 java.lang.String toXml()
          Serialize the object to an XML string.
 void toXml(java.lang.StringBuffer b)
          Serialize the object as XML into a string buffer.
 void toXml(java.lang.StringBuffer b, int indent)
          Serialize the object as XML with an optional indentation.
 void toXmlFile(java.lang.String file)
          Serialize the object to a file.
 void visit(Visitor v)
          All persistent objects support a visitor interface.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

code_id

public static final java.lang.String code_id
See Also:
Constant Field Values

trace

protected static Trace trace

_trace

protected boolean _trace
Debug flag

Constructor Detail

PersistentObject

public PersistentObject()
Base constructor for persistent objects.

Set default ObjectGroup to "Top" for all Persistent Objects the one exception is for the ObjectGroup "Top" whose member object group will be set to null (see ObjectGroup constructor).


PersistentObject

protected PersistentObject(java.lang.String name)
A subclass constructor that assigns the name.


PersistentObject

protected PersistentObject(PersistentObject src)
                    throws WavesetException
A subclass constructor that does a simple clone. BE VERY CAREFUL to not let resolved references survive a clone.

Method Detail

getCreator

public java.lang.String getCreator()
Returns:
the value of Attribute.CREATOR.

setCreator

protected void setCreator(java.lang.String creator)
Replace the value of Attribute.CREATOR.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.


getCreateDate

public java.util.Date getCreateDate()
Returns:
the value of Attribute.CREATE_DATE.

setCreateDate

protected void setCreateDate(java.util.Date createDate)
Set the value of Attribute.CREATE_DATE.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.


getLastModDate

public java.util.Date getLastModDate()
Return the date/time this object was created


setLastModDate

protected void setLastModDate(java.util.Date lastModDate)
Set the date/time this object was last modified.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.


getLastModifier

public java.lang.String getLastModifier()
Returns:
the value of the "lastModifier" attribute.

setLastModifier

protected void setLastModifier(java.lang.String lastModifier)
Replaces the value of the "lastModifier" attribute.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.


getProperties

public java.util.Properties getProperties()

setProperties

public void setProperties(java.util.Properties p)

getPropertyList

public PropertyList getPropertyList()

setPropertyList

public void setPropertyList(PropertyList p)

setTrace

public void setTrace(boolean b)

println

protected static void println(java.lang.Object o)
Ubiquitous macro.


isId

public static boolean isId(java.lang.String id)
Determine whether a string smells like an id. We need this in a few places where either an id or a name could be passed in.


fakeId

public static java.lang.String fakeId(Type type,
                                      java.lang.String name)
Generate a "fake" ID (e.g., for an initial instance).


hasEncryptedData

public static boolean hasEncryptedData()

create

public static PersistentObject create(java.lang.String xml)
                               throws WavesetException
Build a persistent object from an XML string.

DTD Validation is not performed.

Throws:
WavesetException

create

public static PersistentObject create(java.lang.String xml,
                                      boolean validate)
                               throws WavesetException
Build a persistent object from an XML string.

Validation against the DTD can be controlled with the validate argument. Normally this is off for performance, but in some contexts you may want it on.

Throws:
WavesetException

create

public static PersistentObject create(org.w3c.dom.Element element)
                               throws WavesetException
Returns:
a persistent object constructed from a DOM Element.
Throws:
WavesetException

create

public static PersistentObject create(Type type)
                               throws WavesetException
Creates an empty object of the given type.

This was added for the generic object editor GUI, which needs to create a default object for a type. The only types that can be instantiated here are the ones which have no-argument constructors and for which the class is known from the Type object.

Throws:
WavesetException

reEncrypt

public void reEncrypt()
               throws WavesetException
Throws:
WavesetException

reEncryptSubclassAttributes

protected void reEncryptSubclassAttributes()
                                    throws WavesetException
Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer). // * @see #addSubclassAttributes(StringBuffer)

PersistentObject's default implementation is a no-op.

// * @see #parseXml(Element)

Throws:
WavesetException

resolveSummaryAttributes

public static void resolveSummaryAttributes(Type type,
                                            ObjectCache cache,
                                            WSAttributes attrs)
                                     throws WavesetException
Map the type to an implementation class, then call its resolveSummaryAttributes method.

Throws:
WavesetException

visit

public void visit(Visitor v)
           throws WavesetException
All persistent objects support a visitor interface. This is expected to be overridden in the subclasses if you want to support visiting. See the Visitor class for more information.

Throws:
WavesetException

getType

public abstract Type getType()
Return the type of this object. This must be implemented by each subclass.


setSubtype

public void setSubtype(java.lang.String subtype)
Set the subtype of this object (e.g., Messages.ACCOUNT_CORRELATION_RULE within Type.RULE). This may be called by any subclass.

NOTE: By convention, the subtype value is a message key.


getSubtype

public final java.lang.String getSubtype()
Return the subtype of this object.

NOTE: By convention, the subtype value is a message key. This allows persistent objects to be filtered or queried by subtype within type using well-defined constants (i.e., message keys), but allows each subtype to be localized for display.


getAuthType

public java.lang.String getAuthType()
Return the authorization type of this object. An authorization type may be used to further control access to the object beyond that defined for the base repository type.


setAuthType

public void setAuthType(java.lang.String s)
Set the authorization type of this object. An authorization type may be used to further control access to the object beyond that defined for the base repository type.


setAuthType

public void setAuthType(AuthType t)
Set the authorization type of this object. An authorization type may be used to further control access to the object beyond that defined for the base repository type.


getElementName

public java.lang.String getElementName()
Return the XML element name of this object. This is normally the same as the type name, but may be different for classes that support subtyping.

Specified by:
getElementName in interface XmlObject
Returns:
the element name

getId

public java.lang.String getId()
Get the internally generated unique id for this object.


clearId

public void clearId()
Removes the ID from an object.

Useful when creating an object that is derived from another, clone the object, then clear the ID.


getName

public java.lang.String getName()
Return the name of this object.


setName

public void setName(java.lang.String s)
Replaces the value of the name attribute.

Note that if you change the name of an object, and check the object into the repository using the Session.checkinObject method, this will have the effect of renaming the object in the repository.


getDisplayName

public java.lang.String getDisplayName()
Return the display name of this object.


getDisplayableName

public java.lang.String getDisplayableName()
Return the displayable name of this object.


setDisplayName

public void setDisplayName(java.lang.String s)
Replaces the value of the displayName attribute.


setDisplayName

public void setDisplayName(Message m)
Set the display name to an unresolved message. This will convert it to a series of attributes encoded in a string.


getIdOrName

public java.lang.String getIdOrName()
Get the id if one has been assigned, otherwise the name. A convenience method for code that needs some way to identity the object, but doesn't care if it is an id or name. Objects with names but without ids can appear when building new objects.


getNameOrId

public java.lang.String getNameOrId()
Get the name if it has been assigned, otherwise the id. This is typically used for visible messages where we want to prefer the name over the id.


toString

public java.lang.String toString()

getLockInfo

public LockInfo getLockInfo()
Return information about any lock held on this object.

NOTE: To obtain up-to-date lock information, use the Session.getLockInfo method.

See Also:
Session.getLockInfo(com.waveset.object.Type, java.lang.String)

getCounterValue

public long getCounterValue()
Returns:
the current value of this object's counter.

getLastMod

public long getLastMod()
Return the modification count for this object at the time this object was last modified.


setLastMod

protected void setLastMod(java.lang.String lmtString)
Replaces the value of the "modified" attribute.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.

Parameters:
lmtString - - the string representation of the modification time.

setLastMod

protected void setLastMod(long lastMod)
Replaces the value of the "modified" attribute.

NOTE: This method should be called only by RepositoryProxy, and then only on behalf of the Repository.


setCache

public void setCache(ObjectCache c)
Sets the object cache.

There are two situations where this may be used. First, an ObjectCache may set this when an object is added to the cache. Second, an application may wish to assign a cache to this object for automatic reference resolution, without having the object actually be "in" the cache.

For example Type.USER objects will never be in a cache, but they need to point to a cache in order to automatically resolve roles and other things.

Parameters:
c - - an object cache

getCache

public ObjectCache getCache()
Gets the cache this object is referencing.


isAlias

public boolean isAlias()

isProtected

public boolean isProtected()

setProtected

protected void setProtected(boolean b)

isProtectedFromDelete

public boolean isProtectedFromDelete()

setProtectedFromDelete

protected void setProtectedFromDelete(boolean b)

setHidden

public void setHidden(boolean b)

isHidden

public boolean isHidden()

setIsAlias

public void setIsAlias(boolean isAlias)

setProperty

public void setProperty(java.lang.String name,
                        java.lang.Object value)

removeProperty

public void removeProperty(java.lang.String name)

getProperty

public java.lang.Object getProperty(java.lang.String name)

getPropertyAsString

public java.lang.String getPropertyAsString(java.lang.String name)

equals

public boolean equals(java.lang.Object obj)
Compares two objects for equality of identity.

This method overrides the java.lang.Object equals method. It determines equality based on whether the two identities of the current object and the object argument are equal, where equal is defined as:

  1. The object argument is either an instance of a PersistentObject or an ObjectRef
  2. The types must match
  3. If both ids are not null, they must be the same
  4. If either or both ids are null, then the names must be the same

Note that this will makes it impossible to use the equals() method to do content comparison of two object copies. I'm not sure I really like this, its an unusual way to have equals() behave, but it is convenient for searching collections for references.

Parameters:
obj - - a PersistentObject or an ObjectRef

identityEquals

public boolean identityEquals(PersistentObject pobj)
Helper for the equals method, compares the identity of this object with another persistent object.


getMemberObjectGroupRefs

public java.util.List getMemberObjectGroupRefs()
Return the list of references to object groups this object is a member of.


getMemberObjectGroupRefsUpTo

public java.util.List getMemberObjectGroupRefsUpTo(ObjectGroup og)
                                            throws WavesetException
Returns the list of references to object groups this object is a member of up the hierarchy to the specified object group (e.g. Marketing -> Waveset -> Top) If no object group path exists between this object and the one passed in, a null list is returned.

Throws:
WavesetException

setMemberObjectGroupRefs

public void setMemberObjectGroupRefs(java.util.List refs)
                              throws WavesetException
Set the list of references to object groups to which this object is a member (say that 10 times fast). // *

// * jsl - is this necessary?

Throws:
WavesetException

getMemberObjectGroups

public ObjectGroup[] getMemberObjectGroups()
                                    throws WavesetException
Get an array of resolved object groups to which this object is a member.

This list is derived on demand from the list of group references.

Throws:
WavesetException

setMemberObjectGroups

public void setMemberObjectGroups(ObjectGroup[] ogarray)
                           throws WavesetException
Set the object groups to which this object is a member.

The list is specified as an array of group objects, it will be converted internally to a list of object reference objects.

Throws:
WavesetException

addMemberObjectGroup

public void addMemberObjectGroup(ObjectRef og)
                          throws WavesetException
Add a new object group, declaring this object as a member of that group. The group is specified as an object reference.

Throws:
WavesetException

setMemberObjectGroupRef

public void setMemberObjectGroupRef(ObjectRef og)
                             throws WavesetException
Set a single member object group ref

Throws:
WavesetException

addMemberObjectGroup

public void addMemberObjectGroup(ObjectGroup og)
                          throws WavesetException
Add a new object group, declaring this object as a member of that group. The group is specified as an object.

Throws:
WavesetException

removeMemberObjectGroup

public void removeMemberObjectGroup(ObjectGroup og)
Remove an object group from this object. This effectively takes this object out of the group.


directObjectGroupMember

public boolean directObjectGroupMember(ObjectGroup og)
                                throws WavesetException
Test to see if this object is a direct member of the given object group.

Throws:
WavesetException

objectGroupMember

public boolean objectGroupMember(ObjectGroup og)
                          throws WavesetException
Test to see if this object is a member of the given object group.

Throws:
WavesetException

objectGroupMemberRef

public ObjectRef objectGroupMemberRef(ObjectGroup og)
                               throws WavesetException
Test to see if this object is a member of the given object group.

Returns:
ObjectRef to the object group that this object is a member of
Throws:
WavesetException

setRuleDrivenMembersCache

public void setRuleDrivenMembersCache(RuleDrivenMembersCache cache)

getRuleDrivenMemberObjectGroupRefs

public java.util.List getRuleDrivenMemberObjectGroupRefs()
                                                  throws WavesetException
Return the list of references to object groups this object is a member of based on the evaluation of user members rules associated with the object groups controlled by the current subject.

Throws:
WavesetException

getRuleDrivenMemberObjectGroups

public ObjectGroup[] getRuleDrivenMemberObjectGroups()
                                              throws WavesetException
Get an array of resolved object groups to which this object is a member.

This list is derived on demand from the list of group references.

Throws:
WavesetException

ruleDrivenObjectGroupMemberRef

public ObjectRef ruleDrivenObjectGroupMemberRef(ObjectGroup og,
                                                java.util.List memberObjectGroupRefs)
                                         throws WavesetException
Test to see if this object is a member of the given object group.

Returns:
ObjectRef to the object group that this object is a member of
Throws:
WavesetException

getRuleDrivenMemberObjectGroupRefsUpTo

public java.util.List getRuleDrivenMemberObjectGroupRefsUpTo(ObjectGroup og,
                                                             ObjectGroup[] mogs)
                                                      throws WavesetException
Returns the list of references to object groups this object is a member of up the hierarchy to the specified object group (e.g. Marketing -> Waveset -> Top) If no object group path exists between this object and the one passed in, a null list is returned.

Throws:
WavesetException

getAttribute

public java.lang.String getAttribute(java.lang.String name)
                              throws WavesetException
Return the value of an abstract attribute if the class supports it.

Abstract attributes are not currently used, this interface was originally developed to support a concept that evolved into queryable attributes and summary attributes.

Throws:
WavesetException

getSummaryString

public java.lang.String getSummaryString()
Get the summary string for this object. In most cases, this is just a packed representation of the attributes returned by getSummaryAttributes. But some objects (WSUser) have special summary requirements, and may overload this method to calculate the summary in a special way.

Any subclass that overrides this implementation must limit the length of the summary string.

See Also:
Constants.MAX_SUMMARY_STRING_LENGTH

getSummaryAttributes

public WSAttributes getSummaryAttributes()
Returns:
attribute values to expose when this object appears in a list. The WSAttributes contains a WSAttribute for each attribute. Each WSAttribute may contain multiple values.

This default implementation adds values for attributes that are common to most (if not all) PersistentObjects.

See Also:

If a subclass wants to expose a different set of summary attributes, that subclass should override {@link #listSummaryAttributes}. In order to supply values for summary attributes that may not be available in PersistentObject (e.g., from a field specified to that subclass), such a subclass may also override {@link #getAttributeValues(Attribute)}.

A subclass should not need to override this method (except to limit the number of values for a summary attribute).


getAttributeValues

protected final WSAttributes getAttributeValues(java.util.List requestedAttributes)
Returns:
a set of attribute values that represent the values of this object for the specified list of defined attributes.

The WSAttributes contains a WSAttribute for each attribute. Each WSAttribute may contain multiple values.


getAttributeValues

protected WSAttribute getAttributeValues(java.lang.String attrName)
Returns:
a WSAttribute that represents the value (or values) that this object contains for the specified attribute.

listSummaryAttributes

public java.util.List listSummaryAttributes()
Returns the complete list of defined attributes that this type of persistent object exposes as summary attributes (regardless of whether this particular object has a value for each).

Any subclass of PersistentObject that overrides this method should first invoke super.listSummaryAttributes() to ensure that the subclass includes summary attributes that are common to all PersistentObjects.

Any subclass that overrides this implementation must also consider the length of the summary string that will be generated from these attributes.

See Also:
Constants.MAX_SUMMARY_STRING_LENGTH, getSummaryString()

resolveSummaryAttributes

public static void resolveSummaryAttributes(ObjectCache cache,
                                            WSAttributes attrs)
                                     throws WavesetException
Walk the summary attributes, translating the embedded IDs to names. For this object, they are just name and ID which do not need translating.

Throws:
WavesetException

prepareForSerialization

public void prepareForSerialization()
                             throws WavesetException
Prepare for serialization by doing anything that involves resolving references, leaving behind in the object anything that will be needed for toXml, getSummaryAttributes, getQueryableAttributes.

This is called by the session before checking in the object. Later the repository will ask for the xml and summary string.

Throws:
WavesetException

getQueryableAttributes

public final WSAttributes getQueryableAttributes()
Returns:
attribute values to be used as search keys for this object. The WSAttributes contains a WSAttribute for each queryable attribute. Each WSAttribute may contain multiple values.

This is normally not used by applications, but called by storage managers like the Repository. This allows us to define type-specific search keys without requiring the Repository to know the details of each type. <> This default implementation adds values for a number of attributes commonly queryable for PersistentObjects.

See Also:

If a subclass wants to expose a different set of queryable attributes, that subclass should override {@link #listQueryableAttributes()}. In order to supply values for queryable attributes that may not be available in PersistentObject (e.g., from a field specified to that subclass), such a subclass may also override {@link #getAttributeValues(Attribute)}.


listQueryableAttributes

public java.util.List listQueryableAttributes()
Returns:
the complete list of defined attributes that this type of PersistentObject exposes as queryable attributes (regardless of whether this object has a value for each).

Any subclass of PersistentObject that overrides this method must first invoke super.getQueryableAttributes() to ensure that the list of queryable attribute for PersistentObjects are included in the subclasses list.

NOTE: UPDATING THIS METHOD also affects getQueryableAttributes().


listOperationalAttributes

public void listOperationalAttributes(java.util.List attrs)
Add to the specified list the "built-in" attributes that are queryable just because the IDM Repository needs them in order to operate.


listQueryableReferenceAttributes

public java.util.List listQueryableReferenceAttributes()
Returns:
the list of defined attributes that this type of persistent object exposes as queryable and for which each value is a reference to another persistent object.

This is intended to be overloaded each subclass to add queryable reference attributes that are specific to that subclass.


getEncryptedValues

public java.util.List getEncryptedValues()
Returns:
the complete list of object values whose type is encrypted data (regardless of whether this object has a value for each).

Any subclass of PersistentObject that overrides this method must first invoke super.getEncryptedValues() to ensure that the list of encrypted values for PersistentObjects are included in the subclasses list.


attributesMatch

public final boolean attributesMatch(LogicalExpression filter)
Return true if the attributes exposed by this object satisfy the specified logical expression.

The default implementation here calls getQueryableAttributes to obtain the object's attribute list. This can be overloaded if desired if for some reason you want to support matching, without exposing queryable attributes.

See Also:
LogicalExpression

attributesMatch

public final boolean attributesMatch(AttributeCondition[] attrConds)
Return true if the attributes exposed by this object meet the supplied list of attribute conditions.

The default implementation here calls getQueryableAttributes to obtain the object's attribute list. This can be overloaded if desired if for some reason you want to support matching, without exposing queryable attributes.

See Also:
AttributeCondition

attributesMatch

public final boolean attributesMatch(WSAttributes extatts)
Return true if the supplied list of attributes match attributes exposed by this object.

The default implementation here calls getQueryableAttributes to obtain the object's attribute list. This can be overloaded if desired if for some reason you want to support matching, without exposing queryable attributes.

See Also:
WSAttributes

getReferences

public java.util.ArrayList getReferences()
Returns the list of all references in this object. This is intended to be overloaded by subclasses to add references specific to that class.


getAuthReferences

public java.util.ArrayList getAuthReferences()
Returns the list of all references in this object that are subject to CONNECT/DISCONNECT Right authorization checks. In most cases this will be the same list as returned by getReferences for a given persistent object. However, some objects like WSUser include object references not directly assigned by the user but generated by the system (e.g. ResourceInfo's) which are not subject to authorization checks when they change. This method should be overridden by subclasses that require the list of references to be different than the ones returned by getReferences.


isReferencedIn

public boolean isReferencedIn(java.util.Collection coll)
Returns true if an ObjectRef reference to this object is contained within the collection.

This is typically used by classes that maintain a collection of ObjectRefs, and wish to detect attempts to add the same reference more than once.

This could also be a static on ObjectRef, but it felt ok to handle this here too. At the moment you could accomplish a similar function using the Collection.contains method since our equals() method is overloaded to handle ObjectRef comparison. Defining equality for two completely different objects feels strange though, so this interface is also provided.

Parameters:
coll - - a collection (usually an ArrayList) that we will search

resolve

public PersistentObject resolve(ObjectRef ref)
                         throws WavesetException
Resolve a single reference. If the reference is not already resolved, we'll ask our cache to resolve it. We do not throw an exception if the object no longer exists.

If the object does not exist, the reference will be marked as being deleted, so that the ObjectRef.isDeleted method will return true.

Throws:
WavesetException
See Also:
ObjectRef.isDeleted()

resolve

public int resolve(java.util.List refs)
            throws WavesetException
Resolve a list of references, filtering out elements that no longer resolve.

Returns the size of the reference list.

Throws:
WavesetException

resolveArrayByFetching

public java.lang.Object resolveArrayByFetching(java.util.List refs,
                                               java.lang.Object[] array,
                                               java.lang.Class elClass)
                                        throws WavesetException
Now that users can also be administrators that can be approvers or be notified, together with the fact that users are a supressed type meaning they never get cached, we need a way to ensure that we alway resolve these list of refs by hitting the repo.

Resolve a list of references, creating a typed array of PersistentObject pointers. Used by suppressed objects to provide a more convenient array interface for collections of references.

Note that in order to assure that we are always resolving the objects from the repo, we will null out the ref handles before calling resolveArray. !! Note that since this modifies the list, it is not thread safe if you happen to be operating within the server cache. The caller must be synchronized.

Throws:
WavesetException

resolveArray

public java.lang.Object resolveArray(java.util.List refs,
                                     java.lang.Object[] array,
                                     java.lang.Class elClass)
                              throws WavesetException
Resolve a list of references, creating a typed array of PersistentObject pointers. Used by various objects to provide a more convenient array interface for collections of references.

We allow an existing array to be passed in, and will try to reuse the array if it hasn't changed in size. !! Note that since this modifies the list, it is not thread safe if you are in the server thread. But its overly restrictive to synchronize here, the caller must be synchronized.

Throws:
WavesetException

resolve

public boolean resolve(java.util.List refs,
                       java.lang.Object[] array)
                throws WavesetException
Resolve a list of references, storing pointers to the resolved objects in an array as a side effect. This is optimized for objects that maintain both an ArrayList of references, as well as an array of native object pointers in a cache that they want to keep refreshed.

We return true if the provided array matched the number of resolved references, this is the usual case. If the array size doesn't match, we'll still try to resolve all the elements in the list, but the caller will have to reallocate a suitable array. It would be nice if we could do this automatically, but we'd have to know the type of array to allocate, and I'm not sure how to do that with reflection.

Throws:
WavesetException

resolveReference

public PersistentObject resolveReference(ObjectRef ref)
                                  throws WavesetException
DEPRECATED: like resolve above but throws an exception if it can't find it, try to weed these out.

Resolve a reference, throwing an exception if the object didn't exist. We're moving toward being tolerant of deleted objects, so you should call resolve instead. This will shortly become the default behavior.

Parameters:
ref - - an object reference
Throws:
WavesetException

checkReference

public void checkReference(ObjectRef ref)
Checks a reference owned by an object to make sure that the referenced object is in the same cache as the referencing object. This was added to diagnose a cache wiring problem; we may want to turn this into an exception.


checkReferences

public void checkReferences(java.util.List refs)
Check a list of references.


resolveObjectReferences

public void resolveObjectReferences(ObjectCache cache)
                             throws WavesetException
Walk over an object looking for ObjectRefs without ids and resolve them.

We originally used the generic resolveReferences for this, but this operates off of the DOM tree and requires an expensive user/dom/user conversion. Since we're called from bulk load have to be more careful about garabge.

Formerly picked specific attributes out of the user object but that wasn't robust. Assume PersistentObject.getReferences is correct.

Throws:
WavesetException

resolveObjectReference

protected void resolveObjectReference(ObjectRef ref,
                                      PersistentObject owner,
                                      ObjectCache cache)
                               throws WavesetException
Throws:
WavesetException

prepareToSerialize

public void prepareToSerialize()
                        throws WavesetException
Update the structure of the object prior to serialization. This usually does nothing, but certain objects (notably WSUser) may perform complex traversal of related objects such as Roles to compute their summary attrbutes. It is important that resolution of object references be done oustside of the toXml, getQueryableAttributes or getSummaryAttributes calls, due to synchronization issues with the Repository. If your class needs to resolve references in any of these mehtods, it must be designed to do the resolution here and leave the results beind in the object for later use in these methods.

Throws:
WavesetException

toXml

public java.lang.String toXml()
Serialize the object to an XML string.

The default implementation is to create a string buffer, add an XML header and call the toXml(StringBuffer) method. This may be overloaded by the subclasses, though there is usually no need to.

Specified by:
toXml in interface XmlObject
Returns:
the string representation of this object

toXmlFile

public void toXmlFile(java.lang.String file)
Serialize the object to a file. A hack primarily for debugging with JBuilder.


dump

public void dump()
for consistency with XmlObjectFactory & AbstractXmlObject


dumpFile

public void dumpFile(java.lang.String file)

addXmlHeader

public static void addXmlHeader(java.lang.StringBuffer b,
                                java.lang.String element)
Adds a standard XML header, DOCTYPE statement and element start tag. This is typically called by the toXml method above prior to calling the toXml method of a subclass. Subclasses may also call it if they want to overload the generation of the header or DOCTYPE for some reason, though there should be no reason to do so.


toXml

public void toXml(java.lang.StringBuffer b)
Serialize the object as XML into a string buffer. PersistentObject's implementation provides a standard template for its concrete subclasses.

NOTE: Each subclass should serialize any necessary fields specific to that subclass. // * @see #addSubclassAttributes // * @see #addSubclassElements


toXml

public void toXml(java.lang.StringBuffer b,
                  int indent)
Serialize the object as XML with an optional indentation. // * This is the one XmlObject wants to have defined, persistent objects // * should implement this, but its too late now. Since // * they're usually at top level anyway, it doesn't hurt much.

Specified by:
toXml in interface XmlObject
Parameters:
b - target buffer
indent - amount of indentation

addStartTag

protected void addStartTag(java.lang.StringBuffer b,
                           boolean close)
Emit a start tag and persistent attributes.

This should be called at the start of the toXml method for all subclasses. If the close option is false, then the subclass is responsible for adding the start tag close character ('>'). This is done if the subclass has more attributes they want to add after the required attributes.

Parameters:
b - - output string buffer
close - - true to close the start tag, false to leave it open

addSummaryAttributes

protected void addSummaryAttributes(java.lang.StringBuffer b)

addPersistentAttributes

protected void addPersistentAttributes(java.lang.StringBuffer b)
Emit the persistent attributes assuming an open start tag.

All PersistentObject subclasses must serialize the inherited attributes as XML attributes on the wrapper element by calling this method after they have added their own start tag.

The attributes added here must be parsed by the parsePersistentAttributes method.

See Also:
parsePersistentAttributes(Element)

addSubclassAttributes

protected void addSubclassAttributes(java.lang.StringBuffer b)
Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist). PersistentObject's default implementation is a no-op.

NOTE: Any subclass that overrides this method must similarly override parseSubclassAttributes() so that the subclass attributes are restored.

See Also:


addSubclassElements

protected void addSubclassElements(java.lang.StringBuffer b)
Each concrete subclass may append to the buffer an XML representation of any fields it adds to PersistentObject (if those field values must persist). PersistentObject's default implementation is a no-op.

NOTE: Any subclass that overrides this method must similarly override parseSubclassElements() so that the subclass elements are restored.

See Also:


parseSubclassAttributes

protected void parseSubclassAttributes(org.w3c.dom.Element e)
                                throws WavesetException
Each concrete subclass should parse from the XML buffer any persisted subclass-specific fields (generally, the same ones that it writes into the buffer).

Throws:
WavesetException
See Also:

PersistentObject's default implementation is a no-op.

, parseXml(Element)

parseSubclassElements

protected void parseSubclassElements(org.w3c.dom.Element e)
                              throws WavesetException
Each concrete subclass should parse from the XML buffer any persisted subclass-specific elements (generally, the same ones that it writes into the buffer).

Throws:
WavesetException
See Also:

PersistentObject's default implementation is a no-op.

, parseXml(Element)

addCommonElements

protected void addCommonElements(java.lang.StringBuffer b)
Add elements common to all persistent objects. PersistentObject subclasses must call this somewhere within their toXml methods, typically at the end, before calling addEndTag.

Any elements added here must be processed by the parseCommonElement method.

See Also:
parseCommonElement(org.w3c.dom.Element)

addEndTag

protected void addEndTag(java.lang.StringBuffer b)
Add the end tag for this object. This should be called at the end of the toXml method for all PersistentObject subclasses.


parseXml

protected void parseXml(java.lang.String xml)
                 throws WavesetException
A concrete subclass can implement the required constructor that takes a single String (containing XML) simply by invoking this method.

Throws:
WavesetException

parseXml

protected void parseXml(org.w3c.dom.Element e)
                 throws WavesetException
A concrete subclass can implement the required constructor that takes a single XML Element (fully qualified class name here) by invoking this method and implementing the abstract method to parse any subclass-specific fields.

Throws:
WavesetException
See Also:
parseSubclassAttributes(org.w3c.dom.Element)

parsePersistentAttributes

protected void parsePersistentAttributes(org.w3c.dom.Element e)
Parse the common set of XML attributes that all persistent object serializations should have. This must be called by all PersistentObject subclasses inside their parseXml methods.

The attributes parsed must correspond to those added by the addPersistentAttributes(StringBuffer) method.


parseCommonElement

protected void parseCommonElement(org.w3c.dom.Element e)
                           throws WavesetException
Handle a body element that the subclass didn't want. We look for the common elements that should have been added by addCommonElements. This must be called by the parseXml method of PersistentObject subclasses when they encounter an element that they do not recognize.

If we don't recognize this element, it is silently ignored. We could have an option to throw an error, but its generally better to be tolerant of such things, so that the object can be deserialized and repaired. DTD validation should have caught unrecognized elements if the XML source was untrusted, for trusted sources, we'll must assume its correct.

Throws:
WavesetException

parseCommonElements

protected void parseCommonElements(org.w3c.dom.Element wrapper)
                            throws WavesetException
Examine all body elements and treat them as common elements. This is a convenience method for types that don't contribute any elements of their own, but they would otherwise still have to have this little traversal code in their parseXml methods.

Throws:
WavesetException

cloneObject

public PersistentObject cloneObject()
                             throws WavesetException
Clones an object.

We don't overload the java.lang.Object.clone method because it can't throw any exceptions, and there is the potential for deserialization errors here (though I suppose we could throw an unchecked exceptions).

The clone is done using the XML serialization that all PersistentObjects must support. It would probably be more efficient to implement java.lang.Serializable, but that's another serialization format that would have to be debugged. Since we have to support XML transforms anyway, just use that.

Returns:
an exact duplicate of this object

Throws:
WavesetException - if there were problems duplicating the object

cloneAs

public PersistentObject cloneAs(java.lang.String newName)
                         throws WavesetException
Clones an object, changing the name in the process.

This is a convenience method for a common set of operations when attempting to create a new object that is a derivative of another.

We'll clone the object, clear the old object ID, and assign a differeent name.

Returns:
an duplicate of this object with no ID and a new name

Throws:
WavesetException - if there were problems duplicating the object

getInitialInstances

public static PersistentObject.InitialInstance[] getInitialInstances()
Returns the set of initial instances that should be created for this object type when a repository is created.

ServerRepository initialization will call this method on the Java class associated with each Type to get a list of the items it should "seed" into the repository.

Each initial instance contains a PersistentObject to be added, as well as boolean methods that describe any special handling.


getLastModItemId

public static java.lang.String getLastModItemId(Type type)

createLastModItem

public static PersistentObject.InitialInstance createLastModItem(PersistentObject obj)
Build an InitialInstance for a special object used to hold the last modification time of all objects of a particular type. Since these are all constructed in the same way, any PersistentObject subclass may use this helper method to build an initial instance.


createLastModItemList

public static PersistentObject.InitialInstance[] createLastModItemList(PersistentObject obj)
Build an InitialInstance array containing a single instance for the special "last mode time" marker.

A helper method that may be used by persistent object classes that want to have their mod times tracked, but have no other initial instances.


createLastModItem

public static PersistentObject.InitialInstance createLastModItem(Type type)

compareTo

public int compareTo(java.lang.Object o)
Implement the Comparable interface so that lists of these will have a reasonable contains() implementation

Specified by:
compareTo in interface java.lang.Comparable

hashCode

public int hashCode()
Implement the hashCode for efficient map insertion


getReference

public javax.naming.Reference getReference()
                                    throws javax.naming.NamingException
Specified by:
getReference in interface javax.naming.Referenceable
Throws:
javax.naming.NamingException

getBasicAttributes

public javax.naming.directory.BasicAttributes getBasicAttributes()

getBasicAttributes

public javax.naming.directory.BasicAttributes getBasicAttributes(java.lang.String[] attrIds)

getBasicAttributes

public static javax.naming.directory.BasicAttributes getBasicAttributes(PersistentObject po,
                                                                        java.lang.String[] attrIds)