org.opensaml
Class SAMLObject

java.lang.Object
  extended by org.opensaml.SAMLObject
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
SAMLAction, SAMLAttribute, SAMLAttributeDesignator, SAMLAuthorityBinding, SAMLCondition, SAMLNameIdentifier, SAMLQuery, SAMLSignedObject, SAMLStatement, SAMLSubject

public abstract class SAMLObject
extends Object
implements Cloneable

Abstract base class for all SAML constructs

Author:
Scott Cantor

Field Summary
protected  SAMLConfig config
          OpenSAML configuration
protected  boolean dirty
          Dirty bit triggers recreation of DOM
protected  org.apache.log4j.Logger log
          Class-specific logging object
protected  SAMLObject parentObject
          Back pointer to SAML "parent" to allow back-walking and prevent double-containment
protected  Node root
          Root node of a DOM tree capturing the object
 
Constructor Summary
SAMLObject()
           
 
Method Summary
protected abstract  Element buildRoot(Document doc, boolean xmlns)
          Delegates the process of building the root element of an object and inserting appropriate namespaces.
abstract  void checkValidity()
          Evaluates the object's content to see if it is currently valid if serialized.
protected  Object clone()
          Copies a SAML object such that no dependencies exist between the original and the copy.
 void fromDOM(Element e)
          Initialization of an object from a DOM element
protected static Element fromStream(InputStream in)
          Allows parsing of objects from a stream of XML
protected static Element fromStream(InputStream in, int minor)
          Allows parsing of objects of a particular minor version from a stream of XML
 SAMLObject getParent()
          Returns the containing object, if any.
protected  Node plantRoot()
          Installs the root node of this DOM as the document element
protected  void setDirty(boolean flag)
          Sets or clears the object's dirty bit.
 SAMLObject setParent(SAMLObject parent)
          Informs the object that it is being inserted into a composite structure, allowing it to check for existing containment and throw an exception, preventing unexplained errors due to multiple object containment.
 byte[] toBase64()
          Returns a base64-encoded XML representation of the SAML object
 Node toDOM()
          Transforms the object into a DOM tree without an existing document context, including namespace declarations
 Node toDOM(boolean xmlns)
          Transforms the object into a DOM tree without an existing document context
 Node toDOM(Document doc)
          Transforms the object into a DOM tree using an existing document context, including namespace declarations
 Node toDOM(Document doc, boolean xmlns)
          Transforms the object into a DOM tree using an existing document context
 void toStream(OutputStream out)
          Serializes the XML representation of the SAML object to a stream
 String toString()
          Serializes a SAML object to a string in exclusive canonical form.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

config

protected SAMLConfig config
OpenSAML configuration


root

protected Node root
Root node of a DOM tree capturing the object


log

protected org.apache.log4j.Logger log
Class-specific logging object


parentObject

protected SAMLObject parentObject
Back pointer to SAML "parent" to allow back-walking and prevent double-containment


dirty

protected boolean dirty
Dirty bit triggers recreation of DOM

Constructor Detail

SAMLObject

public SAMLObject()
Method Detail

setDirty

protected void setDirty(boolean flag)
Sets or clears the object's dirty bit. When set, serialization will flush an existing DOM. All parent objects will also be flagged.

Parameters:
flag - The new value of the dirty bit

fromStream

protected static Element fromStream(InputStream in)
                             throws SAMLException
Allows parsing of objects from a stream of XML

Parameters:
in - A stream containing XML
Returns:
The root of the XML document instance
Throws:
SAMLException - Raised if an exception occurs while constructing the object

fromStream

protected static Element fromStream(InputStream in,
                                    int minor)
                             throws SAMLException
Allows parsing of objects of a particular minor version from a stream of XML

Parameters:
in - A stream containing XML
minor - The minor version of the incoming object
Returns:
The root of the XML document instance
Throws:
SAMLException - Raised if an exception occurs while constructing the object

plantRoot

protected Node plantRoot()
Installs the root node of this DOM as the document element

