How to write routes?

 

This page contains list of steps and tips for implementation new routes.

Create new routes

  • class name should ends with suffix Route
  • adhere to the rules of naming conventions for route IDs (use getInRouteId(), getOutRouteId() or getRouteId() functions) and URIs
  • use parent class org.openhubframework.openhub.api.route.AbstractBasicRoute
  • use @CamelConfiguration and define unique Spring bean name for this route - this annotation allows initialization by Spring auto-scanning funcionality. Don't forget to check auto-scanning configuration.
  • define operation name 

New synchronous route implementation

Synchronous route is route where source system waits for response. This type of requests are not stored in OpenHub evidence, there are mentions in log files only. Possible error is immediately propagated to source system.

Steps for implementation are identical to those mentioned in previous chapter.

New asynchronous route implementation

How to implement asynchronous routes is described in another page.

Route implementation tips

Checklist of features which can be used during route implementation:

  • throttling - route for processing asynchronnous input requests contains throttling by default. You should add it to all synchronnous routes
  • external call - each call to external system should go through "external call" funcionality
  • route authorization is made by Camel policy, see Camel Security
  • guaranteed message processing order
  • checking of obsolete messages via object ID
  • look at components for use - msg-funnelasynch-child, ...
  • define senders CloseableHttpComponentsMessageSender for calling external system via Spring Web Service (SOAP messages). Add configuration into /META-INF/sp_ws_wsdl.xml

 

Example implementations

Example routes are in examples module. There are two basic examples - synchronous and asynchronous hello world service implemented as web services.

WSDL is available on /ws/hello.wsdl and endpoint on the URL /ws/hello/v1

Synchronous Hello service

Synchronous implementation is in class org.openhubframework.openhub.modules.in.hello.SyncHelloRoute

If comes web service request with element name syncHelloRequest and namespace http://openhubframework.org/ws/HelloService-v1) then this route is "activated" and request starts processing. Response is immediately send back to the source system.

Asynchronous Hello service

Asynchronous implementation is in class org.openhubframework.openhub.modules.in.hello.AsyncHelloRoute.

If comes web service request with element name asyncHelloRequest and namespace http://openhubframework.org/ws/HelloService-v1) then this route is "activated" and request starts processing. Firstly synchronous part is proceeded - input request is validated and saved into queue (database) and synchronous response is immediately send back to the source system with information that OpenHub accepted input request and ensures request processing. When request processing finishes then asynchronous confirmation with processing result is send to source system.

Unit tests

Each route implementation must have corresponding unit tests, at least one successful scenario.

  • create unit test that extends AbstractTest or AbstractDbTest if database support is needed (both classes are from test module)
  • you can use Spring test profiles - see org.openhubframework.openhub.modules.TestProfiles
  • use @ActiveRoutes annotation that defines which routes will be activated for specific unit test


There are corresponding unit tests to each route - SyncHelloRouteTest resp. AsyncHelloRouteTest.