This specification defines the following entities:

Figure 151.1 JAX-RS Whiteboard Overview Diagram

The Figure 151.1 shows an OSGi framework running a JAX-RS Whiteboard Implementation bundle. This bundle has been configured to provide two JAX-RS whiteboards, each of which has a corresponding JAX-RS Service Runtime Service. The various JAX-RS Whiteboard services available in the framework are discovered and processed by both whiteboards.

The JaxrsServiceRuntime service represents the runtime state information of a JAX-RS Whiteboard instance. This information is provided through Data Transfer Objects (DTOs). The architecture of OSGi DTOs is described in OSGi Core Release 8.

Each JAX-RS Whiteboard implementation registers exactly one JaxrsServiceRuntime service per JAX-RS Whiteboard. The service properties of the JAX-RS Service Runtime Service can be used to target JAX-RS Whiteboard services at specific JAX-RS whiteboards, as described by the osgi.jaxrs.whiteboard.target property in Common Whiteboard Properties.

The JaxrsServiceRuntime provides service registration properties to declare its underlying JAX-RS Whiteboard. These service properties can include implementation-specific key-value pairs. They also include the following:

The JAX-RS Service Runtime service provides information about registered Whiteboard services through the RuntimeDTO.

The Runtime DTO provides information about services that have been successfully registered as well as information about the JAX-RS Whiteboard services that were not successfully registered. JAX-RS Whiteboard services that have the required properties set but cannot be processed, are reflected in the failure DTOs. JAX-RS Whiteboard services of interfaces described in this specification that do not have the required properties set are ignored and not reflected in the failure DTOs.

The Runtime DTO can be obtained using the getRuntimeDTO() method. The Runtime DTO returned provides a snapshot of the state of the JAX-RS Runtime, including the JAX-RS Whiteboard resources, extensions and applications that are active in each registered application. The Runtime DTO also includes information about Whiteboard services which could not be activated.

Implementations of this specification will often be backed by existing servlet containers, such as the OSGi Http Whiteboard, or a Java EE application server. There may also exist implementations which bridge into a servlet container into which the OSGi Framework has been deployed as a Web Application.

In bridged situations the JAX-RS Whiteboard implementation will have limited facilities for creating new JAX-RS whiteboards, and may also have limited information about its environment.

Information about the surrounding Servlet Container, including ServletContext information and HttpSession data, is available to JAX-RS Whiteboard resources using standard JAX-RS injection behavior.

@GET
@Path("{name}")
public String interrogateSession(@PathParam("name") String name,
         @Context HttpServletRequest req) {
    HttpSession s = req.getSession();
    return String.valueOf(s.getAttribute(name));
}

A JAX-RS Whiteboard implementation needs to ensure that Http Sessions are not shared amongst different JAX-RS Whiteboards, or amongst different JAX-RS Whiteboard applications. That is, HttpServletRequest.getSession() calls must provide different sessions for each whiteboard application with which a JAX-RS whiteboard service is associated.

Even when they are created by the same JAX-RS Whiteboard implementation, each JAX-RS Whiteboard instance is separate, and isolated from other instances. Importantly, JAX-RS Whiteboard services targeted to one JAX-RS Whiteboard application must not be visible in any other Whiteboard or applications to which they are not targeted.

This isolation restriction is critical, as it ensures that different JAX-RS Whiteboard applications can be configured with different, potentially overlapping, incompatible extension features.

JAX-RS resources use the Path annotation to bind themselves to particular URIs within the JAX-RS container. The path annotation can be applied to the resource class, and to individual resource methods. For example the following JAX-RS resource:

@Path("foo")
public class Foo {

    private final List<String> entries = 
        Arrays.asList("fizz", "buzz", "fizzbuzz");
        
    @GET
    public List<String> getFoos() {
        return Collections.unmodifiableList(entries);
    }

    @GET
    @Path("{name}")
    public String getFoo(@PathParam("name") String name) {
        if(entries.contains(name)) {
            return "A foo called " + name;
        }
        throw new IllegalArgumentException(“No foo called “ + name);
    }

}

