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 }