This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • 5.2 Annotations
Skip to end of metadata
Go to start of metadata

Annotations

Apache Wink provides several annotations in addition to those defined by the JAX-RS specification. The following section describes these annotations in detail.

@Workspace Annotation

The purpose of the @Workspace annotation is to associate a "Collection Resource" with a workspace element and collection elements in an APP Service Document.

Reference

For more information regarding the APP Service Document, refer to section 5.4 APP Service Document

The workspaceTitle annotation parameter specifies the title of the workspace and the collectionTitle annotation parameter specifies the title of the collection.

@Workspace Annotation Specification

Value

Description

Mandatory

No

Target

Resource class

Parameters

Name

Type

 

workspaceTitle

String

 

collectionTitle

String

Example

@Workspace(workspaceTitle = "Title",
collectionTitle = "Collection") x

@Workspace Annotation Example

The following example demonstrates the use of @Workspace annotation on two resources in order to have the auto-generated APP service document contain the information about them.

Given the following collection Resources definitions, ResourceA and ResourceB, the result is displayed in the "Auto Generated APP Service Document" table that follows.

ResourceA Definition

@Workspace(workspaceTitle = "Services", collectionTitle = "Service1")
@Path("services/service1")
public class ResourceA {
    @POST
    @Produces("text/plain")
    @Consumes({"application/atom+xml", "application/xml"})
    public String getText() {return "hey there1";}
}

ResourceB Definition

@Workspace(workspaceTitle = "Services", collectionTitle = "Service2")
@Path("services/service2")
public class ResourceB {
    @POST
    @Produces("text/plain")
    @Consumes({"application/atom+xml", "application/xml"})
    public String getText() {return "hey there2";}
}

The auto-generated APP Service Document is as follows:

Auto Generated APP Service Document

<service xmlns:atom=http://www.w3.org/2005/Atom
         xmlns="http://www.w3.org/2007/app">
    <workspace>
        <atom:title>Services</atom:title>
        <collection href="services/service1">
            <atom:title>Service1</atom:title>
            <accept>application/xml</accept>
            <accept>application/atom+xml</accept>
        </collection>
        <collection href="services/service2">
            <atom:title>Service2</atom:title>
            <accept>application/xml</accept>
            <accept>application/atom+xml</accept>
        </collection>
    </workspace>
</service>

@Asset Annotation

The @Asset annotation is a marker annotation used by the Apache Wink runtime in order to identify an entity as an Asset.

Reference

For more information about Assets refer to section 5.9 Assets.

@Asset Annotation Specification

Value

Description

Mandatory

No

Target

Resource class

Parameters

None

Example

@Asset

@Scope Annotation

The JAX-RS specification defines the default lifecycle behavior for resources and providers, and the option for controlling the lifecycle through the javax.ws.rs.core.Application class.

Apache Wink provides the @Scope annotation to specify the lifecycle of a provider or resource.

@Scope Annotation Specification

Value

Description

Mandatory

No

Target

Provider class or Resource class

Parameters

Name

Type

 

Value

ScopeType enum

Example

@Scope(ScopeType.PROTOTYPE)

Resource Example

The following example illustrates how to define a resource with a singleton lifecycle.

@Scope(ScopeType.SINGLETON)
@Path("service1")
public class ResourceA {
    ...
}

Provider Example

The following example illustrates how to define a provider with a prototype lifecycle.

@Scope(ScopeType.PROTOTYPE)
@Provider
public class EntityProvider implements MessageBodyReader<String> {
    ...
}

@Parent Annotation

The @Parent annotation provides the ability to define a base template URI for the URI specified in a resources @Path annotation.
If a resource is annotated with the @Parent annotation, the Apache Wink runtime calculates the final resource template by first retrieving the value of the @Parent annotation, which holds the parent resource class, and then concatenates the resource path template definition to the path template definition of the parent resource.

@Parent Annotation Specification

Value

Description

Mandatory

No

Target

Provider class or Resource class

Parameters

Name

Type

 

Value

Class<?>

Example

@Parent(ParentResource.class)

Example 1

@Path("services")
public class ParentResource {
    ...
}

Example 2

@Parent(BaseResource.class)
@Path("service1")
public class ResourceA {
    ...
}
Explanation

In the example, the user defined two resources: A ParentResource and ResourceA. ParentResource defines the @Path annotation to associate it with "services" URI. ResourceA defines the @Path annotation to associate it with "service1" URI and defines ParentResource to be its parent by specifying it in the @Parent annotation. In this case, the final URI path for ResourceA is "services/service1".

  • No labels