This JAX-RS resource defines two resource methods. The Path annotation applied to the class sets the base URI for all methods in the resource. The getFoos() method is therefore bound to the URI foo. The Path annotation on the getFoo() method makes this method a sub-resource which captures the next token in the URI. This method is therefore bound to URIs of the form foo/buzz.

When used as an OSGi JAX-RS Whiteboard service a JAX-RS resource follows the same mapping rules, but the base context(s) it uses are determined by the Application(s) to which it is mapped. For example, when mapped to the default application of a whiteboard with endpoint http://127.0.0.1/ the getFoos() method would be available at http://127.0.0.1/foo.

A key tenet of JAX-RS is that all resource objects are stateless. In the JAX-RS specification resources therefore have one of two scopes, they are either singleton, or request-scoped. Singleton resources are created once, potentially outside the JAX-RS container, and request-scoped resources are created on-demand for each request, then discarded afterwards.

Typically JAX-RS developers are encouraged to write request-scoped resources, as this makes it difficult to accidentally write stateful components. In OSGi, however, it is more common to write singleton services. On demand instances of OSGi services can be created, but only if the service is registered as a prototype scope.

The JAX-RS whiteboard implementation is responsible for managing the mismatch between the OSGi service lifecycle model and the JAX-RS resource lifecycle model. If the JAX-RS whiteboard resource is registered as prototype scope then the implementation must treat the resources as request-scoped, creating a new service instance for each request and releasing it when the request completes. Otherwise the JAX-RS whiteboard service must be registered as a singleton scope resource within the application. Singleton scope whiteboard resources must be released by the JAX-RS whiteboard when the application with which they have been registered is removed from the whiteboard, even if this is only a temporary situation.

If a failure occurs when getting the resource service this will prevent the service from being used, which is reflected using a failure DTO. In such a case the system treats the resource as unusable.

When multiple JAX-RS Whiteboard implementations are present all of them can potentially process the whiteboard resources. In such situations it can be useful to associate the servlet with a specific whiteboard by specifying the osgi.http.whiteboard.target property on the service.

@Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource     
 public class MyResource {
  
    @Path(“foo”)
    @GET
    public void getFoo(@Suspended AsyncResponse async) {
        Promise<String> p = doLongRunningTaskAsynchronously();
        p.onSuccess(v -> async.resume(v))
            .onFailure(t -> async.resume(t));
    }
}

@Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource     
 public class MyResource {
  
    @Path(“foo”)
    @GET
    public Promise<String> getFoo() {
        Promise<String> p = doLongRunningTaskAsynchronously();
        return p;
    }
}

@Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource     
 public class MyResource {
  
    @Context
    Sse sse;

    @GET
    @Produces(MediaType.SERVER_SENT_EVENTS)
    public void getFoo(@Context SseEventSink sink) {
        PushStream<String> p = getStreamOfMessages();
        p.map(sse::newEvent)
            .forEach(e -> sink::send)
            .onResolve(sink::close);
    }
}

The following table describes the properties that can be used by JAX-RS resources registered as Whiteboard services. Additionally, the common properties listed in Table 151.2 on page are supported.

The following example code uses Declarative Services annotations to register a JAX-RS Whiteboard service.

@Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource     
 public class MyResource {
  
     @GET
     @Path("hello")
     @Produces("text/plain")
     public String sayHello(){
          return "Hello World!";
     }
 }

This example registers the resource method at: /hello. Requests for http://www.acme.com/hello map to the resource method, which is called to process the request.

To associate the above example resource with another application add the following service property:

osgi.jaxrs.application.select=(osgi.jaxrs.name=myApp)

This can also be added using the property annotation:

@JaxrsApplicationSelect("(osgi.jaxrs.name=myApp)")

Setting this property requires a JAX-RS application named myApp to be registered:

@Component(service=Application.class)
@JaxrsName("myApp")
@JaxrsApplicationBase("foo")
public class MyApplication extends Application {}

Now the whiteboard resource will be available at http://www.acme.com/foo/hello as configured by the custom JAX-RS application.

