001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package javax.jbi.component;
018    
019    import javax.jbi.messaging.MessageExchange;
020    import javax.jbi.servicedesc.ServiceEndpoint;
021    
022    import org.w3c.dom.Document;
023    import org.w3c.dom.DocumentFragment;
024    
025    /**
026     * This interface, implemented by component implementations, allows
027     * the JBI implementation to query the component for various types
028     * of information. This includes:
029     * <ul>
030     *   <li>The component's life cycle control interface.</li>
031     *   <li>The component's service unit manager, for handling deployments.</li>
032     *   <li>A method for querying service metadata describing services
033     *       provided by this component.</li>
034     *   <li>"Policy" methods that are called by the JBI implementation to
035     *       query if proposed matches of this component to a provider (or
036     *       consumer) are acceptable, according to this component's policies.</li>
037     *   <li>Endpoint reference (EPR) resolution. Some components will provide
038     *       the ability to resolve EPRs (typically binding components). This
039     *       ability to resolve EPRs is used by JBI to facilitate resolution of
040     *       EPRs received by service consumers.</li>
041     *
042     * The name of the class that implements this interface for a component is
043     * specified in the installation descriptor for that component.
044     *
045     * @author JSR208 Exert Group
046     */
047    public interface Component {
048    
049        /**
050         * Get the life cycle control interface for this component. This interface
051         * allows the JBI implementation to control the running state of this component.
052         *
053         * This method must be called before any other methods of this interface are
054         * called. In addition, the JBI implementation must call the init() method of
055         * the component life cycle returned by this method before calling any other
056         * methods on this interface, or the component life cycle interface.
057         *
058         * @return the life cycle control interface for this component; must be non-null.
059         */
060        ComponentLifeCycle getLifeCycle();
061    
062        /**
063         * Get the Service Unit manager for this component. If this component does not
064         * support deployments, it must return null.
065         *
066         * @return the ServiceUnitManager for this component, or null if there is none.
067         */
068        ServiceUnitManager getServiceUnitManager();
069    
070        /**
071         * Retrieves a DOM representation containing metadata which describes the service
072         * provided by this component, through the given endpoint. The result can use WSDL
073         * 1.1 or WSDL 2.0.
074         *
075         * @param endpoint the service endpoint.
076         * @return the description for the specified service endpoint.
077         */
078        Document getServiceDescription(ServiceEndpoint endpoint);
079    
080        /**
081         * This method is called by JBI to check if this component, in the role of provider
082         * of the service indicated by the given exchange, can actually perform the operation
083         * desired.
084         *
085         * @param endpoint the endpoint to be used by the consumer; must be non-null.
086         * @param exchange the proposed message exchange to be performed; must be non-null.
087         * @return true if this provider component can interact with the described consumer
088         *         to perform the given exchange.
089         */
090        boolean isExchangeWithConsumerOkay(ServiceEndpoint endpoint, MessageExchange exchange);
091    
092        /**
093         * This method is called by JBI to check if this component, in the role of consumer
094         * of the service indicated by the given exchange, can actually interact with the
095         * provider properly. The provider is described by the given endpoint and the service
096         * description supplied by that endpoint.
097         *
098         * @param endpoint the endpoint to be used by the provider; must be non-null.
099         * @param exchange the proposed message exchange to be performed; must be non-null.
100         * @return true if this consumer component can interact with the described provider
101         *         to perform the given exchange.
102         */
103        boolean isExchangeWithProviderOkay(ServiceEndpoint endpoint, MessageExchange exchange);
104    
105        /**
106         * Resolve the given endpoint reference. This is called by JBI when it is attempting to
107         * resolve the given EPR on behalf of a component.
108         *
109         * If this component returns a non-null result, it must conform to the following:
110         * <ul>
111         *   <li>This component implements the ServiceEndpoint returned.</li>
112         *   <li>The result must not be registered or activated with the JBI implementation.</li>
113         * </ul>
114         *
115         * Dynamically resolved endpoints are distinct from static ones; they must not be activated
116         * (see {@link javax.jbi.component.ComponentContext#activateEndpoint(javax.xml.namespace.QName, String)}),
117         * nor registered (see {@link ComponentContext}) by components. They can only be used to address
118         * message exchanges; the JBI implementation must deliver such exchanges to the component that
119         * resolved the endpoint reference (see
120         * {@link javax.jbi.component.ComponentContext#resolveEndpointReference(org.w3c.dom.DocumentFragment)}).
121         *
122         * @param epr the endpoint reference, in some XML dialect understood by the appropriate component
123         *            (usually a binding); must be non-null.
124         * @return the service endpoint for the EPR; null if the EPR cannot be resolved by this component.
125         */
126        ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
127    }