Author: antelder
Date: Thu Apr 8 11:18:44 2010
New Revision: 931881
URL: http://svn.apache.org/viewvc?rev=931881&view=rev
Log:
Latest OASIS API code for componentcontext, Ileagalarg exception added to
methods and cast generics simplified, formating and javadoc
Modified:
tuscany/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/ComponentContext.java
Modified:
tuscany/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/ComponentContext.java
URL:
http://svn.apache.org/viewvc/tuscany/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/ComponentContext.java?rev=931881&r1=931880&r2=931881&view=diff
==============================================================================
---
tuscany/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/ComponentContext.java
(original)
+++
tuscany/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/ComponentContext.java
Thu Apr 8 11:18:44 2010
@@ -1,5 +1,5 @@
/*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
* OASIS trademark, IPR and other policies apply.
*/
package org.oasisopen.sca;
@@ -7,113 +7,188 @@ package org.oasisopen.sca;
import java.util.Collection;
/**
- * Interface providing programmatic access to a component's SCA context as an
alternative to injection.
- * It provides access to reference and property values for the component and
provides a mechanism for
- * obtaining a reference to a service that can be passed to other components.
- * <p/>
- * SCA components obtain an instance of this interface through injection.
Non-SCA client code may also
- * obtain an instance through runtime-specific mechanisms.
+ * The ComponentContext interface is used to obtain contextual information
+ * about the SCA component which is executing at the time the API is
+ * invoked.
*
- * @version $Rev$ $Date$
+ * <p>Note: An SCA component can obtain a service reference either through
+ * injection or programmatically through the ComponentContext API. Using
+ * reference injection is the recommended way to access a service, since it
+ * results in code with minimal use of middleware APIs. The ComponentContext
+ * API is provided for use in cases where reference injection is not possible.
*/
public interface ComponentContext {
- /**
- * Returns the absolute URI of the component within the SCA Domain.
- *
- * @return the absolute URI of the component
- */
- String getURI();
/**
- * Cast a type-safe reference to a CallableReference.
- * Converts a type-safe reference to an equivalent CallableReference; if
the target refers to a service
- * then a ServiceReference will be returned, if the target refers to a
callback then a CallableReference
- * will be returned.
- *
- * @param target a reference proxy provided by the SCA runtime
- * @param <B> the Java type of the business interface for the reference
- * @param <R> the type of reference to be returned
- * @return a CallableReference equivalent for the proxy
- * @throws IllegalArgumentException if the supplied instance is not a
reference supplied by the SCA runtime
+ * Returns the absolute URI of the component within the SCA domain.
+ *
+ * @return the absolute URI of the component within the SCA domain.
*/
- <B, R extends ServiceReference<B>> R cast(B target) throws
IllegalArgumentException;
-
- /**
- * Returns a proxy for a reference defined by this component.
- *
- * @param businessInterface the interface that will be used to invoke the
service
- * @param referenceName the name of the reference
- * @param <B> the Java type of the business interface for the reference
- * @return an object that implements the business interface
- */
- <B> B getService(Class<B> businessInterface, String referenceName);
+ String getURI();
/**
- * Returns a ServiceReference for a reference defined by this component.
+ * Returns a typed service proxy object for a reference defined by the
+ * current component, where the reference has multiplicity 0..1 or 1..1.
*
- * @param businessInterface the interface that will be used to invoke the
service
- * @param referenceName the name of the reference
- * @param <B> the Java type of the business interface for the reference
- * @return a ServiceReference for the designated reference
- */
- <B> ServiceReference<B> getServiceReference(Class<B> businessInterface,
String referenceName);
+ * @param <B> the Java type that is implemented by the returned proxy
+ * object.
+ * @param businessInterface the Class object for the Java type that
+ * is implemented by the returned proxy object.
+ * @param referenceName the name of the service reference.
+ * @return a proxy for the reference defined by the current component.
+ * Returns null if the named reference has no target service
+ * configured.
+ * @exception IllegalArgumentException if the reference has multiplicity
+ * greater than one, or the component does not have the
reference
+ * named by <code>referenceName</code>, or the interface of the
named
+ * reference is not compatible with the interface supplied in
+ * the <code>businessInterface</code> parameter.
+ */
+ <B> B getService(Class<B> businessInterface, String referenceName)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a ServiceReference object for a reference defined by the current
+ * component, where the reference has multiplicity 0..1 or 1..1.
+ *
+ * @param <B> the Java type of the reference that is associated with
+ * the returned object.
+ * @param businessInterface the Class object for the Java type that
+ * is associated with the returned object.
+ * @param referenceName the name of the service reference.
+ * @return a ServiceReference object for a reference defined by the
current
+ * component, where the reference has multiplicity 0..1 or 1..1.
+ * Returns null if the named reference has no target service
+ * configured.
+ * @exception IllegalArgumentException if the reference has multiplicity
+ * greater than one, or the component does not have the
reference
+ * named by <code>referenceName</code>, or the interface of the
named
+ * reference is not compatible with the interface supplied in
+ * the <code>businessInterface</code> parameter.
+ */
+ <B> ServiceReference<B> getServiceReference(Class<B> businessInterface,
+ String referenceName)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a list of typed service proxies for a reference defined by the
current
+ * component, where the reference has multiplicity 0..n or 1..n.
+ *
+ * @param <B> the Java type that is implemented by the returned proxy
+ * objects.
+ * @param businessInterface the Class object for the Java type that
+ * is implemented by the returned proxy objects.
+ * @param referenceName the name of the service reference.
+ * @return a collection of proxy objects for the reference, one for
each target
+ * service to which the reference is wired, where each proxy
object
+ * implements the interface B contained in the
+ * <code>businessInterface</code> parameter. The collection is
empty if the
+ * reference is not wired to any target services.
+ * @exception IllegalArgumentException if the reference has multiplicity
+ * greater other than 0..1 or 1..1, or the component does not
have the reference
+ * named by <code>referenceName</code>, or the interface of the
named
+ * reference is not compatible with the interface supplied in
+ * the <code>businessInterface</code> parameter.
+ */
+ <B> Collection<B> getServices(Class<B> businessInterface,
+ String referenceName)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a list of typed ServiceReference objects for a reference
defined by the current
+ * component, where the reference has multiplicity 0..n or 1..n.
+ *
+ * @param <B> the Java type that is associated with returned proxy
+ * objects.
+ * @param <B> the Java type of the reference that is associated with
+ * the returned object.
+ * @param referenceName the name of the service reference.
+ * @return a collection of ServiceReference objects for the reference,
one for each target
+ * service to which the reference is wired, where each proxy
object implements
+ * the interface B contained in the
<code>businessInterface</code> parameter.
+ * The collection is empty if the reference is not wired to any
target services.
+ * @exception IllegalArgumentException if the reference has multiplicity
+ * greater other than 0..1 or 1..1, or the component does not
have the reference
+ * named by <code>referenceName</code>, or the interface of the
named
+ * reference is not compatible with the interface supplied in
+ * the <code>businessInterface</code> parameter.
+ */
+ <B> Collection<ServiceReference<B>> getServiceReferences(
+ Class<B> businessInterface, String referenceName)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a ServiceReference that can be used to invoke this component
+ * over the designated service.
+ *
+ * @param <B> the Java type of the reference that is associated with
+ * the returned object.
+ * @param businessInterface the Class object for the Java type that
+ * is associated with the returned object.
+ * @return a ServiceReference that can be used to invoke this
+ * component over the designated service.
+ * @exception IllegalArgumentException if the component does not have a
service
+ * which implements the interface identified by the <code>
+ * businessinterface</code> parameter.
+ */
+ <B> ServiceReference<B> createSelfReference(Class<B> businessInterface)
+ throws IllegalArgumentException;
+
+ /**
+ * Returns a ServiceReference that can be used to invoke this component
+ * over the designated service. The <code>serviceName</code> parameter
explicitly names
+ * the service with which the returned ServiceReference is associated.
+ *
+ * @param <B> the Java type of the reference that is associated with
+ * the returned object.
+ * @param businessInterface the Class object for the Java type that
+ * is associated with the returned object.
+ * @param serviceName the service name with which the returned
ServiceReference
+ * is associated.
+ * @return a ServiceReference that can be used to invoke this component
+ * over the designated service.
+ * @exception IllegalArgumentException if the component does not have a
service
+ * with the name identified by the <code>serviceName</code>
parameter, or
+ * if the named service does not implement the interface
identified by the
+ * <code>businessinterface</code> parameter.
+ */
+ <B> ServiceReference<B> createSelfReference(Class<B> businessInterface,
+ String serviceName)
+ throws IllegalArgumentException;
/**
* Returns the value of an SCA property defined by this component.
*
- * @param type the Java type to be returned for the property
- * @param propertyName the name of the property whose value should be
returned
- * @param <B> the Java type of the property
- * @return the property value
+ * @param <B> the property type.
+ * @param type the Class object for the property type.
+ * @param propertyName the property name.
+ * @return The value of an SCA property defined by this component, or
null if
+ * the property is not configured.
+ * @exception IllegalArgumentException if the component does not have a
property
+ * with the name identified by the <code>propertyName</code>
parameter, or
+ * if the named property type is not compatible with the
<code>type</code>
+ * parameter.
*/
- <B> B getProperty(Class<B> type, String propertyName);
+ <B> B getProperty(Class<B> type, String propertyName)
+ throws IllegalArgumentException;
/**
- * Returns a ServiceReference that can be used to invoke this component
over the default service.
+ * Casts a type-safe reference to a ServiceReference.
*
- * @param businessInterface the interface that will be used to invoke the
service
- * @param <B> the Java type of the business interface for the reference
- * @return a ServiceReference that will invoke this component
+ * @param <B> the Java type of the reference that is associated with
+ * the returned object.
+ * @param target the type-safe reference proxy that implements
interface <B>.
+ * @return a type-safe reference to a ServiceReference.
*/
- <B> ServiceReference<B> createSelfReference(Class<B> businessInterface);
+ <B> ServiceReference<B> cast(B target)
+ throws IllegalArgumentException;
/**
- * Returns a ServiceReference that can be used to invoke this component
over the designated service.
+ * Returns the RequestContext for the current SCA service request.
*
- * @param businessInterface the interface that will be used to invoke the
service
- * @param serviceName the name of the service to invoke
- * @param <B> the Java type of the business interface for the reference
- * @return a ServiceReference that will invoke this component
- */
- <B> ServiceReference<B> createSelfReference(Class<B> businessInterface,
String serviceName);
-
- /**
- * Returns the context for the current SCA service request, or null if
there is no current request
- * or if the context is unavailable.
- *
- * @return the SCA request context; may be null
+ * @return the RequestContext for the current SCA service request when
+ * invoked during the execution of a component service method or
+ * callback method. Returns null in all other cases.
*/
RequestContext getRequestContext();
-
-
- /* ******************** Contribution for issue TUSCANY-2281
******************** */
-
- /**
- * Returns a Collection of typed service proxies for a business interface
type and a reference name.
- * @param businessInterface the interface that will be used to invoke the
service
- * @param referenceName the name of the reference
- * @param <B> the Java type of the business interface for the reference
- * @return a Collection of objects that implements the business interface
- */
- <B> Collection<B> getServices(Class<B> businessInterface, String
referenceName);
-
-
- /**
- * Returns a Collection of typed service reference for a business
interface type and a reference name.
- * @param businessInterface the interface that will be used to invoke the
service
- * @param referenceName the name of the reference
- * @param <B> the Java type of the business interface for the reference
- * @return a Collection of objects that implements the business interface
- */
- <B> Collection<ServiceReference<B>> getServiceReferences(Class<B>
businessInterface, String referenceName);
}