By default JAX-RS extensions are applied to every request, however sometimes they are only needed for a subset of resource methods. In this case a NameBinding annotation can be used to apply the extension to a subset of resource methods. The following example declares a binding annotation called FizzBuzz and uses it to bind an extension which replaces occurrences of "fizz" with "fizzbuzz".

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@NameBinding
public @interface FizzBuzz{}

@Component
@JaxrsExtension
@FizzBuzz
public class FizzBuzzReplacer implements WriterInterceptor {

    public void aroundWriteTo(WriterInterceptorContext ctx) {
        Object entity = ctx.getEntity();
        
        if(entity != null) {
            ctx.setEntity(entity.toString()
                .replace("fizz", "fizzbuzz"));
        }
        ctx.proceed();
    }
}

@Component(service=FizzResource.class)
@JaxrsResource
@Path("fizzbuzz")
public class FizzResource {

    @GET
    @FizzBuzz
    public String getFoos() {
        return "fizz, buzz, fizzbuzz";
    }
}

The result of an http request to the fizzbuzz URI will be fizzbuzz, buzz, fizzbuzzbuzz

The JAX-RS whiteboard implementation must support the use of NameBinding to limit the scope of applied whiteboard extensions.

JAX-RS filters can be annotated with @PreMatching to indicate that they should be applied before the JAX-RS container works out which resource should be called by the incoming request. These filters can therefore change the request such that it maps to a different resource than it would have before the filter’s operation. Pre-matching filters cannot use NameBinding as no corresponding named resource is available to the runtime when they operate.

When used in the OSGi JAX-RS Whiteboard JAX-RS extensions follow the same ordering rules as defined by the JAX-RS specification. Where more than one extension of a particular type is available then they are ordered according to their javax.annotation.Priority. If two extensions of the same type have the same priority then the whiteboard implementation must break the tie by ordering the extensions according to the natural ordering of their service references, with static extensions being ranked below all whiteboard services.

The extension processing flow is as follows:

The osgi.jaxrs.extension.select property described in Common Whiteboard Properties applies to extensions as well as JAX-RS resources. This is because one extension may depend on another.

The most common reason for an extension to have a dependency is for a context injection dependency. Dependencies are often provided by a ContextResolver so that they can be injected into another extension. The following example demonstrates a simple dependency on a Jackson ObjectMapper.

@JaxrsExtension
@JaxrsName("configProvider")
@Component
public class ConfigProvider implements ContextResolver {
    
    private ObjectMapper mapper = new ObjectMapper();
    
    public <T> getContext(Class<T> clazz) {
        if(ObjectMapper.class.equals(clazz)) {
            return mapper;
        }
        return null;
    }
}

@JaxrsExtension
@JaxrsExtensionSelect("(osgi.jaxrs.name=configProvider)")
@Component(scope=ServiceScope.PROTOTYPE)
public class ConfiguredExtension implements WriterInterceptor {

    @Context
    private Providers providers;

    public void aroundWriteTo(WriterInterceptorContext ctx) {
        Object entity = ctx.getEntity();
        
        if(entity != null) {
            ObjectMapper mapper = providers
                    .getContextResolver(ObjectMapper.class)
                    .getContext(ObjectMapper.class);
                    
            ctx.setEntity(mapper.writeValueAsString(entity));
        }
        ctx.proceed();
    }
}

Depending on the capabilities of the JAX-RS whiteboard implementation, and any statically defined extensions that make up a JAX-RS Whiteboard application, there may be numerous non standard extensions available. These extensions must be represented using service properties on the JAX-RS Service Runtime, or the whiteboard application as appropriate. This is why the extension select filters must also be matched against the JAX-RS Service Runtime service and the whiteboard application being targeted.

JAX-RS extensions have a different lifecycle from JAX-RS resources, within a single application a JAX-RS extension always behaves as a singleton. If a JAX-RS whiteboard extension is registered as prototype scope then the whiteboard implementation must obtain a separate instance for every application to which the extension is applied. Whiteboard extension services must be released by the JAX-RS whiteboard when the application with which they have been registered is removed from the whiteboard, even if this is only a temporary situation.

