How to write routes?

Owned by Trello
Last updated: Nov 23, 2016 by Petr Jůza
3 min read

 

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

Look at How to start new project? for starting new project ...

Look at Development tips and Best practices.

Adhere to conventions how to write the code.

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 

Unit tests

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

  • create unit test that extends AbstractTest or AbstractDbTest (both classes are from test module) if database support is needed
  • 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

 

You can use RouteBeanNameGenerator for automatic bean names generation.

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-funnel, asynch-child, ...
  • define senders CloseableHttpComponentsMessageSender for calling external system via Spring Web Service (SOAP messages). Add configuration into /META-INF/sp_ws_wsdl.xml

 

Use SoupUI integration test for calling real web service to verify that everything works as expected. Unit test is good to have but it doesn't catch all possible problems.

Example implementations

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

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

WSDL and XSD implementation

  • WSDL and XSD is defined in Contract-First design approach - firstly define web service interfaces, secondly implement them in specific language.
  • there are two files (in package resources/org.openhubframework.openhub.modules.in.hello.ws.v1_0): WSDL definition (e.g. hello-v1.0.wsdl) and XSD with requests/responses definition (helloOperations-v1.0.xsd). XSD contains request definitions, imports commonTypes-v1.0.xsd with common types
  • publish WSDL/XSD files - add configuration to /META-INF/sp_ws_wsdl.xml. sws:static-wsdl is used for publishing WSDL, XSD files have to be published separately. See Spring Web Services reference manual where you find more information because Spring WS is underlying library for web service communication.
  • register XSD schemas for validation incoming/outgoing messages in configuration of "validatingInterceptor" (class HeaderAndPayloadValidatingInterceptor)
    • traceHeader is mandatory for asynchronous requests only - set synchronnous requests in ignoreRequests property to ignore this validation
  • configure conversion to Java classes - use jaxws-maven-plugin Maven plugin for conversion from WSDL or jaxb2-maven-plugin for conversion from XSD

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 implementation

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