001: /*
002: * BEGIN_HEADER - DO NOT EDIT
003: *
004: * The contents of this file are subject to the terms
005: * of the Common Development and Distribution License
006: * (the "License"). You may not use this file except
007: * in compliance with the License.
008: *
009: * You can obtain a copy of the license at
010: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
011: * See the License for the specific language governing
012: * permissions and limitations under the License.
013: *
014: * When distributing Covered Code, include this CDDL
015: * HEADER in each file and include the License file at
016: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
017: * If applicable add the following below this CDDL HEADER,
018: * with the fields enclosed by brackets "[]" replaced with
019: * your own identifying information: Portions Copyright
020: * [year] [name of copyright owner]
021: */
022:
023: /*
024: * @(#)Component.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.component;
030:
031: import javax.jbi.messaging.MessageExchange;
032: import javax.jbi.servicedesc.ServiceEndpoint;
033:
034: import javax.xml.namespace.QName;
035:
036: import org.w3c.dom.Document;
037: import org.w3c.dom.DocumentFragment;
038:
039: /**
040: * This interface, implemented by component implementations, allows the JBI
041: * implementation to query the component for various types of information. This
042: * includes:
043: * <ul>
044: * <li>The component's life cycle control interface.</li>
045: * <li>The component's service unit manager, for handling deployments.</li>
046: * <li>A method for querying service metadata describing services provided
047: * by this component.</li>
048: * <li>"Policy" methods that are called by the JBI implementation to query if
049: * proposed matches of this component to a provider (or consumer) are
050: * acceptable, according to this component's policies.</li>
051: * <li>Endpoint reference (EPR) resolution. Some components will provide
052: * the ability to resolve EPRs (typically binding components). This
053: * ability to resolve EPRs is used by JBI to facilitate resolution
054: * of EPRs received by service consumers.</li>
055: * </ul>
056: * <p>
057: * The name of the class that implements this interface for a component is
058: * specified in the installation descriptor for that component.
059: *
060: * @author JSR208 Expert Group
061: */
062: public interface Component {
063: /**
064: * Get the life cycle control interface for this component. This interface
065: * allows the JBI implementation to control the running state of this
066: * component.
067: * <p>
068: * This method must be called before any other methods of this interface
069: * are called. In addition, the JBI implementation must call the init()
070: * method of the component life cycle returned by this method before
071: * calling any other methods on this interface, or the component life cycle
072: * interface.
073: *
074: * @return the life cycle control interface for this component; must be
075: * non-null.
076: */
077: ComponentLifeCycle getLifeCycle();
078:
079: /**
080: * Get the Service Unit manager for this component. If this component does
081: * not support deployments, it must return <code>null</code>.
082: *
083: * @return the <code>ServiceUnitManager</code> for this component, or
084: * <code>null</code> if there is none.
085: */
086: ServiceUnitManager getServiceUnitManager();
087:
088: /**
089: * Retrieves a DOM representation containing metadata which describes the
090: * service provided by this component, through the given endpoint. The
091: * result can use WSDL 1.1 or WSDL 2.0.
092: *
093: * @param endpoint the service endpoint.
094: * @return the description for the specified service endpoint.
095: */
096: Document getServiceDescription(ServiceEndpoint endpoint);
097:
098: /**
099: * This method is called by JBI to check if this component, in the role of
100: * provider of the service indicated by the given exchange, can actually
101: * perform the operation desired.
102: *
103: * @param endpoint the endpoint to be used by the consumer; must be
104: * non-null.
105: * @param exchange the proposed message exchange to be performed; must be
106: * non-null.
107: * @return <code>true</code> if this provider component can perform the
108: * given exchange with the described consumer.
109: */
110: boolean isExchangeWithConsumerOkay(ServiceEndpoint endpoint,
111: MessageExchange exchange);
112:
113: /**
114: * This method is called by JBI to check if this component, in the role of
115: * consumer of the service indicated by the given exchange, can actually
116: * interact with the provider properly. The provider is described by the
117: * given endpoint and the service description supplied by that endpoint.
118: *
119: * @param endpoint the endpoint to be used by the provider; must be
120: * non-null.
121: * @param exchange the proposed message exchange to be performed; must be
122: * non-null.
123: * @return <code>true</code> if this consumer component can interact with
124: * the described provider to perform the given exchange.
125: */
126: boolean isExchangeWithProviderOkay(ServiceEndpoint endpoint,
127: MessageExchange exchange);
128:
129: /**
130: * Resolve the given endpoint reference. This is called by JBI when it is
131: * attempting to resolve the given EPR on behalf of a component.
132: * <p>
133: * If this component returns a non-null result, it must conform to the
134: * following:
135: * <ul>
136: * <li>This component implements the {@link ServiceEndpoint} returned.
137: * </li>
138: * <li>The result must not be registered or activated with the JBI
139: * implementation.</li>
140: * </ul>
141: *
142: * Dynamically resolved endpoints are distinct from static ones; they must
143: * not be activated (see {@link ComponentContext#activateEndpoint(QName,
144: * String)}), nor registered (see {@link ComponentContext}) by components.
145: * They can only be used to address message exchanges; the JBI
146: * implementation must deliver such exchanges to the component that resolved
147: * the endpoint reference (see {@link
148: * ComponentContext#resolveEndpointReference(DocumentFragment)}).
149: *
150: * @param epr the endpoint reference, in some XML dialect understood by
151: * the appropriate component (usually a binding); must be non-null.
152: * @return the service endpoint for the EPR; <code>null</code> if the
153: * EPR cannot be resolved by this component.
154: */
155: ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
156: }
|