Page History

...

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.

...

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.

• Collect all the entity-consuming methods of the asset. These are the public methods annotated with @Consumes annotation.

...

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.

• Collect all the entity-producing methods of the asset. These are the public methods annotated with @Produces annotation.

...

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.

DefectAsset Class

@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.