org.opensaml
Class SAMLException

java.lang.Object
  extended by java.lang.Throwable
      extended by java.lang.Exception
          extended by org.opensaml.SAMLException
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
BindingException, InvalidCryptoException, MalformedException, NoSuchProviderException, ProfileException, UnsupportedExtensionException

public class SAMLException
extends Exception
implements Cloneable

Encapsulates a general SAML error.

If the runtime needs to pass through other types of exceptions, it must wrap those exceptions in a SAMLException or an exception derived from a SAMLxception.

The association with the SAML Status element is loose, but is intentional. The codes you pass into this object are embedded in nested sequence inside the XML representation. There is currently no support for the StatusDetail element.

Ideally, this would also inherit from SAMLObject, but Java is limited to single inheritance, so there's no way to inherit the functionality; instead we reimplement the SAMLObject code here. (Note that interfaces!=multiple inheritance and don't solve the problem.)

Author:
Scott Cantor
See Also:
Serialized Form

Field Summary
protected  ArrayList codes
          Collection of status codes (QNames)
protected  SAMLConfig config
          OpenSAML configuration
protected  Exception e
          Embedded exception, if any
protected  org.apache.log4j.Logger log
          Class-specific logging object
protected  String msg
          Status message embedded in exception
protected  SAMLObject parentObject
          Back pointer to SAML "parent" to allow back-walking and prevent double-containment
static javax.xml.namespace.QName REQUESTER
          SAML Requester status code
static javax.xml.namespace.QName RESPONDER
          SAML Responder status code
protected  Node root
          Root node of a DOM tree capturing the object
static javax.xml.namespace.QName SUCCESS
          SAML Success status code
static javax.xml.namespace.QName VERSION
          SAML Version Mismatch status code
 
Constructor Summary
  SAMLException(Collection codes)
          Creates a new SAMLException
  SAMLException(Collection codes, Exception e)
          Creates a new SAMLException wrapping an existing exception
  SAMLException(Collection codes, String msg)
          Creates a new SAMLException
  SAMLException(Collection codes, String msg, Exception e)
          Creates a new SAMLException from an existing exception.
protected SAMLException(Element e)
          Initializes an exception from a DOM tree
  SAMLException(javax.xml.namespace.QName code)
          Creates a new SAMLException
  SAMLException(javax.xml.namespace.QName code, Exception e)
          Creates a new SAMLException wrapping an existing exception
  SAMLException(javax.xml.namespace.QName code, String msg)
          Creates a new SAMLException
  SAMLException(javax.xml.namespace.QName code, String msg, Exception e)
          Creates a new SAMLException from an existing exception.
  SAMLException(String msg)
          Creates a new SAMLException
  SAMLException(String msg, Exception e)
          Creates a new SAMLException
 
Method Summary
 Object clone()
          Copies a SAML object such that no dependencies exist between the original and the copy.
 void fromDOM(Element e)
          Handles initialization of exceptions from a DOM element
 Iterator getCodes()
          Gets the status or fault code QNames
 Exception getException()
          Returns the embedded exception, if any
static SAMLException getInstance(Element e)
          Locates an implementation class for an exception and constructs it based on the DOM provided.
static SAMLException getInstance(InputStream in)
          Locates an implementation class for an exception and constructs it based on the stream provided.
 String getMessage()
          Returns a detail message for this exception
 SAMLObject getParent()
          Returns the containing object, if any.
 SAMLException 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.
 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 a SAML Status to a stream
 String toString()
          Overrides toString to pick up any embedded exception
 
Methods inherited from class java.lang.Throwable
fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

SUCCESS

public static final javax.xml.namespace.QName SUCCESS
SAML Success status code


REQUESTER

public static final javax.xml.namespace.QName REQUESTER
SAML Requester status code


RESPONDER

public static final javax.xml.namespace.QName RESPONDER
SAML Responder status code


VERSION

public static final javax.xml.namespace.QName VERSION
SAML Version Mismatch status code


msg

protected String msg
Status message embedded in exception


e

protected Exception e
Embedded exception, if any


codes

protected ArrayList codes
Collection of status codes (QNames)


root

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


parentObject

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


log

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


config

protected SAMLConfig config
OpenSAML configuration