JAX-RS extensions often require configuration, and need to be configured differently for different applications. This configuration is typically provided by a JAX-RS ContextResolver and injected into fields of the extension by the JAX-RS container. It is therefore highly recommended that JAX-RS Whiteboard extensions are always registered as prototype scope, so that separate instances can be created for each whiteboard application.

If an extension is registered as a singleton service then it should not rely on any fields being injected by the JAX-RS Whiteboard implementation. JAX-RS Whiteboard implementations may support field injection for singleton extensions, however this behavior is non portable, and may lead to errors at runtime when using other implementations.

The following table describes the properties that can be used by JAX-RS extensions registered as Whiteboard services. Additionally, the common properties listed in Table 151.2 on page are supported.

The following example code uses Declarative Services annotations to register a require JAX-RS Whiteboard extension which provides JSON support, and requires the extension from a JAX-RS whiteboard resource.

@Component(property="serialize.to=JSON")
@JaxrsExtension
public class JsonProvider implements MessageBodyReader,
      MessageBodyWriter {
    ...      
}
 
 @Component(service = Object.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource
 @JaxrsExtensionSelect("(serialize.to=JSON)")
 public class MyResource {
  
     @GET
     @Path("hello")
     @Produces(MediaType.APPLICATION_JSON)
     public List<String> getList(){
          return Arrays.asList("Hello", "World!");
     }
 }

The base URI for each application within the whiteboard must be unique. If two or more applications targeting the same whiteboard are registered with the same base URI then only the highest ranked service will be made available. All other application services with that URI will have a failure DTO created for them. The same rules also apply to the osgi.jaxrs.name property, with the highest ranked service shadowing other applications with the same name.

The default application is implicitly created by the whiteboard and has the name .default. The default application has a lower ranking than all registered services. Therefore an application registered with a base of / will shadow a default application bound at /.

A whiteboard application service may set an osgi.jaxrs.name of .default to replace the default application. This technique may be used to rebind the default application to a base uri other than /.

If a whiteboard application fails (for example if the service get fails), or cannot be immediately deployed (for example if it has an unsatisfied osgi.jaxrs.extension.select) then any applications that it shadows are still shadowed and relevant failure DTOs are created for all of the applications.

It is possible for an application to require additional whiteboard extensions before it is eligible to be hosted by the whiteboard. When making this determination the Whiteboard implementation must perform a dry-run validation of the osgi.jaxrs.extension.select filter, applying all of the whiteboard extensions targeted to the application before determining whether the application's requirements are met.

The following table describes the properties that can be used by JAX-RS applications registered as Whiteboard services. Additionally, the common properties listed in Table 151.2 on page are supported, except for the osgi.jaxrs.application.select property.

In JAX-RS the @Context annotation may be used to inject the Application instance into a resource or extension. Application configuration properties can also be injected using the Configuration type.

When using the JAX-RS Whiteboard it can also be necessary to access the service properties associated with the application hosting the resource, for example to allow customization of the resource's response. To this end, the JAX-RS whiteboard implementation must make the Application service properties available as a Map in the configuration. The key used to store this map is osgi.jaxrs.application.serviceProperties, and it can be found in any injected Configuration instance.

Furthermore, for Feature and DynamicFeature extensions the application service properties must be visible in the FeatureContext passed to the extension when applying it to the application. The FeatureContext interface provides programmatic access to the Configuration for the application, so this visibility is achieved in the same manner as for an injected Configuration instance.

In the case where the hosting application is not an OSGi service, for example a Whiteboard implementation may choose to provide its default application as an internal detail, then the osgi.jaxrs.application.serviceProperties map must exist containing the osgi.jaxrs.name of the application and the service properties associated with the JaxrsServiceRuntime service.

The following example code uses Declarative Services annotations to register a JAX-RS Whiteboard application, and shows how to target an additional whiteboard resource to that application.

@Component(service=Application.class)
@JaxrsApplicationBase("example")
@JaxrsName("myApp")
public class MyApplication extends Application {
    public Set<Class<?>> getClasses() {
        return new HashSet<>(Arrays.asList(StaticResource.class));
    }      
}
 
 @Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource
 @JaxrsApplicationSelect("(osgi.jaxrs.name=myApp)")
 public class MyResource {
  
     @GET
     @Path("hello")
     @Produces("text/plain")
     public List<String> getList(){
          return Arrays.asList("Hello", "World!");
     }
 }

The MyResource service will be available at http://www.acme.com/example/hello

While Container extensions can be made available using whiteboard services, the same is not true for Clients. There are two main reasons for this:

In order to add filters, interceptors, readers and writers to the JAX-RS client users should use the ClientBuilder#register() method when building their client.

The JAX-RS client API supports both synchronous and asynchronous calls. In JAX-RS 2.1 the asynchronous behavior of the client was extended using the RxInvoker (reactive invoker) interface. All clients are required to support a reactive invoker which returns CompletionStage instances, however in OSGi the common representation of an asynchronous return is the Promise. This specification therefore provides the PromiseRxInvoker interface which can be used to obtain Promises from the JAX-RS client.

It is the responsibility of the JAX-RS whiteboard implementation to create instances of PromiseRxInvoker. The exact mechanism by which instances are created is undefined, however it is possible to register a portable factory to create PromiseRxInvoker instances by implementing the RxInvokerProvider interface and registering this type with the JAX-RS client. This portable implementation, however, is forced to use a blocking model by the underlying JAX-RS API, and so implementations may choose to implement a more optimized non-blocking model using internal types.

Clients of this specification may make use of the PromiseRxInvoker using normal JAX-RS idioms. For example:

Client client = clientBuilder.build();
Promise<String> p = client.target(REST_SERVICE_URL)
    .path("/foo")
    .path("/{name}")
    .resolveTemplate("name", buzz)
    .request()
    .rx(PromiseRxInvoker.class)
    .get(String.class);

In JAX-RS 2.1 support was added for Server Sent Events. These events are consumed by a REST client using the SseEventSource. The SseEventSource is not created by a JAX-RS client instance, but is normally created using a static factory method, which does not work in a modular environment. Therefore the JAX-RS whiteboard implementation must register a SseEventSourceFactory service in the service registry. This object serves as a factory for the JAX-RS SSE types.

Note that the SseEventSource has no way to register filters or message body processors. All of the filters and necessary processors must be registered with the JAX-RS client that is used to create the WebTarget used when building the SseEventSource. A client may therefore consume Server Sent Events in the following way:

Client client = clientBuilder.build();

WebTarget target = client.target(REST_SERVICE_URL)
    .path("/foo")
    .path("/{name}")
    .resolveTemplate("name", buzz);

SseEventSource source = sseFactory.newSource(target);
    
source.register(event -> doSomething(event));
    
source.open();

A SseEventSource may easily be converted into a PushEventSource (and consequently a PushStream) as follows. Note that the implementation does not respond to back-pressure requests and should typically be used with a buffer.

SseEventSource source = sseBuilder.newSource(target);
    
PushEventSource<InboundSseEvent> pes = pec ->
        source.register(e -> {
                                try {
                                    if(pec.accept(PushEvent.data(e)) < 0) {
                                        source.close();
                                    }
                                } catch (Exception e) {
                                    try {
                                        pec.accept(PushEvent.error(e));
                                    } finally {
                                        source.close();
                                    } 
                                }
                            },
                        t -> pec.accept(PushEvent.error(t)),
                        () -> pec.accept(PushEvent.close()));
        source.open();
        return source;
    };

