XmlBlaster Logo

REQUIREMENT

admin.errorcodes

XmlBlaster Logo


Type NEW
Priority LOW
Status CLOSED
Topic XmlBlaster supports well defined error codes
Des
cription

XmlBlaster throws only one exception namely the XmlBlasterException. To distinguish the errors, xmlBlaster supports an hierarchical error code schema.

The following drawing illustrates some exception situations:


Example for xmlBlaster exceptions

We support a set of top level error code categories:

errorCodeDescription
internal Internal errors which are caused by programming errors like null-pointer, illegal arguments and other bugs. If such an error occurs you should report it to the xmlBlaster mailing list.
resource XmlBlaster uses many local resources like hard disk space, RAM and reading or writing files. If resources exhaust, or access to local resources is not possible or if the configuration of those resources is wrong this can usually be solved by the server administrator or deployer of xmlBlaster.
Some typical members of this category are outOfMemory, ioException, fileNotFound and more.
communication The communication layer to clients or other xmlBlaster cluster nodes is an important part of xmlBlaster. We could categorize them into the resource category as typical IO exceptions, but we keep them separate here to manifest the importance for the MoM.
user User errors are exceptions when clients access xmlBlaster in an illegal way. For example trying to login with a wrong password or sending a message with a corrupted XML-message key syntax will be reported by a user exception.
transaction This is not specified yet.
legacy Old style xmlBlaster exceptions are marked as legacy until they are ported to this new behaviour.

Examples for the error codes errorCode:

errorCodeDescription
internalServer internal problems
internal.unknownServer internal problems which are not known
internal.nullpointerCoding error (blame maintainers)
internal.illegalArgumentCoding error
......
resourceProblems with resources on server hardware or configuration
resource.outOfMemoryNo more memory, increase RAM or java -Xmx option
resource.exhaustA resource of your system exhausted
resource.configuration.pluginFailedYour configuration (e.g. in xmlBlaster.properties) is invalid
......
communicationProblems with client server communication
communication.noconnection.pollingWe have currently no remote connection but are polling for it
communication.noconnection.deadThe remote connection is dead and it is not possible to recover
......
userErrors caused by wrong usage
user.security.authentication.accessDeniedYour login failed
user.security.authorization.notAuthorizedYour message was not accepted
user.publish.qosIllegal syntax in your QoS
user.publish.qos.destinationMessage not delivered as destination is illegal
user.publish.keyYour key has illegal syntax
user.publish.key.oidSuch an oid is not accepted
user.publish.maxSizeThe message sent is too big
......
transactionTodo

An XmlBlasterException contains a set of attributes describing an exception, all of type String:

  • {0} errorCode: The hierarchical error code (e.g. "security.notauthenticated")
  • {1} node: Cluster node location (e.g. /node/heron)
  • {2} location: Logical location in the code (e.g. client/joe/3-SubscriptionInfo)
  • {3} isServerSide: Marks the origin of the exception, if originally is thrown on server or client side
  • {4} message: The human readable error text (e.g. "Authorization denied for message oid 'accountRetrieval'")
  • {5} versionInfo: Information like xmlBlaster version, OS name, Java version etc.
    (e.g. "version=0.81,os.name=Linux,java.version=1.4.1-rc, build.java.vendor=IBM,build.java.version=1.3.1, build.timestamp=06/17/2002 01:59 PM")
  • {6} timestamp: Timestamp when exception was thrown (e.g. 2002-02-10 11:57:51.804000001)
  • {7} stackTrace: The stack trace (optional, for debugging)
  • {8} embeddedMessage: The original exception message (optional, if another exception is re-thrown)
  • {9} errorCode.getUrl(): The online URL describing the problem

Examples for location:

locationDescription
/node/heron/client/joe/3A specific user session
/node/heron/plugin/emailEmail protocol problems
......

All ID's could be made available in a java.util.ResourceBundle, the client or server can display a localized text for the errorCode in this case.

Example
XML 

An xml representation is

XmlBlasterException.toXml():
============================

 <exception id='user.publish.qos'>

    <errorCode>
       <user>
          <publish>
             <qos/>
          </publish>
       </user>
    </errorCode>

    <location>
       <node>
           <heron>
             <client>
                <joe/>
             </client>
           </heron>
       </node>
    </location>

    <message><![CDATA[Invalid publish]]></message>

    <stackTrace/>

 </exception>
