Differences between revisions 4 and 5
Revision 4 as of 2006-10-20 21:38:25
Size: 8112
Editor: JeremyBoynes
Comment:
Revision 5 as of 2009-09-20 22:48:40
Size: 8112
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

Proposal for how components access runtime-provided resources

Recent discussions on tuscany-dev raised the question of how an implementation could access resources provided by an SCA runtime environment. This was raised in conjunction with providing support for JPA (javax.persistence) and how the implementation would be able to access an EntityManager or EntityManagerFactory. However, this issue pertains to any service not modeled as a business service accessible through normal SCA Assembly.

This has been raised in the OSOA Specification Java working group in conjunction with Issue 68 Using @Resource and other Common Annotations.

Resource

A resource is a reference to a service provided by the environment in which a component implementation is running. Whereas an SCA Reference is used to declare a dependency on a service provided by another SCA component or binding, a Resource is used to declare a dependency that an implementation has on a service provided by the runtime infrastructure. As such, the type of a Resource is specific to the implementation type although the underlying implementation may be accessible from multiple implementation types. For example, the Java implementation type may support access to a relational database through a Resource with a type of javax.sql.DataSource whereas a C++ implementation type may support access to the same database through an ODBC Resource.

Access to resources is subject to Policy constraints in the same manner as access to other local services.

Accessing Resources from Component Implementations

A component may declare a dependency on a Resource by:

  • Using the org.osoa.annotation.Resource annotation
  • Using the javax.annotation.Resource annotation
  • Using a XML sidefile

The OSOA @Resource annotation has semantics aligned with the OSOA programming model such as the specification of authentication through Policy declaration; the semantics of javax.annotation.Resource are specified by JSR-250 Common Annotations.

The set of resources dependencies declared by an implementation is the union of all resources declared through these mechanisms. It is an error for two resource declarations to have the same name.

OSOA @Resource Annotation

The @Resource annotation has the following attributes:

  • name - the name of the reference

  • optional - whether a value is optional, defaults to false

The @Resource annotation may be applied to a protected or public field. The Resource service contract is determined by the type of the field and the default name of the Resource is the name of the field.

The @Resource annotation may be applied to a protected or public method. The method must be a valid JavaBean setter method: its name must begin with set, it must have a return type of void, and it must have a single parameter. The Resource service contract is determined by the type of the method parameter and the default name of the Resource is the JavaBean property name corresponding to the method.

The @Resource annotation may be applied to a parameter on a protected or public constructor. The service contact is determined by the type of the parameter and the default name of the Resource is the name of the type of the parameter as returned by Class.getName(). It is recommended that implementation developers provide a more meaningful name than this default.

Any @Resource annotations applied to other class Members (including private, package private, static or final fields and methods) must be ignored and will not be injected.

The set of resource dependencies declared is the union of all resources declared by the implementation class and its superclasses.

@Resource Common Annotation

A resource dependency may be declared using the @Resource Common Annotation. The attributes and rules for where the annotation can be used are defined by the JSR-250 Common Annotations 1.0 specification.

Using an XML sidefile

TODO we should have a way of declaring resource dependencies for implementations without using annotations

Use of JNDI

A SCA Implementation type is not required to provide components with a default JNDI Naming Context or to bind Resources into JNDI. Portable applications must not assume that they have access to the JNDI contexts provided by Java Enterprise Edition.

Applications seeking to dynamically look resources up in JNDI should declare a dependency on a javax.naming.Context resource:

  public class MyImpl {
     @Resource
     public Context compEnv;

     public void someServiceMethod() {
         DataSource ds = (DataSource) compEnv.lookup("someDatabase");
     }

Configuring Resources

A SCA Runtime environment may support the definition of resources that it should make available to applications that it is running. This definition may be part of the configuration of the runtime or may be part of the environment in which SCA is running. For example, an SCA Runtime associated with a Java Enterprise Edition managed environment may provided access to its resources. Every resource made available in this way must have a name that is unique within the scope of the runtime.

The configuration of these resources, including the mapping to any provided by other local environments, is outside the scope of this specification.

References to these resources can be bound in the following ways:

  • Through configuration of the Component being implemented
  • Through defaulting mechanisms in the resource dependency declaration

Configuring Resources for a Component

The resources declared by an implementation may be defined in the SCDL used to define a component that it is implementing. The SCDL schema is modified as follows:

  <complexType name="Resource" abstract="true">
    <attribute name="name" type="NCName" use="required"/>
    <attribute name="mappedName" type="string" use="optional"/>
    <anyAttribute namespace="##any" processContents="lax"/>
  </complexType>

The value of the @name attribute denotes the name of the resource declared by the implementation.

The value of the @mappedName attribute denotes the name of the resource provided by the runtime environment. If not value is supplied, a default service must be provided by the runtime environment; it is recommended that the runtime use the value of the @name attribute to locate a suitable resource. The format of the mapped name is specific to the runtime environment.

The Java implementation type is extended as follows:

    <complexType name="JavaImplementation">
        <complexContent>
            <extension base="sca:Implementation">
                <sequence>
                    <element name="resource" type="sca:Resource" minOccurs="0" maxOccurs="unbounded" />
                    <any namespace="##other" processContents="lax" minOccurs="0" maxOccurs="unbounded" />
                </sequence>
                <attribute name="class" type="NCName" use="required" />
                <anyAttribute namespace="##any" processContents="lax" />
            </extension>
        </complexContent>
    </complexType>

Example showing how a Java implementation can be connected to DataSource

  public class MyImpl {
    @Resource public DataSource myDS;
  }

  <component name="MyComponent">
    <implementation.java class="example.MyImpl">
      <resource name="myDS" mappedName="java:comp/env/LocalDB"/>
    </implementation.java>
  </component>

Configuration by Default

An implementation may provide default values for the mapping in the declaration using the "mappedName" attribute of the annotation or XML definition.

  public class MyImpl {
    @org.osoa.annotation.Resource(mappedName="SomeDB")
    public DataSource myDS;

    @javax.annotation.Resource(mappedName="java:comp/env/EntityManager")
    public EntityManager em;
  }

Any value specified in this manner is overridden by configuration at the Component level.

Tuscany/SpecProposals/Resources (last edited 2009-09-20 22:48:40 by localhost)