A common use of the JAX-RS extension mechanism is to provide support for additional media types, both for consuming incoming requests and for producing responses. All JAX-RS whiteboards must implicitly support text/plain and application/xml (using JAXB), however commonly used media types, such as application/json must be provided as an extension.

To ensure that whiteboard resources can depend on support for a particular media type in a portable way this specification defines the osgi.jaxrs.media.type property. This property key should be registered with one or more media types that are supported, and may be provided by:

The term general purpose is used to indicate that the media type support must not require implementation specific mapping metadata (for example annotations) and should, at a minimum, work with the OSGi scalar types and DTOs. The property key is available as a constant in JAX_RS_MEDIA_TYPE.

@Component(service = MyResource.class,
      scope = ServiceScope.PROTOTYPE)
 @JaxrsResource
 @JSONRequired
 @Produces(MediaType.APPLICATION_JSON)  
 public class MyResource {
  
    @Path(“foo”)
    @GET
    public List<String> getFoos() {
        return Arrays.asList("foo", "bar", "baz");
    }
}

@Component(scope = ServiceScope.PROTOTYPE)
 @JaxrsExtension
 @JaxrsMediaType(MediaType.APPLICATION_JSON)
 public class MyFeature implements Feature {
  
    public boolean configure(FeatureContext context) {
    		context.register(MyJSONCodec.class);
        return true;
    }
}

