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 }