org.opensaml
Class SAMLException

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

public class SAMLException
extends java.lang.Exception
implements java.lang.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.

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  java.util.ArrayList codes
          Collection of status codes (QNames)
protected  SAMLConfig config
          OpenSAML configuration
protected  java.lang.Exception e
          Embedded exception, if any
protected  org.apache.log4j.Logger log
          Class-specific logging object
protected  java.lang.String msg
          Status message embedded in exception
static QName REQUESTER
          SAML Requester status code
static QName RESPONDER
          SAML Responder status code
protected  org.w3c.dom.Node root
          Root node of a DOM tree capturing the object
static QName SUCCESS
          SAML Success status code
static QName VERSION
          SAML Version Mismatch status code
 
Constructor Summary
  SAMLException(java.util.Collection codes)
          Creates a new SAMLException
  SAMLException(java.util.Collection codes, java.lang.Exception e)
          Creates a new SAMLException wrapping an existing exception
  SAMLException(java.util.Collection codes, java.lang.String msg)
          Creates a new SAMLException
  SAMLException(java.util.Collection codes, java.lang.String msg, java.lang.Exception e)
          Creates a new SAMLException from an existing exception.
protected SAMLException(org.w3c.dom.Element e)
          Initializes an exception from a DOM tree
  SAMLException(QName code)
          Creates a new SAMLException
  SAMLException(QName code, java.lang.Exception e)
          Creates a new SAMLException wrapping an existing exception
  SAMLException(QName code, java.lang.String msg)
          Creates a new SAMLException
  SAMLException(QName code, java.lang.String msg, java.lang.Exception e)
          Creates a new SAMLException from an existing exception.
  SAMLException(java.lang.String msg)
          Creates a new SAMLException
  SAMLException(java.lang.String msg, java.lang.Exception e)
          Creates a new SAMLException
 
Method Summary
 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)
          Handles initialization of exceptions from a DOM element
 java.util.Iterator getCodes()
          Gets the status or fault code QNames
 java.lang.Exception getException()
          Returns the embedded exception, if any
static SAMLException getInstance(org.w3c.dom.Element e)
          Locates an implementation class for an exception and constructs it based on the DOM provided.
static SAMLException getInstance(java.io.InputStream in)
          Locates an implementation class for an exception and constructs it based on the stream provided.
 java.lang.String getMessage()
          Returns a detail message for this exception
 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 a SAML Status to a stream
 java.lang.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 QName SUCCESS
SAML Success status code


REQUESTER

public static final QName REQUESTER
SAML Requester status code


RESPONDER

public static final QName RESPONDER
SAML Responder status code


VERSION

public static final QName VERSION
SAML Version Mismatch status code


msg

protected java.lang.String msg
Status message embedded in exception


e

protected java.lang.Exception e
Embedded exception, if any


codes

protected java.util.ArrayList codes
Collection of status codes (QNames)


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


config

protected SAMLConfig config
OpenSAML configuration

Constructor Detail

SAMLException

protected SAMLException(org.w3c.dom.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(java.lang.String msg)
Creates a new SAMLException

Parameters:
msg - The detail message

SAMLException

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

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

SAMLException

public SAMLException(java.util.Collection codes)
Creates a new SAMLException

Parameters:
codes - A collection of QNames

SAMLException

public SAMLException(java.util.Collection codes,
                     java.lang.String msg)
Creates a new SAMLException

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

SAMLException

public SAMLException(java.util.Collection codes,
                     java.lang.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(java.util.Collection codes,
                     java.lang.String msg,
                     java.lang.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(QName code)
Creates a new SAMLException

Parameters:
code - A status code

SAMLException

public SAMLException(QName code,
                     java.lang.String msg)
Creates a new SAMLException

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

SAMLException

public SAMLException(QName code,
                     java.lang.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(QName code,
                     java.lang.String msg,
                     java.lang.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(org.w3c.dom.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(java.io.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

fromDOM

public void fromDOM(org.w3c.dom.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(java.io.OutputStream out)
              throws java.io.IOException,
                     SAMLException
Serializes the XML representation of a SAML Status 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 invalid

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

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

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

getCodes

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

Returns:
An iterator of QNames

getMessage

public java.lang.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.

Returns:
The error message

getException

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

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

toString

public java.lang.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.

Returns:
A string (but not XML) representation of this exception

clone

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

Returns:
The new object
Throws:
java.lang.CloneNotSupportedException
See Also:
Object.clone()


Copyright ? 2002 UCAID. All Rights Reserved.