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 that precede the first underline character ("_")) indicates the subsystem in which the exception originated. Use EngineRuntimeException.getMessage to get the associated message text.

The following code snippets 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 locale-specific 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 locale-specific 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 locale-specific 
// 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."