/* * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved. * OASIS trademark, IPR and other policies apply. */ package org.oasisopen.sca; import java.util.Collection; /** * The ComponentContext interface is used to obtain contextual information * about the SCA component which is executing at the time the API is * invoked. * *
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 within the SCA domain.
*/
String getURI();
/**
* 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 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 referenceName
, or the interface of the named
* reference is not compatible with the interface supplied in
* the businessInterface
parameter.
*/
B getService(Class 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 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 referenceName
, or the interface of the named
* reference is not compatible with the interface supplied in
* the businessInterface
parameter.
*/
ServiceReference getServiceReference(Class 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 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
* businessInterface
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 referenceName
, or the interface of the named
* reference is not compatible with the interface supplied in
* the businessInterface
parameter.
*/
Collection getServices(Class 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 the Java type that is associated with returned proxy
* objects.
* @param 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 businessInterface
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 referenceName
, or the interface of the named
* reference is not compatible with the interface supplied in
* the businessInterface
parameter.
*/
Collection
* businessinterface
parameter.
*/
ServiceReference createSelfReference(Class businessInterface)
throws IllegalArgumentException;
/**
* Returns a ServiceReference that can be used to invoke this component
* over the designated service. The serviceName
parameter explicitly names
* the service with which the returned ServiceReference is associated.
*
* @param 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 serviceName
parameter, or
* if the named service does not implement the interface identified by the
* businessinterface
parameter.
*/
ServiceReference createSelfReference(Class businessInterface,
String serviceName)
throws IllegalArgumentException;
/**
* Returns the value of an SCA property defined by this component.
*
* @param 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 propertyName
parameter, or
* if the named property type is not compatible with the type
* parameter.
*/
B getProperty(Class type, String propertyName)
throws IllegalArgumentException;
/**
* Casts a type-safe reference to a ServiceReference.
*
* @param the Java type of the reference that is associated with
* the returned object.
* @param target the type-safe reference proxy that implements interface .
* @return a type-safe reference to a ServiceReference.
*/
ServiceReference cast(B target)
throws IllegalArgumentException;
/**
* Returns the RequestContext for the current SCA service request.
*
* @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();
}