Constructor Detail

SAMLException

protected SAMLException(Element e)
                 throws SAMLException
Initializes an exception from a DOM tree

Parameters:
e - The root of a DOM tree
Throws:
SAMLException - Raised if an exception occurs while constructing the object.

SAMLException

public SAMLException(String msg)
Creates a new SAMLException

Parameters:
msg - The detail message

SAMLException

public SAMLException(String msg,
                     Exception e)
Creates a new SAMLException

Parameters:
msg - The detail message
e - The exception to be wrapped in a SAMLException

SAMLException

public SAMLException(Collection codes)
Creates a new SAMLException

Parameters:
codes - A collection of QNames

SAMLException

public SAMLException(Collection codes,
                     String msg)
Creates a new SAMLException

Parameters:
codes - A collection of QNames
msg - The detail message

SAMLException

public SAMLException(Collection codes,
                     Exception e)
Creates a new SAMLException wrapping an existing exception

The existing exception will be embedded in the new one, and its message will become the default message for the SAMLException.

Parameters:
codes - A collection of QNames
e - The exception to be wrapped in a SAMLException

SAMLException

public SAMLException(Collection codes,
                     String msg,
                     Exception e)
Creates a new SAMLException from an existing exception.

The existing exception will be embedded in the new one, but the new exception will have its own message.

Parameters:
codes - A collection of QNames
msg - The detail message
e - The exception to be wrapped in a SAMLException

SAMLException

public SAMLException(javax.xml.namespace.QName code)
Creates a new SAMLException

Parameters:
code - A status code

SAMLException

public SAMLException(javax.xml.namespace.QName code,
                     String msg)
Creates a new SAMLException

Parameters:
code - A status code
msg - The detail message

SAMLException

public SAMLException(javax.xml.namespace.QName code,
                     Exception e)
Creates a new SAMLException wrapping an existing exception

The existing exception will be embedded in the new one, and its message will become the default message for the SAMLException.

Parameters:
code - A status code
e - The exception to be wrapped in a SAMLException

SAMLException

public SAMLException(javax.xml.namespace.QName code,
                     String msg,
                     Exception e)
Creates a new SAMLException from an existing exception.

The existing exception will be embedded in the new one, but the new exception will have its own message.

Parameters:
code - A status code
msg - The detail message
e - The exception to be wrapped in a SAMLException
Method Detail

getInstance

public static SAMLException getInstance(Element e)
                                 throws SAMLException
Locates an implementation class for an exception and constructs it based on the DOM provided.

Parameters:
e - The root of a DOM containing the SAML exception
Returns:
SAMLException A constructed exception object
Throws:
SAMLException - Thrown if an error occurs while constructing the object

getInstance

public static SAMLException getInstance(InputStream in)
                                 throws SAMLException
Locates an implementation class for an exception and constructs it based on the stream provided.

Parameters:
in - The stream to deserialize from
Returns:
SAMLException A constructed exception object
Throws:
SAMLException - Thrown if an error occurs while constructing the object

setParent

public SAMLException 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
Handles initialization of exceptions from a DOM element

Parameters:
e -
Throws:
SAMLException - Raised if an exception occurs while initializing the object

toStream

public void toStream(OutputStream out)
              throws IOException,
                     SAMLException
Serializes the XML representation of a SAML Status 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 invalid

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 exception is invalid

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 exception is invalid

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 exception is invalid

getCodes

public Iterator getCodes()
Gets the status or fault code QNames

Returns:
An iterator of QNames

getMessage

public String getMessage()
Returns a detail message for this exception

If there is an embedded exception, and if the SAMLException has no detail message of its own, this method will return the detail message from the embedded exception.

Overrides:
getMessage in class Throwable
Returns:
The error message

getException

public Exception getException()
Returns the embedded exception, if any

Returns:
The embedded exception, or null if there is none

toString

public String toString()
Overrides toString to pick up any embedded exception

One quirk is that this method does not produce a serialized XML representation of the object. toString is oriented around the usual expectations of Exception clients, while toStream implements the behavior expected by SAMLObject clients.

Overrides:
toString in class Throwable
Returns:
A string (but not XML) representation of this exception

clone

public 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()


Copyright ? 2005 UCAID. All Rights Reserved.