Working with Exceptions

Catching an EngineRuntimeException

An example of catching an EngineRuntimeException or standard Java™ exception follows:

Java Example

Document doc2 = Factory.Document.createInstance(os, null);
doc2.checkin(null, null);
doc2.save(RefreshMode.NO_REFRESH);
           
try
{
    doc2 = Factory.Document.fetchInstance(os, (doc2.get_Id()), null);
    doc2.getProperties().putValue("DocumentTitle", "doc2");
}
catch (Exception ex) 
{   
    if (ex instanceof EngineRuntimeException) 
    {
        EngineRuntimeException fnEx = (EngineRuntimeException) ex;
        if (fnEx.getExceptionCode().equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
        {
            doc2.save(RefreshMode.REFRESH);
            doc2 = Factory.Document.fetchInstance(os, (doc2.get_Id()), null);
            doc2.getProperties().putValue("DocumentTitle", "doc2");
        }
        else
            // Do something...printed here for simplicity.
            System.out.println("Exception: " + ex.getMessage());
    }
    else
        // A standard Java exception.
        throw ex;
}

C# Example

IDocument doc2 = Factory.Document.CreateInstance(os, null);
doc2.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc2.Save(RefreshMode.NO_REFRESH);

try
{
    doc2 = Factory.Document.FetchInstance(os, doc2.Id.ToString(), null);
    doc2.Properties.GetProperty("DocumentTitle").SetObjectValue("doc2");
}
catch (System.Exception ex)
{
    if (ex is EngineRuntimeException)
    {
        EngineRuntimeException fnEx = (EngineRuntimeException)ex;
        if (fnEx.GetExceptionCode().Equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
        {
            doc2.Save(RefreshMode.REFRESH);
            doc2 = Factory.Document.FetchInstance(os, doc2.Id.ToString(), null);
            doc2.Properties.GetProperty("DocumentTitle").SetObjectValue("doc2");
        }
        else
            // Do something.... printed here for simplicity.
            System.Console.WriteLine("Exception: " + ex.Message);
    }
    else
        // Standard C# exception
        throw ex;
}        

Interpreting an Exception Code

An exception code consists of a resource key and the associated exception message text. Assuming that you have an EngineRuntimeException instance, you can use EngineRuntimeException.getExceptionCode to get the resource key and message text.

The prefix for the exception code key (the initial characters preceding the first "_" (underline character) indicates the subsystem in which the exception originated. Use EngineRuntimeException.getMessage to get the associated message text.

The following code fragments illustrate potential uses:

Java Example (Exception Code)

// Use EngineRuntimeException.getErrorCode to perform further processing based on the 
// exception thrown.
Document doc1 = Factory.Document.createInstance(os, null);
doc1.checkin(null, null);
doc1.save(RefreshMode.NO_REFRESH);

try
{
    doc1 = Factory.Document.fetchInstance(os, (doc1.get_Id()), null);
}            
catch (EngineRuntimeException ex) 
{   
    if (ex.getExceptionCode().equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
    {
        // Do something...printed here for simplicity.
        System.out.println("Exception: " + ex.getMessage());
    }
}

// The resulting exception: "Exception: Property Id not found in properties 
// collection."

C# Example (Exception Code)

// Use EngineRuntimeException.getErrorCode to perform further processing based on the 
// exception thrown.
IDocument doc1 = Factory.Document.CreateInstance(os, null);
doc1.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc1.Save(RefreshMode.NO_REFRESH);

try
{
    doc1 = Factory.Document.FetchInstance(os, doc1.Id.ToString(), null);
}            
catch (EngineRuntimeException ex)
{
    if (ex.GetExceptionCode().Equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
    // Do Something... printed here for simplicity.
    System.Console.WriteLine("Exception: " + ex.Message);
}
// The resulting exception: "Exception: Property Id not found in properties 
// collection."

Java Example (Exception String)

// Use EngineRuntimeException.toString to return all of the exception information, 
// including the localized message.
try
{
    // ... code ...
}
catch (EngineRuntimeException ex) 
{   
    if (ex.getExceptionCode().equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
    {
        // Do something...printed here for simplicity.
        System.out.println(ex.toString());
    }
}

// The resulting exception (default locale):  
// "com.filenet.api.exception.EngineRuntimeException: API_PROPERTY_NOT_IN_CACHE: 
// Property Id not found in properties collection."    

C# Example (Exception String)

// Use EngineRuntimeException.toString to return all of the exception information, 
// including the localized message.
try
{
    // ... code ...
}
catch (EngineRuntimeException ex)
{
    if (ex.GetExceptionCode().Equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
    // Do Something... printed here for simplicity.
    System.Console.WriteLine(ex.ToString());
}

Java Example (Exception Message)

// Use either EngineRuntimeException.getMessage or 
// EngineRuntimeException.getLocalizedMessage, as required, to get only the localized 
// exception message. (These two methods differ only in the java.lang.Throwable method 
// they override.)
try
{
    // ... code ...
}
catch (EngineRuntimeException ex) 
{   
    if (ex.getExceptionCode().equals(ExceptionCode.API_PROPERTY_NOT_IN_CACHE))
    {
        // Do something...printed here for simplicity.
        System.out.println(ex.getLocalizedMessage());
    }
}

// The resulting exception (default locale): "Property Id not found in properties 
// collection."

Note: The Content Engine .NET API does not support the EngineRuntimeException.getMessage or EngineRuntimeException.getLocalizedMessage methods.

Interpreting the Error Stack

The information for the EngineRuntimeException instance thrown will always be at the top of the stack. For example, the following:

Java Example

try
{
    Document doc1 = Factory.Document.fetchInstance(os, new Id("{F905DBD6-5A69-4252-9985-2D3DD28D7FBA}"), null);
}            
catch (Throwable e) 
{   
    throw new EngineRuntimeException(e, ExceptionCode.CONTENT_FCP_DOC_EXISTS_FAILED, null);
}

C# Example

try
{
    IDocument doc1 = Factory.Document.FetchInstance(os, new Id("{239B418A-386B-4FF4-9812-EC8A157CDDA1}"), null);
}
catch (System.Exception e)
{
    throw new EngineRuntimeException(e, ExceptionCode.CONTENT_FCP_DOC_EXISTS_FAILED, null);
}

might generate a returned stack similar to this:

    Failed to determine whether document exists.
    com.filenet.api.exception.EngineRuntimeException: CONTENT_FCP_DOC_EXISTS_FAILED: Failed to determine whether document exists.
        at testbase.daphne.MainCases$Case1.run(MainCases.java:84)
        at testbase.daphne.CaseRunner.runTestCase(CaseRunner.java:123)
        at testbase.daphne.CaseRunner.runTestCase(CaseRunner.java:92)
        at testbase.daphne.CaseRunner.runCase(CaseRunner.java:59)
        at testbase.daphne.MainCases.run(MainCases.java:59)
        at java.security.AccessController.doPrivileged(Native Method)
        at javax.security.auth.Subject.doAs(Subject.java:320)
        at testbase.daphne.WebServer.executeAction(WebServer.java:56)
        at testbase.daphne.CaseRunner.runAction(CaseRunner.java:48)
        at testbase.daphne.MainCases.<init>(MainCases.java:37)
        at testbase.daphne.MainCases.main(MainCases.java:45)
    Caused by: java.lang.Throwable: Requested item not found.

Throwing an EngineRuntimeException

To throw an EngineRuntimeException, use the appropriate constructor to create the EngineRuntimeException instance:

Java Example (Unchained Exception)

// Use the constructor EngineRuntimeException(ExceptionCode code) or, to specify the 
// parameter values, EngineRuntimeException(ExceptionCode code, java.lang.Object[] 
// codeArgs) to throw an unchained exception. The following fragment checks the status of 
// the current page for page iteration (PageIterator class).
//
// Note: The BEFORE_FIRST and AFTER_LAST values are example 
// static variables assumed to have been declared in statements 
// preceding this fragment.
    	  	
if (state == BEFORE_FIRST)
{
    throw new EngineRuntimeException(ExceptionCode.API_BEFORE_FIRST_PAGE_ELEMENT);
}
else if (state == AFTER_LAST)
{
    throw new EngineRuntimeException(ExceptionCode.API_AFTER_LAST_PAGE_ELEMENT);
}
else if (currentPage == null)
{
    throw new EngineRuntimeException(ExceptionCode.API_BEFORE_NEXT_PAGE_ELEMENT);
}

Java Example (Chained Exception)

// Use the constructor EngineRuntimeException(ExceptionCode code) to throw a chained 
// exception for a given exception code.
Document doc1 = Factory.Document.createInstance(os, null);
doc1.checkin(null, null);
doc1.save(RefreshMode.NO_REFRESH);
doc1.getProperties().putValue("DocumentTitle", "doc1");
        
try
{
    doc1 = Factory.Document.fetchInstance(os, (doc1.get_Id()), null);
}                
catch (EngineRuntimeException ex) 
{   
    if (ex.getExceptionCode().equals(ExceptionCode.API_NO_CONTENT_ELEMENTS))
    {
        doc1.getProperties().putValue("DocumentTitle", "doc1");
        doc1.save(RefreshMode.NO_REFRESH);
    }
    else
    {
        // Chain the exception, then do something...printed here for simplicity.
        EngineRuntimeException thrown = new EngineRuntimeException(ex, ExceptionCode.CONTENT_FCP_CE_ALREADY_EXISTS, null);
        System.out.println("Exception: " + thrown.getMessage());
        throw thrown;
    }
}

// The resulting exception: "Exception: Content element create failed, a content 
// element with the name {0} already exists."
// Note that the name of the content element was unspecified. To correct this, use the 
// constructor EngineRuntimeException(ExceptionCode code, java.lang.Object codeArg0).        

C# Example (Chained Exception)

// Use the constructor EngineRuntimeException(ExceptionCode code) to throw a chained 
// exception for a given exception code.
IDocument doc1 = Factory.Document.CreateInstance(os, null);
doc1.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
doc1.Save(RefreshMode.NO_REFRESH);
doc1.Properties.GetProperty("DocumentTitle").SetObjectValue("doc1");

try
{
    doc1 = Factory.Document.FetchInstance(os, doc1.Id.ToString(), null);
}        
catch (EngineRuntimeException ex)
{
    if (ex.GetExceptionCode().Equals(ExceptionCode.API_NO_CONTENT_ELEMENTS))
    {
        doc1.Properties.GetProperty("DocumentTitle").SetObjectValue("doc1");
        doc1.Save(RefreshMode.NO_REFRESH);
    }
    else
    {
        // Chain the exception, then do something ... printed here for simplicity.
        EngineRuntimeException thrown = new EngineRuntimeException(ex, ExceptionCode.CONTENT_FCP_CE_ALREADY_EXISTS, null);
        System.Console.WriteLine("Exception: " + thrown.Message);
        throw thrown;
    }
}

// The resulting exception: "Exception: Content element create failed, a content 
// element with the name {0} already exists."
// Note that the name of the content element was unspecified. To correct this, use the 
// constructor EngineRuntimeException(ExceptionCode code, java.lang.Object codeArg0).

Java Example (Chained Exception with Specified Parameter)

// Use the constructor EngineRuntimeException(ExceptionCode code, java.lang.Object 
// codeArg0) to throw a chained exception for a given exception code and specify the 
// parameter in use when the exception occurred. When multiple parameters are specified, 
// use the constructor EngineRuntimeException(ExceptionCode code, java.lang.Object[] 
// codeArgs).
try
{
    // ... code ...
}
catch (EngineRuntimeException ex) 
{   
    if (ex.getExceptionCode().equals(ExceptionCode.API_NO_CONTENT_ELEMENTS))
    {
        doc1.getProperties().putValue("DocumentTitle", "doc1");
        doc1.save(RefreshMode.NO_REFRESH);
    }
    else
    {
        // Do something...printed here for simplicity.
        Object[ ] title_arg = new Object[ ] {doc1.getProperties().getStringValue("DocumentTitle")};
        EngineRuntimeException thrown = new EngineRuntimeException(ex, ExceptionCode.CONTENT_FCP_CE_ALREADY_EXISTS, title_arg);
        System.out.println("Exception: " + thrown.getMessage());
        throw thrown;
    }
}

// The resulting exception: "Exception: Content element create failed, a content 
// element with the name doc1 already exists."

C# Example (Chained Exception with Specified Parameter)

// Use the constructor EngineRuntimeException(ExceptionCode code, object codeArg0) 
// to throw a chained exception for a given exception code and specify the 
// parameter in use when the exception occurred. When multiple parameters are specified, 
// use the constructor EngineRuntimeException(ExceptionCode code, object[] codeArgs).
catch (EngineRuntimeException ex)
{
    if (ex.GetExceptionCode().Equals(ExceptionCode.API_NO_CONTENT_ELEMENTS))
    {
        doc1.Properties.GetProperty("DocumentTitle").SetObjectValue("doc1");
        doc1.Save(RefreshMode.NO_REFRESH);
    }
    else
    {
        // Do something ... printed here for simplicity.
        Object[] title_arg = new Object[] { doc1.Properties.GetStringValue("DocumentTitle") };
        EngineRuntimeException thrown = new EngineRuntimeException(ex, ExceptionCode.CONTENT_FCP_CE_ALREADY_EXISTS, title_arg);
        System.Console.WriteLine("Exception: " + thrown.Message);
        throw thrown;
    }
}

// The resulting exception: "Exception: Content element create failed, a content 
// element with the name doc1 already exists."