Returns:
The root node so planted

buildRoot

protected abstract Element buildRoot(Document doc,
                                     boolean xmlns)
Delegates the process of building the root element of an object and inserting appropriate namespaces.

Parameters:
doc - The document context to use
xmlns - Include namespace(s) on root element?
Returns:
A new root element for the object

checkValidity

public abstract void checkValidity()
                            throws SAMLException
Evaluates the object's content to see if it is currently valid if serialized. Does not evaluate embedded objects except on the basis of whether they exist. For example, an Assertion must have a Statement, but if an invalid statement is added, SAMLAssertion.checkValidity() would succeed, while SAMLStatement.checkValidity would raise an exception.

Throws:
SAMLException - Raised if the serialized object would be invalid SAML, excluding any embedded objects

setParent

public SAMLObject setParent(SAMLObject parent)
                     throws SAMLException
Informs the object that it is being inserted into a composite structure, allowing it to check for existing containment and throw an exception, preventing unexplained errors due to multiple object containment.

Parameters:
parent - The object into which this object is being inserted
Returns:
A reference to the object being inserted (allows for cleaner insertion)
Throws:
SAMLException - Raised if this object already has a parent

getParent

public SAMLObject getParent()
Returns the containing object, if any. Multiple containment of a single object is prohibited! You must clone() to add an owned object to another parent.

Returns:
The parent SAML object, or null if stand-alone

fromDOM

public void fromDOM(Element e)
             throws SAMLException
Initialization of an object from a DOM element

Parameters:
e - Root element of a DOM tree
Throws:
SAMLException - Raised if an exception occurs while constructing the object

toStream

public void toStream(OutputStream out)
              throws IOException,
                     SAMLException
Serializes the XML representation of the SAML object to a stream

Parameters:
out - Stream to use for output
Throws:
IOException - Raised if an I/O problem is detected
SAMLException - Raised if the object is incompletely defined

toBase64

public byte[] toBase64()
                throws IOException,
                       SAMLException
Returns a base64-encoded XML representation of the SAML object

Returns:
A byte array containing the encoded data
Throws:
IOException - Raised if an I/O problem is detected
SAMLException - Raised if the object is incompletely defined

toDOM

public Node toDOM(Document doc,
                  boolean xmlns)
           throws SAMLException
Transforms the object into a DOM tree using an existing document context

Parameters:
doc - A Document object to use in manufacturing the tree
xmlns - Include namespace(s) on root element?
Returns:
Root element node of the DOM tree capturing the object
Throws:
SAMLException - Raised if the object is incompletely defined

toDOM

public Node toDOM(boolean xmlns)
           throws SAMLException
Transforms the object into a DOM tree without an existing document context

Parameters:
xmlns - Include namespace(s) on root element?
Returns:
Root element node of the DOM tree capturing the object
Throws:
SAMLException - Raised if the object is incompletely defined

toDOM

public Node toDOM(Document doc)
           throws SAMLException
Transforms the object into a DOM tree using an existing document context, including namespace declarations

Parameters:
doc - A Document object to use in manufacturing the tree
Returns:
Root element node of the DOM tree capturing the object
Throws:
SAMLException - Raised if the object is incompletely defined

toDOM

public Node toDOM()
           throws SAMLException
Transforms the object into a DOM tree without an existing document context, including namespace declarations

Returns:
Root element node of the DOM tree capturing the object
Throws:
SAMLException - Raised if the object is incompletely defined

clone

protected Object clone()
                throws CloneNotSupportedException
Copies a SAML object such that no dependencies exist between the original and the copy.

Overrides:
clone in class Object
Returns:
The new object
Throws:
CloneNotSupportedException
See Also:
Object.clone()

toString

public String toString()
Serializes a SAML object to a string in exclusive canonical form.

Overrides:
toString in class Object
Returns:
The canonicalized output
See Also:
Object.toString()


Copyright ? 2005 UCAID. All Rights Reserved.