gov.nih.nci.cagrid.opensaml
Class SAMLObject

java.lang.Object
  gov.nih.nci.cagrid.opensaml.SAMLObject

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

SAMLAction, SAMLAttribute, SAMLAttributeDesignator, SAMLAuthorityBinding, SAMLCondition, SAMLNameIdentifier, SAMLQuery, SAMLSignedObject, SAMLStatement, SAMLSubject

public abstract class SAMLObject
extends java.lang.Object
implements java.lang.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 org.w3c.dom.Node	root Root node of a DOM tree capturing the object

Constructor Summary

SAMLObject()

Method Summary

protected abstract org.w3c.dom.Element	buildRoot(org.w3c.dom.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 java.lang.Object	clone() Copies a SAML object such that no dependencies exist between the original and the copy.
void	fromDOM(org.w3c.dom.Element e) Initialization of an object from a DOM element
protected static org.w3c.dom.Element	fromStream(java.io.InputStream in) Allows parsing of objects from a stream of XML
protected static org.w3c.dom.Element	fromStream(java.io.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 org.w3c.dom.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
org.w3c.dom.Node	toDOM() Transforms the object into a DOM tree without an existing document context, including namespace declarations
org.w3c.dom.Node	toDOM(boolean xmlns) Transforms the object into a DOM tree without an existing document context
org.w3c.dom.Node	toDOM(org.w3c.dom.Document doc) Transforms the object into a DOM tree using an existing document context, including namespace declarations
org.w3c.dom.Node	toDOM(org.w3c.dom.Document doc, boolean xmlns) Transforms the object into a DOM tree using an existing document context
void	toStream(java.io.OutputStream out) Serializes the XML representation of the SAML object to a stream
java.lang.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 org.w3c.dom.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 org.w3c.dom.Element fromStream(java.io.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 org.w3c.dom.Element fromStream(java.io.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 org.w3c.dom.Node plantRoot()

Installs the root node of this DOM as the document element

Returns:

The root node so planted

buildRoot

protected abstract org.w3c.dom.Element buildRoot(org.w3c.dom.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(org.w3c.dom.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(java.io.OutputStream out)
              throws java.io.IOException,
                     SAMLException

Serializes the XML representation of the SAML object to a stream

Parameters:

out - Stream to use for output

Throws:

java.io.IOException - Raised if an I/O problem is detected

SAMLException - Raised if the object is incompletely defined

toBase64

public byte[] toBase64()
                throws java.io.IOException,
                       SAMLException

Returns a base64-encoded XML representation of the SAML object

Returns:

A byte array containing the encoded data

Throws:

java.io.IOException - Raised if an I/O problem is detected

SAMLException - Raised if the object is incompletely defined

toDOM

public org.w3c.dom.Node toDOM(org.w3c.dom.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 org.w3c.dom.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 org.w3c.dom.Node toDOM(org.w3c.dom.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 org.w3c.dom.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 java.lang.Object clone()
                          throws java.lang.CloneNotSupportedException

Copies a SAML object such that no dependencies exist between the original and the copy.

Overrides:

clone in class java.lang.Object

Returns:

The new object

Throws:

java.lang.CloneNotSupportedException

See Also:

Object.clone()

toString

public java.lang.String toString()

Serializes a SAML object to a string in exclusive canonical form.

Overrides:

toString in class java.lang.Object

Returns:

The canonicalized output

See Also:

Object.toString()