org.opensaml
Class SAMLObject

java.lang.Object
  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()