docs/user-manual/modules/ROOT/pages/using-exchange-pattern-annotations.adoc

[[UsingExchangePatternAnnotations-UsingExchangePatternAnnotations]]
= Using Exchange Pattern Annotations

When working with xref:pojo-producing.adoc[POJO Producing] or
xref:spring-remoting.adoc[Spring Remoting] you invoke methods which
typically by default are InOut for xref:request-reply.adoc[Request
Reply]. That is there is an In message and an Out for the result.
Typically invoking this operation will be synchronous, the caller will
block until the server returns a result.

Camel has flexible xref:exchange-pattern.adoc[Exchange Pattern] support
- so you can also support the xref:event-message.adoc[Event Message]
pattern to use InOnly for asynchronous or one way operations. These are
often called 'fire and forget' like sending a JMS message but not
waiting for any response.

From 1.5 onwards Camel supports annotations for specifying the message
exchange pattern on regular Java methods, classes or interfaces.

[[UsingExchangePatternAnnotations-SpecifyingInOnlymethods]]
== Specifying InOnly methods

Typically the default InOut is what most folks want but you can
customize to use InOnly using an annotation.

[source,syntaxhighlighter-pre]
----
public interface Foo {
  Object someInOutMethod(String input);
  String anotherInOutMethod(Cheese input);
  
  @InOnly
  void someInOnlyMethod(Document input);
}
----

The above code shows three methods on an interface; the first two use
the default InOut mechanism but the *someInOnlyMethod* uses the InOnly
annotation to specify it as being a oneway method call.

[[UsingExchangePatternAnnotations-Classlevelannotations]]
== Class level annotations

You can also use class level annotations to default all methods in an
interface to some pattern such as

[source,syntaxhighlighter-pre]
----
@InOnly
public interface Foo {
  void someInOnlyMethod(Document input);
  void anotherInOnlyMethod(String input);
}
----

Annotations will also be detected on base classes or interfaces. So for
example if you created a client side proxy for

[source,syntaxhighlighter-pre]
----
public class MyFoo implements Foo {
  ...
}
----

Then the methods inherited from Foo would be InOnly.

[[UsingExchangePatternAnnotations-Overloadingaclasslevelannotation]]
== Overloading a class level annotation

You can overload a class level annotation on specific methods. A common
use case for this is if you have a class or interface with many InOnly
methods but you want to just annote one or two methods as InOut

[source,syntaxhighlighter-pre]
----
@InOnly
public interface Foo {
  void someInOnlyMethod(Document input);
  void anotherInOnlyMethod(String input);
  
  @InOut
  String someInOutMethod(String input); 
}
----

In the above Foo interface the *someInOutMethod* will be InOut

[[UsingExchangePatternAnnotations-Usingyourownannotations]]
== Using your own annotations

You might want to create your own annotations to represent a group of
different bits of metadata; such as combining synchrony, concurrency and
transaction behaviour.

So you could annotate your annotation with the @Pattern annotation to
default the exchange pattern you wish to use.

For example lets say we want to create our own annotation called
@MyAsyncService

[source,syntaxhighlighter-pre]
----
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.METHOD})

// lets add the message exchange pattern to it
@Pattern(ExchangePattern.InOnly)

// lets add some other annotations - maybe transaction behaviour?

public @interface MyAsyncService {
}
----

Now we can use this annotation and Camel will figure out the correct
exchange pattern...

[source,syntaxhighlighter-pre]
----
public interface Foo {
  void someInOnlyMethod(Document input);
  void anotherInOnlyMethod(String input);
  
  @MyAsyncService
  String someInOutMethod(String input); 
}
----