OSB Coding Standards

    OSB follows a set of standards to enhance functionality and increase readability. They can
    be broadly categorized into following:
    

Naming Conventions for Project Structure

·         Naming conventions for the folders

Naming standards for different folders in the entire folder structure must follow a consistent and readable approach.

Example:

·         Naming conventions for WSDL/Schema documents included

The WSDL should always be named by the name of the service.

Example: For Customer Service WSDL name should be Customer.wsdl

Naming conventions for security resources like policy files and service accounts

For security resources also, naming conventions must be followed.

Example:

For WSSE policy file, ‘WSSE’ should be prefixed with the name of the file.

For a service account to call a particular provider, it should be named after   the provider name. Like for Customer provider, its service account should be named as CustomerServiceAccount.

Naming conventions for Proxy services, Business services, End points, Categories and Actions

Proxy services should also follow a naming pattern to make them self-explanatory of their functionality.

Proxy Service:

Every proxy service should start with the PS_ prefix, followed by the functional name and ends with a version and release number.
Syntax: PS_<functional-name>_v1r0

Business Service:

Every business service should start with the BS_ prefix, followed by the functional name and ends with a version and release number.
Syntax: BS_<functional-name>_v1r0

End points:

The end point of the proxy service should be changed to
Syntax: /<category>/PS_<functional-name>_v1r0

Categories:

Discover all the services that need to be implement for OSB. Catalog the services in a category. This category is used as OSB project to collect the proxy services and business services etc.

There is one special category called common.
The structure of a category is as follows:

Example:

<category>/BusinessService
<category>/ProxyService
<category>/Schema
<category>/Transformation
<category>/Wsdl

<category>/Utility/Jar

<category>/Security/ServiceAccount

<category>/JCA 

Common Objects:

Objects such as XSD files, XQuery’s, XSLT etc... That are used in more than one proxy / business services are stored in the common category.

Actions:

In OSB actions are executed in the message flow of the proxy service. Each action has a default name. Name each action in the following format.

Syntax: <action>_<function_name>

Example:

· Assign_saveBody

· Replace_tranform2OrderMessage

·         Naming conventions for transformation resources like XQuery’s

The XQuery’s, like any other resource, also follow a naming pattern. As XQuery is a transformation resource, its name should be prefixed with keyword ‘transform’.

Syntax: 
Request XQuery:   transform<Operation Name>Request

Response XQuery: transform<Operation Name>Response

Example: 
transformSearchByOrderNumberRequest,
transformSearchByOrderNumberResponse

·         Naming conventions for pipeline pair

Pipeline pair should be named after the name of the operation the pipeline belongs to.

Syntax:    <Service Name>Pipeline

Example: OrderServicePipeline

·       Naming conventions for branch nodes where conditional branching is incorporated

Wherever branching needs to be done based on a certain condition, it is suggested to use conditional branching in that case. And while implementing the conditional branch, branches thus created must be named appropriately.

Syntax:    <Operation Name>

Example: SearchByOrderNumber

·         No unused resources in the project

It is a best practice not to have any unused or unreferenced resource in the project folder structure.

Better Readability

@Comments to be present at various places like at stage level, in case of special logic or for service callouts to the provider services etc. for better readability.

 

Validation

Different kind of validations can be implemented in OSB to ensure the correctness of request and response structures.

·         Schema Validation

To confirm that the incoming request is in accordance with the schemas of the service, schema validation is performed.

Validate option is used to validate an incoming request against the schema.

Example:

 

·         
Custom Validation

Apart from schema validation, there can be validations that we want to enable as per the requirement of the code and functionality.

  

Logging

Logging is an integral part of the message flows in OSB. Logs enable easy debugging of errors, structures of request and responses being transformed internally. Logging can be done either by OSB logs or can be done by a separate service by using an EJB etc. Using different levels of logging exposed by OSB, we can differentiate the logs based on success and error scenarios.

In case of logging, there is again a certain set of standards which if followed, can increase the effectiveness of the logging procedure.

·         Logging should be implemented at all checkpoints

·         No alert statements should be left in the flow

Reason: Alert statements are used to track the value of a particular variable or to track the direction of flow. These statements are helpful during coding and testing phases but it is suggested not to have any alert statement in the final code version.

·   The Operational settings of all proxy and business services must be properly configured

Operational settings are important to enable logging from OSB. In case the OSB logs are implemented, enabling logging in operational settings is a mandate.

Example:

·         The log statements should be sufficient to track a log end to end

      Note: Once Testing is done disable or delete all log actions.

  

Error Handling

Error handling is one of the most important features to ensure an efficient and capable OSB code. For any implementation to be successful, it important to have all the error scenarios handled in an efficient manner. Like any success response, error responses are equally important. Now when errors are already an integral part of any implementation, OSB also provides various methods to enable this functionality in the flows.

The basic standards which should be followed to make error handling all the way more effective are:

·         Schema Errors

At places where schema validations are performed, stage error handlers should be implemented appropriately to handle the responses in case the system throws a schema non-compliance error.

 Each stage in a request or response pipeline can have a separate error handling pipeline. If you design your pipeline with multiple stages, you can avoid writing a single error handler that must handle all errors by all actions in a single stage.

Error handlers for all Operations has to be provided in the Message flow of the Proxy services

·         Service Error Handler

Always configure the service-level error handler. For non-SOAP services the built-in error handler only returns a transport error code since there is no standard error response document like a SOAP fault that it can auto generate.

Example:

 

·             If you use the resume action (in an error handler) or the skip action, the behaviour is to resume processing at the next stage in the request or response pipeline. Therefore, depending on the logic you want to enforce, it can be a good design principle to put actions subsequent to a resume or skip action in subsequent stages.

·         Publish to best effort

While publishing, error handlers should be implemented just like service callouts. But in case publish to best effort is used, no error handlers are to be used as it is over HTTP and is fire and forget in nature. In this case, response is not sent back by OSB hence no need of error handler to handle the error response.

For all synchronous protocol services, Read time-out and Connection time-out should be set, which ensures that the transaction time-out after configured time if the target system is down. This would ensure that the calling systems does not wait for a very long time.

For one way service, Retry Count and Retry Iteration Interval should be set, so that the process automatically retries for certain number of times if target system is down.