The JAX-RS Whiteboard implementation bundle must provide the osgi.implementation capability with name osgi.jaxrs. This capability can be used by provisioning tools and during resolution to ensure that a JAX-RS Whiteboard implementation is present to process the Whiteboard services defined in this specification. The capability must also declare a uses constraint for the javax.ws.rs.* specification packages, and for the and OSGi JAX-RS Whiteboard package. The version of this capability must match the version of this specification:

Provide-Capability: osgi.implementation;
       osgi.implementation="osgi.jaxrs";
       uses:="javax.ws.rs, javax.ws.rs.client, javax.ws.rs.container,
              javax.ws.rs.core, javax.ws.rs.ext, javax.ws.rs.sse, 
              org.osgi.service.jaxrs.whiteboard";
       version:Version="1.0"

This capability must follow the rules defined for the osgi.implementation Namespace.

The JAX-RS Whiteboard implementation must provide a capability in the osgi.contract namespace with name JavaJAXRS if it exports the JAX-RS specification packages. See [5] Portable Java Contract Definitions.

Providing the osgi.contract capability enables developer to build portable bundles for packages that are not versioned under OSGi Semantic Versioning rules. For more details see osgi.contract Namespace.

If the JAX-RS API is provided by another bundle, the JAX-RS Whiteboard implementation must be a consumer of the API and require the contract.

The bundle providing the JaxrsServiceRuntime service must provide a capability in the osgi.service namespace representing this service. This capability must also declare a uses constraint for the org.osgi.service.jaxrs.runtime and org.osgi.service.jaxrs.runtime.dto packages:

Provide-Capability: osgi.service;
  objectClass:List<String>="org.osgi.service.jaxrs.runtime.JaxrsServiceRuntime";
  uses:="org.osgi.service.jaxrs.runtime,org.osgi.service.jaxrs.runtime.dto"

The bundle providing the javax.ws.rs.client.ClientBuilder service must also provide a capability in the osgi.service namespace representing this service. This capability must declare that the service is prototype scope, and that there is a uses constraint for the javax.ws.rs.client package:

Provide-Capability: osgi.service;
  objectClass:List<String>="javax.ws.rs.client.ClientBuilder";
  uses:="javax.ws.rs.client,org.osgi.service.jaxrs.client";
  service.scope="prototype"

The bundle providing the org.osgi.service.jaxrs.client.SseEventSourceFactory service must also provide a capability in the osgi.service namespace representing this service. This capability must declare a uses constraint for the org.osgi.service.jaxrs.client package:

Provide-Capability: osgi.service;
  objectClass:List<String>="org.osgi.service.jaxrs.client.SseEventSourceFactory";
  uses:="org.osgi.service.jaxrs.client"

These capabilities must follow the rules defined for the osgi.service Namespace.

Bundles that need to register JAX-RS Whiteboard services must be granted ServicePermission[interfaceName, REGISTER] where interface name is the relevant JAX-RS Whiteboard service interface name.

The Http Whiteboard implementation must be granted ServicePermission[*, GET] to retrieve the JAX-RS Whiteboard services from the service registry.

Bundles that need to introspect the state of the JAX-RS runtime will need ServicePermission[org.osgi.service.jaxrs.runtime.JaxrsServiceRuntime, GET] to obtain the JAX-RS Service Runtime service and access the DTO types.

This specification does not require that the JAX-RS Whiteboard implementation is granted All Permission or wraps calls to the JAX-RS Whiteboard services in a doPrivileged block. Therefore, it is the responsibility of the JAX-RS Whiteboard services to use a doPrivileged block when performing privileged operations.