[[PageOutline]]
= Basic Integration =
Develop an annotation processor for dependency injection and template handling. Similar syntax to JBoss Seam.
== Resource Identification ==
A resource is identified by the `@Resource` annotation.
{{{
#!java
@Resource("/full/url/path/with/{template}/{variables}")
public class Example {
}
}}}
== Dependency Injection ==
Dependencies are identified with the `@In` annotation and can be sourced from the URL template or request parameters. Unless specified, search order is request parameters first. For example a request to `/full/url/path/with/foo/bar?param=value&variables=blah` could be injected into resource:
{{{
#!java
@Resource("/full/url/path/with/{template}/{variables}")
public class Example {
@In(source=SourceType.TEMPLATE) private String template;
@In private String variables;
@In(name="param", required=false) private String widget;
}
}}}
After instantiation: `template` will contain "foo"; `variables` will contain "blah"; and `param` will contain "value".
== Representation Association ==
An XTC template can be associated with a resource for representing a particular content type. The default content type is "text/html". The association is made with the `@Representation` annotation:
{{{
#!java
@Resource("/full/url/path/with/{template}/{variables}")
@Representation("/path/to/template.xhtml")
@Representation("/path/to/another.xml", contentType="text/xml")
public class Example {
}
}}}
== XTC Context ==
The XTC template context is initialised by out-jection from the resource. Objects to be made available to the template context are annotated with the `@Out` annotation:
{{{
#!java
@In(name="var") @Out private String variables;
@Out(name="myData") private MyDataObject data;
}}}
== Request Handling ==
Resources may perform some processing for a request by providing a void method annotated with the appropriate request type. Available request types annotations are `@Get`, `@Post`, `@Put` and `@Delete`. Typically, this is where the resource will initialise variables for out-jection to the template context. A complete example, using the request URL of `/list/1?size=10`:
{{{
#!java
@Resource("/list/{id}")
@Representation("ListTemplate.xhtml")
public class ListResource {
@In @Out private Integer id;
@In(required=false) private Integer size;
@Out private List list;
@Get public void processGet() {
list = retrieveListFromDatasource(id);
if (list.size() > size) {
list = list.subList(0, size);
}
}
}
}}}
`ListTemplate.xhtml`:
{{{
#!text/html
List ${id}
}}}
== Google Guice ==
How much of the above can be achieved using Guice rather than creating a new annotation processor and dependency injector? Not much really. Guice mostly handles class level bindings, not named instance binding like we desire. It could be done, but it would be clunky.
= Resource Relations =
How can we handle relationships between resources? For example `Invoice` would contain `Item`s, perhaps with a URL mapping of `/invoice/{invoiceNumber}/item/{itemNumber}`. Using the above techniques requires us to have an `InvoiceItemResource` which handles the full URL above, as well as an `InvoiceResource` for just `/invoice/{invoiceNumber}` URLs. Wouldn't it be better to be able to specify that `ItemResource` is a sub-resource of `InvoiceResource` with relative URL `item/{itemNumber}`? Then we could re-use the `ItemResource` in an `InventoryResource` (perhaps with a different relative URL).
== Option A ==
Sub-resources are identified in the parent resource with a complete relative URL:
{{{
#!java
@Resource("/invoice/{invoiceNumber}")
public class InvoiceResource {
@SubResource("/item/{itemNumber}")
private ItemResource items;
}
}}}
First the parent is initialised and processed for `@Get`, then the sub-resource is processed.