Example
JAVA 

// Example showing how to convert an Exception (as a server developer)
import org.xmlBlaster.util.XmlBlasterException;
import org.xmlBlaster.util.def.ErrorCode;

try {

   ... // Throws exceptions 

}
catch (CorbaException ex) {

   throw new XmlBlasterException(glob,
                  ErrorCode.COMMUNICATION_NOCONNECTION_POLLING,
                  this.getClass().getName(),
                  "No callback connection to client joe",
                  ex);

}
Example
JAVA 

//=====================================================================
// Example showing usage by a client

try {

   ... // Throws exceptions 

}
catch (XmlBlasterException ex) {

   // Display full stack trace for internal exceptions
   // and moderate information for user exceptions with getMessage():

   log4j.error(ex.getMessage());
}
//=====================================================================


//=====================================================================
// For user exceptions the output could look like this:
errorCode=[user.configuration]
node=[xmlBlaster]
location=[ConnectionsHandler-client:client/joe]
message=[Please provide a public session ID]
//=====================================================================


//=====================================================================
// For internal exceptions the output could look like this:
node=[xmlBlaster]
location=[XmlBlasterAccess-client/joe]
java.lang.NullPointerException: 

stackTrace=java.lang.NullPointerException: 
        at org.xmlBlaster.client.XmlBlasterAccess.connect(XmlBlasterAccess.java:181)
        at HelloWorld2(HelloWorld2.java:28)
        at HelloWorld2.main(HelloWorld2.java:76)
errorCode=internal.nullpointer message=Connection failed
        at org.xmlBlaster.util.XmlBlasterException.convert(XmlBlasterException.java:551)
        at org.xmlBlaster.util.XmlBlasterException.convert(XmlBlasterException.java:540)
        at org.xmlBlaster.client.XmlBlasterAccess.connect(XmlBlasterAccess.java:211)
        at HelloWorld2(HelloWorld2.java:28)
        at HelloWorld2.main(HelloWorld2.java:76)

versionInfo=version=0.844,os.name=Linux,os.version=2.4.19-4GB,
java.vm.vendor=IBM Corporation,java.vm.version=1.4.0,os.arch=x86,
build.timestamp=03/24/2003 11:46 PM,
build.java.vendor=IBM Corporation,build.java.version=1.4.0

errorCode description=A null pointer is an xmlBlaster internal programming error,
                      please post it to the mailing list.
//=====================================================================
Configure

These parameters allow to configure the dispatch plugin.

Property Default Description Impl
XmlBlasterException.logFormat errorCode=[{0}] serverSideException={3} node=[{1}] message=[{4} {8}] Allows to format the returned exception text when exception.getMessage() is invoked. See the meaning of the numbers in the above description, e.g. {0} is a place holder for the errorCode and {5} for versionInfo.

The left example would result in a logging output like:

errorCode=[resource.overflow.queue.bytes] node=[/node/heron] message=[Bla bla ] 		yes
XmlBlasterException.logFormat.internal Dumps extended informations including the stack trace Allows to format the returned exception text when exception.getMessage() is invoked specifically for internal exceptions. yes
XmlBlasterException.logFormat.resource defaults to XmlBlasterException.logFormat Allows to format the returned exception text when exception.getMessage() is invoked specifically for resource exceptions. yes
XmlBlasterException.logFormat.communication defaults to XmlBlasterException.logFormat Allows to format the returned exception text when exception.getMessage() is invoked specifically for communication exceptions. yes
XmlBlasterException.logFormat.user defaults to XmlBlasterException.logFormat Allows to format the returned exception text when exception.getMessage() is invoked specifically for user exceptions. yes
XmlBlasterException.logFormat.transaction defaults to XmlBlasterException.logFormat Allows to format the returned exception text when exception.getMessage() is invoked specifically for transaction exceptions. yes
XmlBlasterException.logFormat.legacy defaults to XmlBlasterException.logFormat Allows to format the returned exception text when exception.getMessage() is invoked specifically for legacy exceptions. yes

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

Todo
See REQ admin.errorcodes.listing
See API org.xmlBlaster.util.def.ErrorCode
See API org.xmlBlaster.util.XmlBlasterException

This page is generated from the requirement XML file xmlBlaster/doc/requirements/admin.errorcodes.xml

Back to overview