Here are the guidelines and recommendations to design, develop, test, and deploy WSO2 integration solutions:
...
Creating a tooling project
- When you start WSO2
To create and manage artifacts, use WSO2 Enterprise Integrator Tooling.
- When you start WSO2 Enterprise Integrator Tooling, a default workspace is created to store your projects. Change the default workspace location to a preferred location that you can easily access. For information on how to change the default workspace, see Switching workspaces.
- Change the default location that your new project is created in your machine in the same way that you change the default workspace.
- Create a Maven Multi Module (MMM) project to group the projects of a specific use case.
- When you create the project structure, add it to source control such as SVN or Git.
- Use the source control command line tools to interact with files.
- When you create projects, ensure that you follow the standard Maven naming convention. For more information, see Naming Guidelines.
- When you define
groupid
,artifactid,
andversion
, ensure that you follow the proper naming convention. For example, you can specify a name such asorg.acme.integration.sampleesb-demo-project1.0.0
.
...
- When you create an artifact, use the proper naming convention from the start.
- If an ESB project contains many artifacts related to multiple use cases, name the artifacts by prefixing or post fixing the use case name.
- Create specific ESB projects for specific use cases. This makes it easy to manage the code/project.
- Design the ESB logic into highly cohesive and loosely coupled modules.
- Avoid creating large, complex mediation code as much as possible. Always follow the separation of concerns design principle and split lengthy logic into separate mediation components.
- When you have a common set of code, implement it in a sequence or a template that can be reused. For more information, see Sequence Template.
- Externalize endpoint and policy references using the Registry. For more information, see Managing ESB projects across environments.
- Hide sensitive information such as passwords in configuration files using Secure Vault.
...
Follow a standard file naming convention to improve the readability of the code. Naming conventions change depending on the programming language.
Given below is the naming convention for WSO2 source files:
Code Block <ProjectName>_<FileName>_<FileType>.<Extension> Example: Student_Student_Sequence.xml, Stocks_StockQuote_FileInbound.xml
You can use a general naming convention for other known source files. If applicable, you can use a class naming convention that includes the business domain so that it is self explanatory. For example,
BubbleSortMediator.java
. For more information on naming conventions, see the library article WSO2 Developer Studio - Development and Deployment Best Practices.
Using mediators
Using the Log mediator
In an ideal production environment where the server is running smoothly, log entries should not be written to the log file. However, if the server experiences problems, there should be sufficient entries written to the log file to understand the problem.
In the When a server encunters errors, you should have enough information about the errors in the logs.
To log mediated messages, the best option is to use the Log mediator.
In a production setup, it is not recommended to use the Log mediator within sequences and proxy services other than in the Fault sequences.
Using logs with information such as ERROR_CODE is generally useful to understand the issue.
Put the Log mediators within the Fault sequences, which capture information about errors.
In the development phase, you should use Log mediators in the message flow as checkpoints.
If you are using the Log mediator to track and troubleshoot the message flow, set the log category to
DEBUG
.If you are in a development environment, ensure that you set the global log level of
org.apache.synapse.mediators.builtin.LogMediator
toDEBUG
.If you are in a production environment, ensure that you set the global log level of
org.apache.synapse.mediators.builtin.LogMediator
to INFO. Setting the log level to INFO allows you to troubleshoot the message flow in production whenever required without having to go through the synapse configuration.You should use Log mediators in the
FaultSequence
to capture information about errors that occur. The logs entries printed via theFaultSequences
will be available in the wso2carbon.log that is in the main log file.
...
Insert excerpt | ||||||
---|---|---|---|---|---|---|
|
...
Using the
...
Clone mediator
When using a Clone mediator, use a Call mediator in the target sequence to bring the responses back into the In-Sequence. This continues the mediation since the Continuation Stack gets pushed into the Synapse Message Context via the handleMessage
method in the SynapseCallbackReceiver
class.
Otherwise, the Continuation Stack becomes empty in the Synapse Message Context if you do not use a Call mediator in the target sequence.
Using the Loopback mediator
Do not include the Loopback mediator in the OutSequence
.
Tip |
---|
When a message passes from the |
...
- You should not specify any mediator after the Send Mediator or the Respond Mediator .
A message flow must end from these two mediators. Here, the message flow does not mean the current sequence. If you have these two mediators in a sub-sequence that gets called from a parent sequence, then once the message returns from the sub-sequence to the parent, the parent sequence should not include any mediator after the call to the sub-sequence. If you include a mediator after these two mediators, it can cause unusual behaviour in the message flow.
The following diagram illustrates an incorrect use of the Send mediator:
The following diagram illustrates the correct use of the Send mediator:
...
Use the Iterate mediator in association with the Aggregate mediator.
Do not do any configuration after the Send mediator.
Do proper error handling to handle mediation errors as well as endpoint errors.
Use appropriate intervals for tasks.
Use the ForEach mediator only for message transformations. If you need to make back-end calls from each iteration, then use the iterate mediator.
Do not use the DB mediators (DBReport and DBLookup) with complex SQL queries or in scenarios where you need to simultaneously retrieve multiple rows. Instead, use the data services functionality of WSO2 Enterprise Integrator. For information on how to use the data services functionality, see the Tutorials.
Use dollar context (i.e., $ctx) instead of get-property(). This is because the
get
- property methods search even in Registry if the value is not available in the message context. Thus, it affects performance as Registry search is an expensive operation. However,$
ctx
only checks in the message context.
If you need to retrieve a property that you have set on a message, use the predefined XPath variables such as $ctx instead of the get-property() function for better performance. For example, use$ctx:
proxy.name instead ofget-property('
proxy.name')
.
For more information on the predefined XPath variables that you can use to retrieve a property, and for examples of XPath variable usage, see Synapse XPath Variables.Note title Note The use of the
get-property()
function can have a lower performance because it does a registry lookup when the value is not available in the message context. Therefore, the recommended approach is to use predefined XPath variables when you need to retrieve a property.You will encounter this performance issue only if you are using WSO2 ESB 4.9.0 or below.
Reusing a defined sequence
If you want to repeatedly use the same mediation sequence, you can define it and save it either in the Synapse configuration or in the Registry, with a unique name. Then you can call the mediation sequence from the main sequence as well as from multiple proxy services and REST APIs. The saved sequence can be called via the Sequence mediator or can be selected as theInSequence
,OutSequence
, orFaultSequence
when you define a proxy service or a REST API.The following diagram illustrates how a saved sequence can be called using the Sequence mediator:
...
- Ensure that you tune the deployment environment based on the performance tuning guidelines.
Install all patches using WSO2 Update Manager (WUM) in all environments.
Info title Note If you are using WSO2 ESB 4.9.0 or above, ensure that you have all WUM updates installed at any given time.
- Pre-test patches in a test environment before going into the production environment. You should use an automated test suite to do this. For example, you can use JMeter Automation or SOAP UI.
- Pre-test artifacts in a test environment before deploying into the production environment.
- Pre-test configuration changes before applying them in the production environment.
- Automate the process of change deployment. You can use puppet for this purpose. For more information, see the tutorial on How To Use WSO2 Puppet Modules to Deploy WSO2 Products.
- Make sure you follow the production hardening guidelines before going into production or exposing instances to live traffic.
- To port your artifacts from one environment to another, first package the artifacts into a Composite Application (C-App) archive using WSO2 Enterprise Integrator Tooling, and then deploy the C-App in the new environment.
- It is not recommended to run more than one server instance inside a docker container.
Note |
---|
You can implement high availability in your deployment via strategies like Blue-Green, Canary, or Rolling deployments. Select one of those strategies based on your requirements. This enables you to perform load balancing to maintain availability of services for consumers while they are being undeployed. |
Recommended deployment patterns
...