Logging and Error Handling for the MealOrderService

When building "real" code it is important to consider how users, or other developers on your team, will be able to support it, including troubleshoot problems that arise. We have already used the Manage Processes screen to see what is happening in business processes. When writing custom code, as we have in the Meal Program Library, you have all the standard ways of tracing and debugging the code using standard tools. 

Debugging

If your instance allows remote connections, you can use your IDE to connect to your instance, place breakpoints, single-step through code, as described in the documentation. Note: most cloud-based development sandboxes currently do not allow these connections.

Error Handling

In many cases, when errors occur it is best handled by catching an exception in the form of the RxException class. If iit is indicating an error on the server, by default it will be propagated back to the client, and will be logged in the relevant service log, such as process.log  that is accessible in the same fashion as your own custom logs.

You may want to do some special handling of errors. You can actually implement a custom class that extends RxException.  In the sample code, you can see this in the class MealOrderException.  In this class, we do several things:

• We extend RxException, the exception thrown by the framework itself.   This causes it to be properly communicated back to the client.
• Define our own constants for the different situations.  We have elected to use a Java enum here called MealOrderMessage, but we could have used static final int constants as well.
• Because RxException uses integer error codes, we need to provide a constructor for MealOrderMessage that converts from int, and an IntValue() method to convert the other way. Note: this code uses underscore characters in the numeric literals for readability, as in 600_100 for 600100 - this may look strange, but the underscores are ignored by the compiler and this is perfectly valid Java code.
• We need to overload at least one of the constructors for RxException. For a simple message with appended text, that wraps the original Exception, we use that particular constructor.
• We pass the bundle-id to the framework so it can handle messages from different bundles properly.
  
  

You will note that there is no text provided for the error codes. That is because text must be provided in the localizable properties file for this bundle, found in src/main/resources/localized-strings.properties.

In order to test this, as a developer, it is not enough to simply but the strings in this file. You will also need to run the "localization" maven profile at least once.  This causes these strings to be loaded into the string catalog of BMC Helix Platform.

 Here's an example where we wrap an RxException into a MealOrderException with our own error message. This code also logs a different message directly into the configured log for this bundle.

This can be tested by invoking Get Order Info using an invalid Order ID.

Logging

As you may have noticed in the previous snippet, it is also possible to log various events at various levels. The Logging Service provides a uniform way to format filterable information into a configured server-side log file that can be managed and retrieved to trace through code execution. Your code can emit logging statements using the Logging Service. For example, note the  beginning of the MealOrderInfoDataPageQuery's execute() method:

To configure where this output goes, and the level of logging, find the com.example.meal-program-lib bundle configuration in the Administration tab of BMC Helix Innovation Studio.

Here's an example of testing and examining the log (and also shows the use of exception wrapping). Consider the following logging statements found in the cancelMealOrder() implementation.

Let's run this method to see the log output.

1. Create an Order - it will now be in Submitted state - and capture the ID using the Edit Data screen.
   
2. Using Postman to send the command:
   1. Be sure to include the default-bundle-scope header. Otherwise, logging will only occur in the context of a calling Application.
      
   2. Pass the ID of the Order as the required parameter of the command.
      
3. Use the Mid-Tier to retrieve the mealprogramlibrary.log file that was configured earlier.
   

4. You can see the trace statements appearing in the log.

   mealprogramlibrary.log - Snippet

   INFO START - cancelMealOrder(AGGA4D22JRZ70AOWLJ0BOVPAFKA09O)
   INFO previous status was: 0
   INFO cancelMealOrder updating status for AGGA4D22JRZ70AOWLJ0BOVPAFKA09O to Cancelled
   INFO END - cancelMealOrder(AGGA4D22JRZ70AOWLJ0BOVPAFKA09O)
5. Try a bad ID to test error handling:
   1. Change the body of the POST.
      
   2. Note the response shows the custom Exception text.
      

   3. The log shows both trace and error statements.

      mealprogramlibrary.log - Snippet

      INFO CancelMealOrderCommand called for meal order bad-id
      TRACE cancelMealOrder(bad-id)
      ERROR Cannot cancel - no such Order bad-id

Challenge

• Add your own logging, re-deploy the Library, and test it using Postman
• Add your own error handling:
  • Add a new constant to MealOrderMessage. 
  • Be sure to add English text for it in localized-strings.properties, and localize it using the -Plocalization command.
  • Throw it under some circumstance in your code.
  • Test it with Postman to be sure it returns the right error.

What Have you Learned

• To create maintainable code, make sure you are logging important events or adding appropriate tracing.
• The Logging Service can be used to send logs to a retrievable file, or to view messages in the Browser (for synchronous processes)
• You can extend RxException in order to wrap it with more meaningful error messages.

For more information, see Handling-exceptions.