Page History

...

When an asset is the entity parameter of a resource method, it is used by the Apache Wink runtime to set the actual request entity by invoking the appropriate entity-consuming method of the asset.

Assets Overview

A typical application exposes each resource in a number of representations. Some form of data model usually backs the resource, and the application business logic relies on the manipulation of that data model. The application will most likely expose resource methods allowing the consumption of the data model in more than one representation (for example Atom and XML) and the production of the data model in other representation (for example Atom, XML and JSON).

...

The lifecycle of an asset as a response entity is as follows:

1. The application creates and returns the asset from the resource method.
2. The appropriate entity-producing method is invoked by the Apache Wink runtime to retrieve the actual response entity.
3. The appropriate message body writer as obtained from the Providers#getMessageBodyWriter() method serializes the entity obtained at the previous step.
4. The asset is made available for garbage collection.

Request Entity Asset

The lifecycle of an asset as a request entity is as follows:

1. An asset class is instantiated by the Apache Wink runtime by invoking the asset default constructor. Note that this implies that the asset class must have a public default constructor.
2. The appropriate message body reader as obtained from the Providers#getMessageBodyReader() method is invoked by the Apache Wink runtime to read the request entity.
3. The appropriate entity-consuming method is invoked on the asset to populate the asset with the request entity.
4. The asset is injected into the resource method as the entity parameter.
5. The asset is made available for garbage collection after returning from the resource method.

Asset Entity Methods

Asset Entity methods are the public methods of an asset annotated with either @Consumes or @Produces annotation. Annotating a method with both @Consumes and @Produces annotations is not supported and may result in unexpected behavior.

...

Asset classes are handled by the AssetProvider which is a JAX-RS provider that is capable of consuming and producing all media types.

Request Entity Matching

The following points describe the process of selecting the asset entity-consuming method to handle the request entity. This process occurs during the invocation of the AssetProvider#isReadable() method.

1. Collect all the entity-consuming methods of the asset. These are the public methods annotated with @Consumes annotation.
2. Sort the collected entity-consuming methods in descending order, where methods with more specific media types precede methods with less specific media types, following the rule n/m > n/* > /.
3. Select the first method that supports the media type of the request entity body as provided to the AssetProvider#isReadable() method, and return true.
4. If no entity-consuming method supports the media type of the request entity body, return false. The Apache Wink runtime continues searching for a different provider to handle the asset as a regular entity.

Response Entity Matching

The following points describe the process of selecting an entity-producing method to produce the actual response entity. The following process occurs during the invocation of the AssetProvider#isWriteable() method.

1. Collect all the entity-producing methods of the asset. These are the public methods annotated with @Produces annotation.
2. Sort the collected entity-producing methods in descending order, where methods with more specific media types precede methods with less specific media types, following the rule n/m > n/* > /.
3. Select the first method that supports the media type of the response entity body as provided to the AssetProvider#isWriteable()method and return true.
4.  If no entity-producing method supports the media type of the response entity body, return false. The Apache Wink runtime continues searching for a different provider to handle the asset as a regular entity.

Asset Example

The following example illustrates the use of an asset. The "Defect" bean is a JAXB annotated class.

DefectAsset Class

The DefectAsset class is the asset backed by an instance of a "Defect" bean. The DefectResource class is a resource that is anchored to the URI path "defects/{id}" within the Apache Wink runtime.

...

@Asset
public class DefectAsset {
    public Defect defect;
    public DefectAsset(Defect defect) {
        this.defect = defect;
    }
    @Produces("application/xml")
    public Defect getDefect() {
        return this.defect;
    }
    @Produces("text/html")
    public String getDefectAsHtml() {
        String html = ...;
        return html;
    }

    @Produces("application/atom+xml")
    public AtomEntry getDefectAsAtom() {
        AtomEntry entry = ...;
        return entry;
    }
    @Consumes("application/xml")
    public void setDefect(Defect defect) {
        this.defect = defect;
    }
}

DefectResource Class

 The DefectResource class is a resource that is anchored to the URI path "defects/{id}" within the Apache Wink runtime.

@Path("defects/{id}")
public class DefectResource {
    @GET
    public DefectAsset getDefect(@PathParam("id") String id) {
        return new DefectAsset(defects.get(id));
    }
    @PUT
    public DefectAsset updateDefect(DefectAsset defectAsset,
                                    @PathParam("id") String id) {
        defects.put(id, defectAsset.getDefect());
        return defectAsset;
    }
}

Scenario Explanation 1

1. A client issues an HTTP GET request with a URI="/defects/1" and Accept Header= "application/xm
2. The Apache Wink runtime analyzes the request and invokes the DefectResource#getDefect() resource method.
3. The DefectResource#getDefect() resource method creates an instance of DefectAsset and populates it with defect "1" data
4. The DefectResource#getDefect() resource method returns the DefectAsset instance back to Apache Wink runtim
5. The Apache Wink runtime analyzes the asset and invokes the DefectAsset#getDefect() entity-producing method to obtain the reference to the "Defect" bean.
6. The "Defect" bean is serialized by Apache Wink runtime as an XML using the appropriate provider.

Scenario Explanation 2

1. A Client issues an HTTP GET request with a URI="/defects/1" and Accept Header= "text/html"
2. The Apache Wink runtime analyzes the request and invokes the DefectResource#getDefect() resource metho
3. The DefectResource#getDefect() resource method creates an instance of DefectAsset and populates it with defect "1" data.
4. The DefectResource#getDefect() method returns the populated asset back to the Apache Wink runtime.
5. The Apache Wink runtime analyzes the asset and invokes the DefectAsset#getDefectAsHtml() entity-producing method in order to obtain the reference to the "Defect" bean.
6. The "Defect" is serialized by Apache Wink runtime as an HTML using the appropriate provider.

Scenario Explanation 3

1. A Client issues an HTTP PUT request with a URI="/defects/1" and Accept Header= "text/html"
2. The Apache Wink runtime analyzes the request and invokes the DefectResource#updateDefect() method with an instance of DefectAsset populated with the request entity.* A DefectAsset is instantiated by the Apache Wink runtime
3. The DefectAsset#setDefect() entity-consuming method is invoked in order to populate the DefectAsset with the defect data.