org.apache.felix.dm.annotation.api

Annotation Type ResourceAdapterService

@Retention(value=CLASS)
@Target(value=TYPE)
public @interface ResourceAdapterService

Annotates a class as a Resource adapter service. Resource adapters are things that adapt a resource instead of a service, and provide an adapter service on top of this resource. Resources are an abstraction that is introduced by the dependency manager, represented as a URL. They can be implemented to serve resources embedded in bundles, somewhere on a file system or in an http content repository server, or database.

The adapter will be applied to any resource that matches the specified filter condition, which can match some part of the resource URL (with "path", "protocol", "port", or "host" filters). For each matching resource an adapter will be created based on the adapter implementation class. The adapter will be registered with the specified interface and with any extra service properties you supply here. Moreover, the following service properties will be propagated from the resource URL:

• "host": this property exposes the host part of the resource URL
• "path": the resource URL path
• "protocol": the resource URL protocol
• "port": the resource URL port

Usage Examples

Here, the "VideoPlayer" service provides a video service on top of any movie resources, with service properties "host"/"port"/"protocol"/"path" extracted from the resource URL:

 
 @ResourceAdapterService(filter = "(&(path=/videos/*.mkv)(host=localhost))", propagate = true)
 public class VideoPlayerImpl implements VideoPlayer {
     // Injected by reflection
     URL resource;
     
     void play() {} // play video referenced by this.resource     
     void stop() {} // stop playing the video
     void transcode() {} // ...
 }
 

And here is an example of a VideoProvider, which provides some videos using a web URL. Notice that Resource providers need to depend on the DependencyManager API:

 import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.HashMap;
 import java.util.Map;
 
 import org.apache.felix.dm.ResourceHandler;
 import org.apache.felix.dm.ResourceUtil;
 import org.apache.felix.dm.annotation.api.Component;
 import org.apache.felix.dm.annotation.api.Init;
 import org.apache.felix.dm.annotation.api.ServiceDependency;
 import org.osgi.framework.BundleContext;
 import org.osgi.framework.Filter;
 import org.osgi.framework.InvalidSyntaxException;
 
 @Component
 public class VideoProvider
 {
     // Injected by reflection
     private volatile BundleContext context;
     // List of known resource handlers
     private Map<ResourceHandler, Filter> m_handlers = new HashMap<ResourceHandler, Filter>();
     // List of known video resources
     private URL[] m_videos;
 
     @Init
     void init() throws MalformedURLException
     {
        m_videos = new URL[] {
                new URL("http://localhost:8080/videos/video1.mkv"),
                new URL("http://localhost:8080/videos/video2.mkv"),
         };
     }
 
     // Track resource handlers
     @ServiceDependency(required = false)
     public void add(Map<String, String> serviceProperties, ResourceHandler handler) throws InvalidSyntaxException
     {
         String filterString = serviceProperties.get("filter");
         filterString = (filterString != null) ? filterString : "(path=*)";
         Filter filter = context.createFilter(filterString);
         synchronized (this)
         {
             m_handlers.put(handler, filter);
         }
         for (URL video : m_videos)
         {
             if (filter.match(ResourceUtil.createProperties(video)))
             {
                 handler.added(video);
             }
         }
     }
 }
 

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String	filter The filter condition to use with the resource.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String	changed The callback method to be invoked when the Resource has changed.
java.lang.String	factoryMethod Sets the static method used to create the AdapterService implementation instance.
boolean	propagate true if properties from the resource should be propagated to the service properties.
Property[]	properties Additional properties to use with the adapter service registration
java.lang.Class<?>[]	provides The interface(s) to use when registering adapters

Element Detail

filter

public abstract java.lang.String filter

The filter condition to use with the resource.

provides

public abstract java.lang.Class<?>[] provides

The interface(s) to use when registering adapters

Default:

{}

properties

public abstract Property[] properties

Additional properties to use with the adapter service registration

Default:

{}

propagate

public abstract boolean propagate

true if properties from the resource should be propagated to the service properties.

Default:

false

changed

public abstract java.lang.String changed

The callback method to be invoked when the Resource has changed.

Default:

""

factoryMethod

public abstract java.lang.String factoryMethod

Sets the static method used to create the AdapterService implementation instance.

Default:

""