/*
 * 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.
 * 
 * <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 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     <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     <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)
		    throws IllegalArgumentException;

    /**
     * Casts a type-safe reference to a ServiceReference.
     *
     * @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> 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();
}