SwitchYard provides a low-level auditing mechanism intended for application debugging. Using Auditors to implement application logic is generally discouraged as the set and order of processors which auditors bind to is subject to change at any time. Auditing support requires a CDI environment to run, so your application must include META-INF/beans.xml.
SwitchYard exchanges sent from a service consumer to a service provider go through a set of handlers:
Addressing - addressing handler determines which provider is wired to a consumer reference.
Transaction - when service requires transaction this handler starts it
Security - verifies contraints related to authentication and authorization
General policy - executes other checks different than security and transaction
Validation - executes custom validators
Transformation - prepare payload for calling providing service
Validation - validates transformed payload
Provider call - calls providing service
Transaction - commits or rollbacks transaction, if necessary
If service consumer is synchronous and exchange pattern is set to in-out then some from these handlers are called once again:
Validation - verifies output generated by provider
Transformation - converts payload to structure required by consumer
Validation - checks output after transformation
Consumer callback - returns exchange to service consumer
As said before audit mechanism requires CDI runtime to work. Annotate your Auditor implementations with the @Named annotation in order to have Camel recognise them. Camel Exchange Bus (a default implementation used by SwitchYard) look up for bean definitions with @Audit annotation. Simplest auditor looks following:
@Audit
@Named("custom auditor")
public class SimpleAuditor implements Auditor {
@Override
public void beforeCall(Processors processor, Exchange exchange) {
System.out.println("Before " + processor.name());
}
@Override
public void afterCall(Processors processor, Exchange exchange) {
System.out.println("After " + processor.name());
}
}
You will see lots of statements printed in server console like 'Before DOMAIN_HANDLERS', 'Before ADDRESSING' and so on. Every step of mediation is surrounded by this SimpleAuditor class.
Be aware that afterCall method is not called if surrounded step thrown an exception. In this case call of afterCall is skipped.
If you are not interested in all these states of SwitchYard mediation process you might provide argument to @Audit annotation. Accepted values must come from org.switchyard.bus.camel.processors.Processors enumeration. For example @Audit(Processors.VALIDATION) will handle only validation occurances.
Please remember that validation is executed twice for in-only exchanges and fourth times for in-out. Validation occurs before transformation of inbound message and after transformation. In case when outgoing message will be sent from SwitchYard service validation is executed before transformation of outbound message and after transformation.
Transformation is executed once for in-only exchanges and twice for in-out exchanges.
Transaction phase is always executed twice.
If you are interested in only one execution of your auditor use following combination @Audit(Processors.PROVIDER_CALLBACK). Auditor will be executed just before sending exchange to service implementation. It's also possible to stick one auditor instance with few mediation steps. For example bean with annotation @Audit({Processors.PROVIDER_CALLBACK, Processors.CONSUMER_CALLBACK}) will be executed twice. One pair of before/after call for provider service and second pair for outgoing response.
Custom auditors should not preserve state inside any fields because dispatching order is not guaranteed and only one instance of auditor is created by default. If you would like store some values please use exchange properties or message headers. Example below shows how to count processing time using Exchange properties as temporary storage.
@Named("custom auditor")
public class SimpleAuditor implements Auditor {
private Logger _logger = Logger.getLogger(SimpleAuditor.class);
@Override
public void beforeCall(Processors processor, Exchange exchange) {
exchange.setProperty("time", System.currentTimeMillis());
}
@Override
public void afterCall(Processors processor, Exchange exchange) {
long time = System.currentTimeMillis() - exchange.getProperty("time", 0, Long.class);
_logger.info("Step " + processor.name() + " took " + time + "ms");
}
}