ws-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Ws Wiki] Update of "Tuscany/SpecProposals/Constructors" by JeremyBoynes
Date Wed, 07 Jun 2006 23:36:03 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Ws Wiki" for change notification.

The following page has been changed by JeremyBoynes:
http://wiki.apache.org/ws/Tuscany/SpecProposals/Constructors

New page:
A proposal to allow the use of non-default constructors in the Java Implementation model.

== Rationale ==

The 0.9 version of the Java Client and Implementation Specification (Java Spec) requires that
all implementations have a public, no-argument constructor that can be used by the container
to instantiate instances of the component. All Property and Reference values are injected
directly into fields or through setter methods.

However, some Java programmers prefer to pass these type of values in through constructor
parameters. There are some cases where this is necessary, for example when the value is going
to be stored in a final field. This proposal provides a mechanism that allows this style of
injection as an additional alternative to the existing methods.

== Proposal ==

A Java implementation class must provide a public or protected constructor that can be used
by the container to instantiate the component. The constructor may contain parameters; in
the presence of such parameters, the container will pass the applicable property or reference
values when invoking the constructor. Any values not supplied in this manner will be set into
the field or passed to the setter method associated with the property or reference before
any service method is invoked.

The constructor to use must be selected by the container as follows:
 * A declared constructor annotated with a @Constructor annotation.
 * A declared constructor that unambiguously identifies all property and reference values.
 * A no-argument constructor.

The @Constructor annotation must only be specified on one constructor; the container must
report an error if multiple constructors are so annotated. 

The property or reference associated with each parameter of a constructor is identified by
name in the @Constructor annotation (if present), though the presence of a @Property or @Reference
annotation on the parameter declaration, or by uniquely matching the parameter type to the
type of a property or reference defined by annotation of a field or setter method or declared
in a sidefile.

Cyclic references between components may be handled by the container in one of two ways:
 * if any reference in the cycle is optional, then the container may inject a null value during
construction, followed by injection of a reference to the target before invoking any service.
 * the container may inject a proxy to the target service; invocation of methods on the proxy
may result in a ServiceUnavailableException

== Annotation changes ==

This proposal introduces a new annotation that is used to identify the constructor:
{{{
package org.osoa.sca.annotations;
@Target(CONSTRUCTOR)
@Retention(RUNTIME)
public @interface Constructor {
    /** List of property or reference names associated with each parameter */
    String[] value();
}
}}}
In addition, the Property and Reference annotations are extended to allow placement on parameters:
{{{
@Target({METHOD, FIELD, PARAMETER})
@Retention(RUNTIME)
public @interface Property {
    ...
}
}}}

== Examples ==
{{{
/** Simple class taking a single property value */
public class Impl1 {
    String someProperty;
    public Impl1(String propval) {...}
}
}}}
{{{
/** Simple class taking a property and reference in the constructor;
 * The values are not injected into the fields.
 *//
public class Impl2 {
    public String someProperty;
    public SomeService someReference;
    public Impl2(String a, SomeService b) {...}
}
}}}
{{{
/** Class declaring a named property and reference through the constructor */
public class Impl3 {
    @Constructor({"someProperty", "someReference"})
    public Impl3(String a, SomeService b) {...}
}
}}}
{{{
/** Class declaring a named property and reference through parameters */
public class Impl3b {
    public Impl3b(
        @Property("someProperty") String a, 
        @Reference("someReference) SomeService b
        ) {...}
}
}}}
{{{
/** Additional property set through a method */
public class Impl4 {
    public String someProperty;
    public SomeService someReference;
    public Impl2(String a, SomeService b) {...}
    @Property public void setAnotherProperty(int x) {...}
}
}}}

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@ws.apache.org
For additional commands, e-mail: general-help@ws.apache.org


Mime
View raw message