Examples

The following example is a minimal <try>/<catch> block that executes an invalid SQL query inside <try> and catches any exception.

The <catch> block handles any exception thrown by the <sql> statement because EMMLException is the Default EMML Exception Class for any EMML statement. The exception is assigned to the default variable exception.

Note: You can also provide your own variable name to use for the exception. In <catch EMMMMLException e"> the variable for the exception will be $e.

The <display> statement in <catch> uses the default variable $exception to include the entire exception in the message.

Depending on the source of the exception, exceptions may be simple strings or well-formed XML documents most commonly in one of these forms:

<exception-class-name>
<errorcode>nnnn</errorcode>
<message>description of the exception</message>
</exception-class-name>

<exception-class-name>
<message>description of the exception</message>
</exception-class-name>

<exception-class-name>description of the exception</exception-class-name>

But other forms occur based on the context of the exception. For example, exceptions thrown by WSDL mashables follow SOAP standards.

In some cases, you may want to throw a different exception from a <catch> block to provide other information or a user-friendly error message. This uses the <throw> statement, literal XML and a dynamic mashup expression to represent the exception. For example:

Unless this <try> block also contains <catch type="XsltTransformException">, this new exception will be thrown by the mashup and processing stops if the <xslt> statement fails to complete the transformation.

This exception provides both a more specific exception name and some additional context that can help track down the error, such as the organization and mashup name in the context attribute. As well, the message itself is more user friendly that the original Java exception.

With some exceptions, you want to stop further mashup or macro processing but still return a result. You can do this with the <return> statement. For example:

...
<output name="result" type="document"/>
...
<foreach variable="member" items="$selectedMembers//member/name">
<try>
<variable name="newList" type="string"/>
<macro:addToFormattedList list="$partial" newItem="$member"
outputvariable="newList"/>
<catch type="NoNewListItem e">

<constructor outputvariable="$result">
<members>{$partial}</members>
</constructor>
<return/>
</catch>
</try>
</foreach>
...
</mashup>

This example calls a macro in the <try> block to assemble a formatted list of member names. If the macro throws a custom exception named NoNewListItem, because the member name that was passed was empty, the <catch> block constructs a result for the mashup using the partial formatted list already assembled and calls <return/> to stop processing and return this partial list.

When mashups invoke other mashups or call macros, exceptions can propagate up through each level of mashup or macro until they are caught. For example:

The exception thrown in this example by Macro C propagates up the call stack (through Mashup B) to Mashup A where it is finally caught.

You identify what exceptions each <catch> block will handle in the type attribute with an exception class name. The name can be either:

...
<try>
...
<catch type="SQLException e">

</catch>
<catch type="java.net.ConnectException e">

</catch>
<catch type="emmlexception e">

</catch>
</try>
...

With multiple <catch> blocks, the order of <catch> blocks does not determine which block handles a given exception. Instead, exceptions are handled by the <catch> block with the exception name that is the most specific match.

The potential exception classes that can be thrown in a <try> block depend on the context of the exception:

For <directinvoke> within a <try> block, the onerror attribute affects how exceptions are treated. If onerror="continue" within <try>, all <catch> blocks are ignored. The exception is handled just as it is when <directinvoke> with onerror="continue" is outside a <try> block. See Lightweight Error Handling for Component Mashups and Mashables for more information.

If onerror is not included or onerror="abort" is used, then you can specify one of the following EMML exception classes or use the Default EMML Exception Class. These EMML exception classes are used for responses from the endpoint based on the HTTP status code and the content of the response:

restexception is used for responses from REST web services, syndicated web feeds or web sites (HTML) when the HTTP status code is in the 300s, 400s or 500s. For example:

...
<try>
<directinvoke endpoint="http://localhost/foo302.php"
outputvariable="result" followredirects="false"
responseheader="$responseHeader" responsecode="$responseCode"/>
<catch type="restexception e">
<if condition="$responseCode >= 500">
<display message="caught restException 5xxx" />
<elseif condition="$responseCode >= 400">
<display message="caught restException 4xxx" />
</elseif>
<elseif condition="$responseCode >= 300">
<display message="caught restException 3xxx" />
</elseif>
</if>
</catch>
</try>
...

soapexception is used for responses from WSDL web services when the response has an HTTP 500 status code and the response contains a SOAP fault for SOAP 1.1 or 1.2.

Note: If the response contains a SOAP fault, but does not use the HTTP 500 status code, this is not considered a SOAP exception (per the Web Service standard).

...
<try>
<directinvoke endpoint="http://localhost/soapfault1.php"
outputvariable="result1" />
<catch type="soapexception se">
<display message="caught soapException=" expr="$se//*:Fault"/>
<display message="soapException Value =" expr="$se//*:Value/string()"/>
</catch>
</try>
...

For <invoke> within a <try> block, the onerror attribute affects how exceptions are treated. If onerror="continue" within <try>, all <catch> blocks are ignored. The exception is handled just as it is when <invoke> with onerror="continue" is outside a <try> block. See Lightweight Error Handling for Component Mashups and Mashables for more information.

If onerror is not included or onerror="abort" is used, you can use the JBPException class or use the Default EMML Exception Class.

In most cases, it is a best practice to handle exceptions from <script> within the scripting code itself. If this is not possible, the potential exception classes for <script> depend on the scripting language in use:

JavaScript	RhinoException or org.mozilla.javascript.RhinoException for scripts in JavaScript.
Groovy	GroovyRuntimeException or groovy.lang.GroovyRuntimeException or any subclass for scripts in Groovy. See http://groovy.codehaus.org/api/groovy/lang/GroovyRuntimeException.html for a complete list.

For other EMML statements, you must specify a specific Java exception or use the Default EMML Exception Class. Some of the most common exceptions include:

<sql>, <sqlUpdate> or <sqlcall>	java.sql.* exceptions for the <sql>, <sqlUpdate> or <sqlcall> statements.
<xslt>	javax.xml.transform.* exceptions or net.sf.saxon.* exceptions for the <xslt> statement.
XPath errors for any statement	XPathException, XPathExpressionException or XPathFunctionException for XPath errors from any EMML statement.
Parser errors	For syntax errors.

The default exception class for all EMML statements is EMMLException or org.oma.emml.me.commons.EMMLException. It is always the least specific match to an exception. Most commonly, you use this to catch any exceptions not caught by other <catch> blocks. See A Basic <try>/<catch> Block for an example.