SM-1455: Add JBI api to the specs subproject
git-svn-id: https://svn.apache.org/repos/asf/servicemix/smx4/specs/trunk@688675 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/jbi-api-1.0/pom.xml b/jbi-api-1.0/pom.xml
new file mode 100644
index 0000000..31970b7
--- /dev/null
+++ b/jbi-api-1.0/pom.xml
@@ -0,0 +1,63 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+
+ <!--
+
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.servicemix.specs</groupId>
+ <artifactId>specs</artifactId>
+ <version>1.1-SNAPSHOT</version>
+ </parent>
+
+ <groupId>org.apache.servicemix.specs</groupId>
+ <artifactId>org.apache.servicemix.specs.jbi-api-1.0</artifactId>
+ <packaging>bundle</packaging>
+ <version>1.1-SNAPSHOT</version>
+ <name>Apache ServiceMix Specs :: JBI API 1.0</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.geronimo.specs</groupId>
+ <artifactId>geronimo-activation_1.1_spec</artifactId>
+ <version>1.0.2</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.felix</groupId>
+ <artifactId>maven-bundle-plugin</artifactId>
+ <configuration>
+ <instructions>
+ <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName>
+ <Export-Package>javax.jbi*;version=1.0;-split-package:=merge-first</Export-Package>
+ <Import-Package>*</Import-Package>
+ <Implementation-Title>Apache ServiceMix</Implementation-Title>
+ <Implementation-Version>${project.version}</Implementation-Version>
+ </instructions>
+ <unpackBundle>true</unpackBundle>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/JBIException.java b/jbi-api-1.0/src/main/java/javax/jbi/JBIException.java
new file mode 100644
index 0000000..7427a7d
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/JBIException.java
@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi;
+
+/**
+ * JBIException is the top-level exception thrown by all JBI system components.
+ */
+public class JBIException extends Exception {
+
+ /**
+ * Creates a new instance of JBIException with an exception message.
+ * @param aMessage String describing this exception.
+ */
+ public JBIException(String aMessage) {
+ super(aMessage);
+ }
+
+ /**
+ * Creates a new instance of JBIException with the specified message and cause.
+ * @param aMessage String describing this exception.
+ * @param aCause Throwable which represents an underlying problem (or null).
+ */
+ public JBIException(String aMessage, Throwable aCause) {
+ super(aMessage, aCause);
+ }
+
+ /**
+ * Creates a new instance of JBIException with the specified cause.
+ * @param aCause Throwable which represents an underlying problem (or null).
+ */
+ public JBIException(Throwable aCause) {
+ super(aCause);
+ }
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/Bootstrap.java b/jbi-api-1.0/src/main/java/javax/jbi/component/Bootstrap.java
new file mode 100644
index 0000000..8fd5630
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/Bootstrap.java
@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import javax.jbi.JBIException;
+
+import javax.management.ObjectName;
+
+/**
+ * This interface is implemented by a JBI Component to provide any
+ * special processing required at install/uninstall time. The methods
+ * defined here are called by the JBI implementation during the installation
+ * (or uninstallation) of the component that, among other things, supplies
+ * an implementation of this interface.
+ *
+ * Initialization/cleanup tasks such as creation/deletion of directories,
+ * files, and database tables can be done by the onInstall() and onUninstall()
+ * methods, respectively. This also allows the component to terminate the
+ * installation or uninstallation in the event of an error.
+ *
+ * After calling onInstall() or onUninstall(), regardless of outcome, the JBI
+ * implementation must call the cleanUp() method afterwards. Similarly, if
+ * init(InstallationContext) fails with an exception, the JBI implementation
+ * must call the cleanUp() method.
+ *
+ * Component implementors should note that there is no guarantee that the same
+ * instance of its Bootstrap implementation will be used during both install
+ * and uninstall operations on the component. Data that need to be retained
+ * between installation-time and uninstallation-time must be persisted in such
+ * as fashion that a separate instance of the bootstrap class can find them,
+ * despite component or system shutdown.
+ *
+ * @author JSR208 Exert Group
+ */
+public interface Bootstrap {
+
+ /**
+ * Initializes the installation environment for a component. This method is
+ * expected to save any information from the installation context that may
+ * be needed by other methods.
+ *
+ * If the component needs to register an optional installer configuration MBean,
+ * it MUST do so during execution of this method, or the getExtensionMBean()
+ * method.
+ *
+ * This method must be called after the installation root (available through
+ * the installContext parameter) is prepared.
+
+ * @param installContext the context containing information from the install
+ * command and from the component installation ZIP file;
+ * this must be non-null.
+ * @throws JBIException when there is an error requiring that the installation
+ * be terminated
+ */
+ void init(InstallationContext installContext) throws JBIException;
+
+ /**
+ * Cleans up any resources allocated by the bootstrap implementation,
+ * including performing deregistration of the extension MBean, if applicable.
+ *
+ * This method must be called after the onInstall() or onUninstall() method
+ * is called, whether it succeeds or fails. It must be called after init() is
+ * called, if init() fails by throwing an exception.
+ *
+ * @throws JBIException if the bootstrap cannot clean up allocated resources
+ */
+ void cleanUp() throws JBIException;
+
+ /**
+ * Obtains the ObjectName of the optional installer configuration MBean. If
+ * none is provided by this component, this method must return null.
+ *
+ * This method must be called before onInstall() (or onUninstall()) is called
+ * by the JBI implementation.
+ *
+ * @return ObjectName of the optional installer configuration MBean; returns null
+ * if there is no such MBean
+ */
+ ObjectName getExtensionMBeanName();
+
+ /**
+ * Called at the beginning of installation of a component to perform any special
+ * installation tasks required by the component.
+ *
+ * This method must not be called if the init() method failed with an exception.
+ *
+ * @throws JBIException when there is an error requiring that the installation be
+ * terminated
+ */
+ void onInstall() throws JBIException;
+
+ /**
+ * Called at the beginning of uninstallation of a component to perform any special
+ * uninstallation tasks required by the component.
+ *
+ * This method must not be called if the init() method failed with an exception.
+ *
+ * @throws JBIException when there is an error requiring that the uninstallation be
+ * terminated.
+ */
+ void onUninstall() throws JBIException;
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/Component.java b/jbi-api-1.0/src/main/java/javax/jbi/component/Component.java
new file mode 100644
index 0000000..d46a4cd
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/Component.java
@@ -0,0 +1,127 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import javax.jbi.messaging.MessageExchange;
+import javax.jbi.servicedesc.ServiceEndpoint;
+
+import org.w3c.dom.Document;
+import org.w3c.dom.DocumentFragment;
+
+/**
+ * This interface, implemented by component implementations, allows
+ * the JBI implementation to query the component for various types
+ * of information. This includes:
+ * <ul>
+ * <li>The component's life cycle control interface.</li>
+ * <li>The component's service unit manager, for handling deployments.</li>
+ * <li>A method for querying service metadata describing services
+ * provided by this component.</li>
+ * <li>"Policy" methods that are called by the JBI implementation to
+ * query if proposed matches of this component to a provider (or
+ * consumer) are acceptable, according to this component's policies.</li>
+ * <li>Endpoint reference (EPR) resolution. Some components will provide
+ * the ability to resolve EPRs (typically binding components). This
+ * ability to resolve EPRs is used by JBI to facilitate resolution of
+ * EPRs received by service consumers.</li>
+ *
+ * The name of the class that implements this interface for a component is
+ * specified in the installation descriptor for that component.
+ *
+ * @author JSR208 Exert Group
+ */
+public interface Component {
+
+ /**
+ * Get the life cycle control interface for this component. This interface
+ * allows the JBI implementation to control the running state of this component.
+ *
+ * This method must be called before any other methods of this interface are
+ * called. In addition, the JBI implementation must call the init() method of
+ * the component life cycle returned by this method before calling any other
+ * methods on this interface, or the component life cycle interface.
+ *
+ * @return the life cycle control interface for this component; must be non-null.
+ */
+ ComponentLifeCycle getLifeCycle();
+
+ /**
+ * Get the Service Unit manager for this component. If this component does not
+ * support deployments, it must return null.
+ *
+ * @return the ServiceUnitManager for this component, or null if there is none.
+ */
+ ServiceUnitManager getServiceUnitManager();
+
+ /**
+ * Retrieves a DOM representation containing metadata which describes the service
+ * provided by this component, through the given endpoint. The result can use WSDL
+ * 1.1 or WSDL 2.0.
+ *
+ * @param endpoint the service endpoint.
+ * @return the description for the specified service endpoint.
+ */
+ Document getServiceDescription(ServiceEndpoint endpoint);
+
+ /**
+ * This method is called by JBI to check if this component, in the role of provider
+ * of the service indicated by the given exchange, can actually perform the operation
+ * desired.
+ *
+ * @param endpoint the endpoint to be used by the consumer; must be non-null.
+ * @param exchange the proposed message exchange to be performed; must be non-null.
+ * @return true if this provider component can interact with the described consumer
+ * to perform the given exchange.
+ */
+ boolean isExchangeWithConsumerOkay(ServiceEndpoint endpoint, MessageExchange exchange);
+
+ /**
+ * This method is called by JBI to check if this component, in the role of consumer
+ * of the service indicated by the given exchange, can actually interact with the
+ * provider properly. The provider is described by the given endpoint and the service
+ * description supplied by that endpoint.
+ *
+ * @param endpoint the endpoint to be used by the provider; must be non-null.
+ * @param exchange the proposed message exchange to be performed; must be non-null.
+ * @return true if this consumer component can interact with the described provider
+ * to perform the given exchange.
+ */
+ boolean isExchangeWithProviderOkay(ServiceEndpoint endpoint, MessageExchange exchange);
+
+ /**
+ * Resolve the given endpoint reference. This is called by JBI when it is attempting to
+ * resolve the given EPR on behalf of a component.
+ *
+ * If this component returns a non-null result, it must conform to the following:
+ * <ul>
+ * <li>This component implements the ServiceEndpoint returned.</li>
+ * <li>The result must not be registered or activated with the JBI implementation.</li>
+ * </ul>
+ *
+ * Dynamically resolved endpoints are distinct from static ones; they must not be activated
+ * (see {@link javax.jbi.component.ComponentContext#activateEndpoint(javax.xml.namespace.QName, String)}),
+ * nor registered (see {@link ComponentContext}) by components. They can only be used to address
+ * message exchanges; the JBI implementation must deliver such exchanges to the component that
+ * resolved the endpoint reference (see
+ * {@link javax.jbi.component.ComponentContext#resolveEndpointReference(org.w3c.dom.DocumentFragment)}).
+ *
+ * @param epr the endpoint reference, in some XML dialect understood by the appropriate component
+ * (usually a binding); must be non-null.
+ * @return the service endpoint for the EPR; null if the EPR cannot be resolved by this component.
+ */
+ ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentContext.java b/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentContext.java
new file mode 100644
index 0000000..2f85f81
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentContext.java
@@ -0,0 +1,304 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import java.util.MissingResourceException;
+import java.util.logging.Logger;
+
+import javax.jbi.JBIException;
+import javax.jbi.messaging.DeliveryChannel;
+import javax.jbi.messaging.MessagingException;
+import javax.jbi.servicedesc.ServiceEndpoint;
+
+import javax.xml.namespace.QName;
+
+import org.w3c.dom.Document;
+import org.w3c.dom.DocumentFragment;
+
+/**
+ * This interface provides access to data needed by a JBI component
+ * about the JBI environment in which it is installed, as well providing
+ * the means to allow the component to inform the JBI environment about
+ * services provided by this component. This interface provides methods
+ * for the following functions:
+ * <ul>
+ * <li>Get the <bold>DeliveryChannel</bold> for this component. This is
+ * required to allow the component to send and receive message
+ * exchanges.</li>
+ * <li><bold>Activate</bold> (and deactivate) service endpoints provided
+ * by this component.</li>
+ * <li><bold>Register</bold> (and deregister) external endpoints provided
+ * by this component.</li>
+ * <li><bold>Query</bold> available endpoints (internal and external).</li>
+ * <li><bold>Query</bold> various data about the component, as installed
+ * in the JBI environment (name, workspace root, install root, initial
+ * JNDI context, MBean Server, Transaction Manager).</li>
+ * <li><bold>Loggers</bold>. Obtain the component's logger and subloggers.</li>
+ * <li><bold>MBean name creator</bold>. Access a utility for creating
+ * custom MBean names.</li>
+ * <li><bold>EPR Resolver</bold>. Ask JBI to resolve an endpoint reference
+ * (EPR), converting it into a service endpoint.</li>
+ *
+ * Note: The term "NMR" (meaning Normalized Message Router) is used here to refer
+ * to the messaging system of the JBI implementation. This term is used as a
+ * synonym for the JBI implementation, and refers only to the logical message
+ * routing functions of a JBI implementation. It is not meant to require that
+ * JBI implementations literally have a subsystem named "NMR".
+ *
+ * @author JSR208 Expert Group
+ */
+public interface ComponentContext {
+
+ /**
+ * Activates the named endpoint with the NMR. Activation indicates to the NMR
+ * that this component is ready to process requests sent to the named endpoint.
+ *
+ * Note that the JBI implementation may call this component's
+ * {@link Component#getServiceDescription(ServiceEndpoint)} method before returning
+ * from this method call; the component's implementation must be ready to supply
+ * service description metadata before the result of this activation call (a
+ * ServiceEndpoint) is known.
+ *
+ * @param serviceName qualified name of the service the endpoint exposes; must
+ * be non-null.
+ * @param endpointName the name of the endpoint to be activated; must be non-null
+ * and non-empty.
+ * @return a reference to the activated endpoint; must be non-null.
+ * @throws JBIException if the endpoint cannot be activated.
+ */
+ ServiceEndpoint activateEndpoint(QName serviceName, String endpointName) throws JBIException;
+
+
+ /**
+ * Deactivates the given endpoint with the NMR. Deactivation indicates to the NMR
+ * that this component will no longer process requests sent to the named endpoint.
+ *
+ * @param endpoint reference to the endpoint to be deactivated; must be non-null.
+ * @throws JBIException if the endpoint cannot be deactivated.
+ */
+ void deactivateEndpoint(ServiceEndpoint endpoint) throws JBIException;
+
+ /**
+ * Registers the given external endpoint with the NMR. This indicates to the NMR that
+ * the given endpoint is used as a proxy for external service consumers to access an
+ * internal service of the same service name (but a different endpoint name).
+ *
+ * @param externalEndpoint the external endpoint to be registered, must be non-null.
+ * @throws JBIException if an external endpoint with the same name is already registered,
+ * by this or another component.
+ */
+ void registerExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException;
+
+ /**
+ * Deregisters the given external endpoint with the NMR. This indicates to the NMR that
+ * the given external endpoint can no longer be used as a proxy for external service
+ * consumers to access an internal service of the same service name.
+ *
+ * @param externalEndpoint the external endpoint to be deregistered; must be non-null.
+ * @throws JBIException if the given external endpoint was not previously registered.
+ */
+ void deregisterExternalEndpoint(ServiceEndpoint externalEndpoint) throws JBIException;
+
+ /**
+ * Resolve the given endpoint reference into a service endpoint. This is called by the
+ * component when it has an EPR that it wants to resolve into a service endpoint.
+ *
+ * Note that the service endpoint returned refers to a dynamic endpoint; the endpoint
+ * will exist only as long as this component retains a strong reference to the object
+ * returned by this method. The endpoint may not be included in the list of "activated"
+ * endpoints.
+ *
+ * @param epr endpoint reference as an XML fragment; must be non-null.
+ * @return the service endpoint corresponding to the given endpoint reference; null if
+ * the reference cannot be resolved.
+ */
+ ServiceEndpoint resolveEndpointReference(DocumentFragment epr);
+
+ /**
+ * Get the unique component name of this component, ass assigned by the identification
+ * section of this component's installation descriptor.
+ *
+ * @return the component name; must be non-null and non-empty.
+ */
+ String getComponentName();
+
+ /**
+ * Get a channel for this component to use to communicate with the Normalized Message
+ * Router. This channel must be used by the component to send and receive message
+ * exchanges.
+ *
+ * @return the delivery channel for this component; must be non-null.
+ * @throws MessagingException if a channel has already been opened, but not yet closed.
+ */
+ DeliveryChannel getDeliveryChannel() throws MessagingException;
+
+ /**
+ * Get the service endpoint for the named activated endpoint, if any.
+ *
+ * @param service qualified-name of the endpoint's service; must be non-null.
+ * @param name name of the endpoint; must be non-null.
+ * @return the named endpoint, or null if the named endpoint is not activated.
+ */
+ ServiceEndpoint getEndpoint(QName service, String name);
+
+ /**
+ * Retrieve the service description metadata for the specified endpoint.
+ *
+ * Note that the result can use either the WSDL 1.1 or WSDL 2.0 description language.
+ *
+ * @param endpoint endpoint reference; must be non-null.
+ * @return metadata describing endpoint, or null if metadata is unavailable.
+ * @throws JBIException invalid endpoint reference.
+ */
+ Document getEndpointDescriptor(ServiceEndpoint endpoint) throws JBIException;
+
+ /**
+ * Queries the NMR for active endpoints that implement the given interface. This
+ * will return the endpoints for all services and endpoints that implement the
+ * named interface (portType in WSDL 1.1). This method does NOT include external
+ * endpoints (those registered using {@link #registerExternalEndpoint(ServiceEndpoint)}).
+ *
+ * @param interfaceName qualified name of interface/portType that is implemented
+ * by the endpoint; if null then all activated endpoints in
+ * the JBI environment must be returned.
+ * @return an array of available endpoints for the specified interface name; must
+ * be non-null; may be empty.
+ */
+ ServiceEndpoint[] getEndpoints(QName interfaceName);
+
+ /**
+ * Queries the NMR for active endpoints belonging to the given service. This
+ * method does NOT include external endpoints (those registered using
+ * {@link #registerExternalEndpoint(ServiceEndpoint)}).
+ *
+ * @param serviceName qualified name of the service that the endpoints are part
+ * of; must be non-null.
+ * @return an array of available endpoints for the specified service name; must
+ * be non-null; may be empty.
+ */
+ ServiceEndpoint[] getEndpointsForService(QName serviceName);
+
+ /**
+ * Queries the NMR for external endpoints that implement the given interface name.
+ * This methods returns only registered external endpoints (see
+ * {@link #registerExternalEndpoint(ServiceEndpoint)}).
+ *
+ * @param interfaceName qualified name of interface implemented by the endpoints;
+ * must be non-null.
+ * @return an array of available external endpoints for the specified interface name;
+ * must be non-null; may be empty.
+ */
+ ServiceEndpoint[] getExternalEndpoints(QName interfaceName);
+
+ /**
+ * Queries the NMR for external endpoints that are part of the given service.
+ *
+ * @param serviceName qualified name of service that contains the endpoints;
+ * must be non-null.
+ * @return an array of available external endpoints for the specified service name;
+ * must be non-null; may be empty.
+ */
+ ServiceEndpoint[] getExternalEndpointsForService(QName serviceName);
+
+ /**
+ * Get the installation root directory path for this component.
+ *
+ * This method MUST return the file path formatted for the underlying platform.
+ *
+ * @return the installation root directory path, in platform-specific form;
+ * must be non-null and non-empty.
+ */
+ String getInstallRoot();
+
+ /**
+ * Get a logger instance from JBI. Loggers supplied by JBI are guaranteed to have
+ * unique names such that they avoid name collisions with loggers from other
+ * components created using this method. The suffix parameter allows for the
+ * creation of subloggers as needed. The JBI specification says nothing about
+ * the exact names to be used, only that they must be unique across components
+ * and the JBI implementation itself.
+ *
+ * @param suffix for creating subloggers; use an empty string for the base component
+ * logger; must be non-null.
+ * @param resourceBundleName name of ResourceBundle to be used for localizing messages
+ * for the logger. May be null if none of the messages require
+ * localization. The resource, if non-null, must be loadable
+ * using the component's class loader as the initiating loader.
+ * @return a standard logger, named uniquely for this component (plus the given suffix,
+ * if applicable); must be non-null.
+ * @throws java.util.MissingResourceException if the ResourceBundleName is non-null and no
+ * corresponding resource can be found.
+ * @throws JBIException if the resourceBundleName has changed from a previous invocation
+ * by this component of this method with the same suffix.
+ */
+ Logger getLogger(String suffix, String resourceBundleName) throws MissingResourceException, JBIException;
+
+ /**
+ * Get a reference to the MBeanNames creator for use in creating custom MBean names.
+ *
+ * @return reference to the MBeanNames creator; must be non-null.
+ */
+ javax.jbi.management.MBeanNames getMBeanNames();
+
+ /**
+ * Get the JMX MBean server used to register all MBeans in the JBI environment.
+ *
+ * @return a reference to the MBean server; must be non-null.
+ */
+ javax.management.MBeanServer getMBeanServer();
+
+ /**
+ * Get the JNDI naming context for this component. This context is a standard JNDI
+ * InitialContext but its content will vary based on the environment in which the JBI
+ * implementation is running.
+ *
+ * @return the JNDI naming context; must be non-null.
+ */
+ javax.naming.InitialContext getNamingContext();
+
+ /**
+ * Get the TransactionManager for this implementation. The instance returned is an
+ * implementation of the standard JTA interface. If none is available, this method
+ * returns null.
+ *
+ * The object returned by this method is untyped, to allow this interface to be compiled
+ * in environments that do not support JTA. If not null, the object returned must be of
+ * type javax.transaction.TransactionManager.
+ *
+ * This downcast is necessary because JBI is used in environments that do not support
+ * JTA (i.e., J2SE). Explicit use of JTA types would cause compilation failures in
+ * such environments.
+ *
+ * @return A TransactionManager instance, or null if none is available in the
+ * execution environment.
+ */
+ Object getTransactionManager();
+
+ /**
+ * Get the root directory path for this component's private workspace.
+ *
+ * This method MUST return the file path formatted for the underlying platform.
+ *
+ * The returned value must indicate a valid file path that the component may use
+ * to write files to, and read files from.
+ *
+ * @return the private workspace root path, in platform-specific form;
+ * must be non-null and non-empty.
+ */
+ String getWorkspaceRoot();
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentLifeCycle.java b/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentLifeCycle.java
new file mode 100644
index 0000000..c98a736
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/ComponentLifeCycle.java
@@ -0,0 +1,96 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import javax.jbi.JBIException;
+import javax.management.ObjectName;
+
+/**
+ * This interface must be implemented by a JBI component to provide initialization,
+ * start, stop, and shutdown life cycle processing. These methods comprise the life
+ * cycle contract between the JBI implementation and the component. The life cycle
+ * of a component begins with a call to the init() method on an instance of the
+ * component's implementation of this interface, and ends with the first call to the
+ * shutDown() method on that instance. Between these two calls, there can be any
+ * number of stop() and start() calls.
+ *
+ * The JBI implementation must track the running state of a component, and ensure
+ * that life cycle state changes are always legal. For example, if the management
+ * interface for controlling a component's life cycle ({@link
+ * javax.jbi.management.ComponentLifeCycleMBean}) is used to start a component that
+ * was just installed (and thus in the <i>Shutdown</i> state), the implementation
+ * must invoke this component's {@link #init(ComponentContext)} method before
+ * invoking its {@link #start()} method.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface ComponentLifeCycle {
+
+ /**
+ * Get the JMX object name for the extension MBean for this component; if there
+ * is none, return null.
+ *
+ * @return the JMX object name of the additional MBean or null if there is no
+ * additional MBean.
+ */
+ ObjectName getExtensionMBeanName();
+
+ /**
+ * Initialize the component. This performs initialization required by the component
+ * but does not make it ready to process messages. This method is called once for
+ * each life cycle of the component.
+ *
+ * If the component needs to register an additional MBean to extend its life cycle,
+ * or provide other component management tasks, it should be registered during this
+ * call.
+ *
+ * @param context the component's context, providing access to component data provided
+ * by the JBI environment; must be non-null.
+ * @throws JBIException if the component is unable to initialize.
+ */
+ void init(ComponentContext context) throws JBIException;
+
+ /**
+ * Shut down the component. This performs clean-up, releasing all run-time resources
+ * used by the component. Once this method has been called, {@link #init(ComponentContext)}
+ * must be called before the component can be started again with a call to {@link #start()}.
+ *
+ * @throws JBIException if the component is unable to shut down.
+ */
+ void shutDown() throws JBIException;
+
+ /**
+ * Start the component. This makes the component ready to process messages. This method
+ * is called after {@link #init(ComponentContext)}, both when the component is being
+ * started for the first time and when the component is being restarted after a previous
+ * call to {@link #shutDown()}. If {@link #stop()} was called previously but {@link #shutDown()}
+ * was not, {@link #start()} can be called again without another call to
+ * {@link #init(ComponentContext)}.
+ *
+ * @throws JBIException if the component is unable to start.
+ */
+ void start() throws JBIException;
+
+ /**
+ * Stop the component. This makes the component stop accepting messages for processing.
+ * After a call to this method, {@link #start()} may be called again without first
+ * calling {@link #init(ComponentContext)}.
+ *
+ * @throws JBIException if the component is unable to stop.
+ */
+ void stop() throws JBIException;
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/InstallationContext.java b/jbi-api-1.0/src/main/java/javax/jbi/component/InstallationContext.java
new file mode 100644
index 0000000..2ba9ac3
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/InstallationContext.java
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import org.w3c.dom.DocumentFragment;
+
+/**
+ * This context contains information necessary for a JBI component to perform
+ * its installation/uninstallation processing.
+ */
+public interface InstallationContext {
+
+ /**
+ * Get the name of the class that implements the {@link Component}
+ * interface for this component. This must be the component class name
+ * given in the component's installation descriptor.
+ *
+ * @return the {@link Component} implementation class name, which
+ * must be non-null and non-empty.
+ */
+ String getComponentClassName();
+
+ /**
+ * Get a list of elements that comprise the class path for this component.
+ * Each element represents either a directory (containing class files) or
+ * a library file. All elements are reachable from the install root. These
+ * elements represent class path items that the component's execution-time
+ * component class loader uses, in search order. All path elements must use
+ * the file separator character appropriate to the system (i.e.,
+ * <code>File.separator</code>).
+ *
+ * @return a list of String objects, each of which contains a class path
+ * elements. The list must contain at least one class path element.
+ */
+ java.util.List getClassPathElements();
+
+ /**
+ * Get the unique name assigned to this component. This name must be assigned
+ * from the component's installation descriptor identification section.
+ *
+ * @return the unique component name, which must be non-null and non-empty.
+ */
+ String getComponentName();
+
+ /**
+ * Get the JBI context for this component. The following methods are valid
+ * to use on the context:
+ * <ul>
+ * <li>{@link ComponentContext#getLogger(String, String)}</li>
+ * <li>{@link ComponentContext#getMBeanNames()}</li>
+ * <li>{@link ComponentContext#getMBeanServer()}</li>
+ * <li>{@link ComponentContext#getNamingContext()}</li>
+ * <li>{@link ComponentContext#getTransactionManager()}</li>
+ * </ul>
+ *
+ * All other methods on the returned context must throw a IllegalStateException
+ * exception if invoked.
+ *
+ * @return the JBI context for this component, which must be non-null.
+ */
+ ComponentContext getContext();
+
+ /**
+ * Get the installation root directory full path name for this component.
+ * This path name must be formatted for the platform the JBI environment
+ * is running on.
+ *
+ * @return the installation root directory name, which must be non-null
+ * and non-empty.
+ */
+ String getInstallRoot();
+
+ /**
+ * Return a DOM document fragment representing the installation descriptor
+ * (jbi.xml) extension data for the component, if any.
+ *
+ * The Installation Descriptor Extension data are located at the end of the
+ * <component> element of the installation descriptor.
+ *
+ * @return a DOM document fragment containing the installation descriptor
+ * (jbi.xml) extension data, or null if none is present in the descriptor.
+ */
+ DocumentFragment getInstallationDescriptorExtension();
+
+ /**
+ * Returns <code>true</code> if this context was created in order to install a
+ * component into the JBI environment. Returns false if this context was created
+ * to uninstall a previously installed component.
+ *
+ * This method is provided to allow Bootstrap implementations to tailor their
+ * behaviour according to use case. For example, the
+ * {@link Bootstrap#init(InstallationContext)} method implementation may create
+ * different types of extension MBeans, depending on the use case specified by
+ * this method.
+ *
+ * @return <code>true</code> if this context was created in order to install a
+ * component into the JBI environment; otherwise the context was created
+ * to uninstall an existing component.
+ */
+ boolean isInstall();
+
+ /**
+ * Set the list of elements that comprise the class path for this component. Each
+ * element represents either a directory (containing class files) or a library file.
+ * Elements are reached from the install root. These elements represent class path
+ * items that the component's execution-time component class loader uses, in search
+ * order. All file paths are relative to the install root of the component.
+ *
+ * This method allows the component's bootstrap to alter the execution-time class
+ * path specified by the component's installation descriptor. The component
+ * configuration determined during installation can affect the class path needed by
+ * the component at execution-time. All path elements must use the file separator
+ * character appropriate to the system (i.e., <code>File.separator</code>).
+ *
+ * @param classPathElements a list of String objects, each of which contains a class
+ * path elements; the list must be non-null and contain at least one class path
+ * element.
+ * @throws java.lang.IllegalArgumentException if the class path elements is null, empty,
+ * or if an individual element is ill-formed.
+ */
+ void setClassPathElements(java.util.List classPathElements);
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/component/ServiceUnitManager.java b/jbi-api-1.0/src/main/java/javax/jbi/component/ServiceUnitManager.java
new file mode 100644
index 0000000..91637ce
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/component/ServiceUnitManager.java
@@ -0,0 +1,146 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.component;
+
+import javax.jbi.management.DeploymentException;
+
+/**
+ * This interface defines component-supplied methods for managing service
+ * unit deployments, and is implemented by the component. The JBI
+ * implementation queries the component for the implementation of this
+ * interface using the {@link Component#getServiceUnitManager()} method.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface ServiceUnitManager {
+
+ /**
+ * Deploy a Service Unit to the component. This is called by the JBI
+ * implementation in order to deploy the given artifact to the implementing
+ * component.
+ *
+ * Upon successful deployment, a non-empty result string must be returned,
+ * that starts with the JBI-defined component-task-result element. For example:
+ * <pre>
+ * <component-task-result>
+ * <component-name>BC1</component-name>
+ * <component-task-result-details
+ * xmlns="http://java.sun.com/xml/ns/jbi/management-message">
+ * <task-result-details>
+ * <task-id>deploy</task-id>
+ * <task-result>SUCCESS</task-result>
+ * </task-result-details>
+ * </component-task-result-details>
+ * </component-task-result>
+ * </pre>
+ * A failed deployment of the service unit must be reported using the
+ * <code>component-task-result</code> element as well; the
+ * <code>task-result</code> must be set to FAILED.
+ *
+ * @param serviceUnitName name of the service unit being deployed; must be
+ * non-null and non-empty and unique among service units already
+ * deployed to the component.
+ * @param serviceUnitRootPath path of the service unit artifact root, in
+ * platform specific format; must be non-null and non-empty.
+ * @return a deployment status message, which is an XML string that conforms
+ * to the schema given in the <i>MBean Status and Result Strings</i>
+ * section of the <i><b>Management</b></i> chapter of the JBI
+ * specification; must be non-null and non-empty.
+ * @exception DeploymentException if the deployment operation is
+ * unsuccessful.
+ */
+ String deploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
+
+ /**
+ * Initialize the given deployed service unit. This is the first phase of
+ * a two-phase start, where the component must prepare to receive service
+ * requests related to the deployment (if any).
+ * <p>
+ * The serviceUnitRootPath parameter is provided to facilitate restart of
+ * the component. This allows simple components to rely entirely on JBI's
+ * ability to persist deployment information, avoiding the need for the
+ * component to provide its own persistence mechanism.
+ *
+ * @param serviceUnitName name of the service unit being initialized; must
+ * be non-null, non-empty, and match the name of a previously
+ * deployed (but not yet undeployed) service unit.
+ * @param serviceUnitRootPath path of the service unit artifact root, in
+ * platform specific format; must be non-null and non-empty.
+ * @exception DeploymentException if the service unit is not deployed, or
+ * if it is in an incorrect state.
+ */
+ void init(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
+
+ /**
+ * Start the deployed service unit. This is the second phase of a two-phase
+ * start, where the component can now initiate service requests related to
+ * the deployment.
+ *
+ * @param serviceUnitName the name of the service unit being started; must
+ * be non-null, non-empty, and match the name of a previously
+ * deployed (but not yet undeployed) service unit.
+ * @exception DeploymentException if the service unit is not deployed, or
+ * if it is in an incorrect state.
+ */
+ void start(String serviceUnitName) throws DeploymentException;
+
+ /**
+ * Stop the deployed service unit. This causes the component to cease
+ * generating service requests related to the given service unit. This
+ * returns the service unit to a state equivalent to after
+ * {@link #init(String, String)} was called.
+ *
+ * @param serviceUnitName name of the service unit being stopped; must
+ * be non-null, non-empty, and match the name of a previously
+ * deployed (but not yet undeployed) service unit.
+ * @exception DeploymentException if the service unit is not deployed, or
+ * if it is in an incorrect state.
+ */
+ void stop(String serviceUnitName) throws DeploymentException;
+
+ /**
+ * Shut down the deployment. This causes the deployment to return to the
+ * to the state it was in after {@link #deploy(String, String)}, and before
+ * {@link #init(String, String)}.
+ *
+ * @param serviceUnitName name of the service unit being shut down; must
+ * be non-null, non-empty, and match the name of a previously
+ * deployed (but not yet undeployed) service unit.
+ * @exception DeploymentException if the service unit is not deployed, or
+ * if it is in an incorrect state.
+ */
+ void shutDown(String serviceUnitName) throws DeploymentException;
+
+ /**
+ * Undeploy a service unit from the component. The service unit must be
+ * shut down to undeploy it.
+ *
+ * @param serviceUnitName name of the service unit being undeployed; must
+ * be non-null, non-empty, and match the name of a previously
+ * deployed (but not yet undeployed) service unit.
+ * @param serviceUnitRootPath path of the service unit artifact root, in
+ * platform specific format; must be non-null and non-empty.
+ * @return deployment status message, which is an XML string that conforms
+ * to the <code>component-task-result</code> type from
+ * the schema given in the <i>MBean Status and Result Strings</i>
+ * section of the <i><b>Management</b></i> chapter of the JBI
+ * specification; must be non-null and non-empty.
+ * @exception DeploymentException if undeployment operation is unsuccessful,
+ * or if the service unit is in an incorrect state.
+ */
+ String undeploy(String serviceUnitName, String serviceUnitRootPath) throws DeploymentException;
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/AdminServiceMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/AdminServiceMBean.java
new file mode 100644
index 0000000..d4728d3
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/AdminServiceMBean.java
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.management.ObjectName;
+
+/**
+ * This interface defines a set of administrative methods allowing a JMX-based
+ * administrative tool to perform a variety of administrative tasks.
+ * <ul>
+ * <li>Find component lifecycle MBean names for:
+ * <ul>
+ * <li>Individual components, by name</li>
+ * <li>All binding components</li>
+ * <li>All service engines</li>
+ * </ul>
+ * </li>
+ * <li>Find lifecyle MBeans names for implementation-defined services:
+ * <ul>
+ * <li>Individual implementation services, by name</li>
+ * <li>All implementation services</li>
+ * </ul>
+ * </li>
+ * <li>Query whether an individual component is a binding or engine</li>
+ * <li>Query implementation information (version etc.)</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
+public interface AdminServiceMBean {
+
+ /**
+ * Get a list of {@link ComponentLifeCycleMBean}s for all binding components
+ * currently installed in the JBI system.
+ *
+ * @return array of JMX object names of component life cycle MBeans for all
+ * installed binding components; must be non-null; may be empty
+ */
+ ObjectName[] getBindingComponents();
+
+ /**
+ * Find the {@link ComponentLifeCycleMBean} of a JBI Installable Component
+ * by its unique name.
+ *
+ * @param name the name of the engine or binding component; must be non-
+ * null and non-empty
+ * @return the JMX object name of the component's life cycle MBean, or
+ * <code>null</code> if there is no such component with the given
+ * <code>name</code>
+ */
+ ObjectName getComponentByName(String name);
+
+ /**
+ * Get a list of {@link ComponentLifeCycleMBean}s for all service engines
+ * currently installed in the JBI system.
+ *
+ * @return array of JMX object names of component life cycle MBeans for all
+ * installed service engines; must be non-null; may be empty
+ */
+ ObjectName[] getEngineComponents();
+
+ /**
+ * Return current version and other info about this JBI implementation. The
+ * contents of the returned string are implementation dependent.
+ *
+ * @return information string about the JBI implementation, including
+ * version information; must be non-null and non-empty
+ */
+ String getSystemInfo();
+
+ /**
+ * Lookup a system service {@link LifeCycleMBean} by name. System services
+ * are implementation-defined services which can administered through JMX,
+ * and have a life cycle.
+ * <p>
+ * System services are not related to service engines.
+ *
+ * @param serviceName name of the system service; must be non-null and non-
+ * empty; values are implementation-dependent
+ * @return JMX object name of the system service's LifeCycleMBean, or
+ * <code>null</code> if there is no system service with the given
+ * <code>name</code>.
+ */
+ ObjectName getSystemService(String serviceName);
+
+ /**
+ * Looks up all JBI system services {@link LifeCycleMBean}'s currently
+ * installed. System services are implementation-defined services which can
+ * administered through JMX. System services are not related to service
+ * engines.
+ *
+ * @return array of LifecycleMBean JMX object names of system services
+ * currently installed in the JBI implementation; must be non-null;
+ * may be empty
+ */
+ ObjectName[] getSystemServices();
+
+ /**
+ * Check if a given JBI component is a Binding Component.
+ *
+ * @param componentName the unique name of the component; must be non-null
+ * and non-empty
+ * @return <code>true</code> if the component is a binding component;
+ * <code>false</code> if the component is a service engine or if
+ * there is no component with the given <code>componentName</code>
+ * installed in the JBI system
+ */
+ boolean isBinding(String componentName);
+
+ /**
+ * Check if a given JBI component is a Service Engine.
+ *
+ * @param componentName the unique name of the component; must be non-null
+ * and non-empty
+ * @return <code>true</code> if the component is a service engine;
+ * <code>false</code> if the component is a binding component, or if
+ * there is no component with the given <code>componentName</code>
+ * installed in the JBI system
+ */
+ boolean isEngine(String componentName);
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java
new file mode 100644
index 0000000..28088ee
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/ComponentLifeCycleMBean.java
@@ -0,0 +1,51 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.management.ObjectName;
+
+/**
+ * ComponentLifeCycleMBean defines the standard life cycle controls for
+ * JBI Installable Components.
+ * <ul>
+ * <li>Initialize the component, preparing it to receive service requests.</li>
+ * <li>Start the component, allowing it to initiate service requests.</li>
+ * <li>Stop the component from initiating any more service requests.</li>
+ * <li>Shut down the component, returning it to the uninitialized state
+ * where it cannot receive service requests.</li>
+ * <li>Query the JMX object name of the extension MBean for the component.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
+public interface ComponentLifeCycleMBean extends LifeCycleMBean {
+
+ /**
+ * Get the JMX ObjectName for the life cycle extension MBean for this
+ * component. If there is none, return <code>null</code>.
+ * Note that this MBean may serve as a container for multiple MBeans,
+ * as required by the component implementation.
+ *
+ * @return ObjectName the JMX object name of the additional MBean
+ * or <code>null</code> if there is no additional MBean.
+ * @exception javax.jbi.JBIException if there is a failure getting component
+ * information for the component to which this life cycle
+ * applies.
+ */
+ ObjectName getExtensionMBeanName() throws javax.jbi.JBIException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentException.java b/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentException.java
new file mode 100644
index 0000000..3a38f5a
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentException.java
@@ -0,0 +1,60 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+/**
+ * DeploymentException is an exception thrown by the Deployment Service and
+ * the Service Unit Manager.
+ *
+ * @author JSR208 Expert Group
+ */
+public class DeploymentException extends javax.jbi.JBIException {
+
+ /**
+ * Creates a new instance of DeploymentException with an exception detail
+ * message.
+ *
+ * @param aMessage the detail message for this exception.
+ */
+ public DeploymentException(String aMessage) {
+ super(aMessage);
+ }
+
+ /**
+ * Creates a new instance of DeploymentException with and exception detail
+ * message and a cause.
+ *
+ * @param aMessage the detail message for this exception.
+ * @param aCause <code>Error</code> or <code>Exception</code> which
+ * represents the cause of the problem (<code>null</code> if none,
+ * or if the cause is not known).
+ */
+ public DeploymentException(String aMessage, Throwable aCause) {
+ super(aMessage, aCause);
+ }
+
+ /**
+ * Creates a new instance of DeploymentException with the specified cause.
+ *
+ * @param aCause <code>Error</code> or <code>Exception</code> which
+ * represents the cause of the problem (<code>null</code> if none,
+ * or if the cause is not known).
+ */
+ public DeploymentException(Throwable aCause) {
+ super(aCause);
+ }
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentServiceMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentServiceMBean.java
new file mode 100644
index 0000000..4ca67f4
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/DeploymentServiceMBean.java
@@ -0,0 +1,234 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+/**
+ * The deployment service MBean allows administrative tools to manage
+ * service assembly deployments. The tasks supported are:
+ * <ul>
+ * <li>Deploying a service assembly.</li>
+ * <li>Undeploying a previously deployed service assembly.</li>
+ * <li>Querying deployed service assemblies:
+ * <ul>
+ * <li>For all components in the system.</li>
+ * <li>For a particular component.</li>
+ * </ul>
+ * </li>
+ * <li>Control the state of deployed service assemblies:
+ * <ul>
+ * <li>Start the service units that contained in the SA.</li>
+ * <li>Stop the service units that contained in the SA. </li>
+ * <li>Shut down the service units that contained in the SA.</li>
+ * </ul>
+ * </li>
+ * <li>Query the service units deployed to a particular component.</li>
+ * <li>Check if a service unit is deployed to a particular component.</li>
+ * <li>Query the deployment descriptor for a particular service assembly.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
+public interface DeploymentServiceMBean {
+
+ /**
+ * The service assembly is started. This means that the assembly's offered
+ * services can accept message exchanges, and it can send exchanges to
+ * consume services.
+ */
+ String STARTED = "Started";
+
+ /**
+ * The service assembly has been deployed, or shutdown
+ */
+ String SHUTDOWN = "Shutdown";
+
+ /**
+ * The service assembly is stopped. This means that the assembly's offered
+ * services can accept message exchanges, but it will not send any.
+ */
+ String STOPPED = "Stopped";
+
+ /**
+ * Deploys the given Service Assembly to the JBI environment.
+ * <p>
+ * Note that the implementation must not automatically start the service
+ * assembly after deployment; it must wait for the {@link #start(String)}
+ * method to be invoked by the administrative tool.
+ *
+ * @param saZipURL String containing the location URL of the
+ * Service Assembly ZIP file; must be non-null, non-empty, and a
+ * legal URL
+ * @return Result/Status of the current deployment; must conform to
+ * JBI management result/status XML schema; must be non-null and
+ * non-empty
+ * @exception Exception if complete deployment fails
+ */
+ String deploy(String saZipURL) throws Exception;
+
+ /**
+ * Undeploys the given Service Assembly from the JBI environment.
+ *
+ * @param saName name of the Service Assembly that is to be
+ * undeployed; must be non-null and non-empty
+ * @return Result/Status of the current undeployment; must conform to
+ * JBI management result/status XML schema; must be non-null and
+ * non-empty
+ * @exception Exception if compelete undeployment fails
+ */
+ String undeploy(String saName) throws Exception;
+
+ /**
+ * Returns an array of service unit names that are currently deployed to
+ * the named component.
+ *
+ * @param componentName the name of the component to query; must be
+ * non-null and non-empty
+ * @return array of service unit names deployed in the named component;
+ * must be non-null; may be empty
+ * @exception Exception if a processing error occurs
+ */
+ String[] getDeployedServiceUnitList(String componentName) throws Exception;
+
+ /**
+ * Returns a list of Service Assemblies deployed to the JBI environment.
+ *
+ * @return list of Service Assembly names; must be non-null; may be
+ * empty
+ * @exception Exception if a processing error occurs
+ */
+ String[] getDeployedServiceAssemblies() throws Exception;
+
+ /**
+ * Returns the deployment descriptor of the Service Assembly that was
+ * deployed to the JBI enviroment, serialized to a <code>String</code>.
+ *
+ * @param saName name of the service assembly to be queried;
+ * must be non-null and non-empty
+ * @return descriptor of the Assembly Unit; must be non-null
+ * @exception Exception if a processing error occurs
+ */
+ String getServiceAssemblyDescriptor(String saName) throws Exception;
+
+ /**
+ * Returns an array of Service Assembly names, where each assembly contains
+ * Service Units for the given component.
+ *
+ * @param componentName name of the component to query; must be non-null
+ * and non-empty
+ * @return array of of Service Assembly names, where each assembly contains
+ * a Service Unit for the named component; must be non-null; may
+ * be empty
+ * @exception Exception if a processing error occurs
+ */
+ String[] getDeployedServiceAssembliesForComponent(String componentName) throws Exception;
+
+ /**
+ * Returns an array of component names, where for each the given assembly
+ * contains a service unit for the component.
+ *
+ * @param saName the service assembly to be queried; must be
+ * non-null and non-empty
+ * @return array of component names, where for each name the given assembly
+ * contains a service unit from the given service assembly; must
+ * be non-null; may be empty
+ * @exception Exception if a processing error occurs
+ */
+ String[] getComponentsForDeployedServiceAssembly(String saName) throws Exception;
+
+ /**
+ * Queries if the named Service Unit is currently deployed to the named
+ * component.
+ *
+ * @param componentName name of the component to query; must be non-null
+ * and non-empty
+ * @param suName name of the subject service unit; must be non-null
+ * and non-empty
+ * @return <code>true</code> if the named service unit is currently deployed
+ * to the named component
+ */
+ boolean isDeployedServiceUnit(String componentName, String suName) throws Exception;
+
+ /**
+ * Returns <code>true</code> if the the given component accepts the
+ * deployment of service units. This is used by admin tools to
+ * determine which components can be named in service assembly
+ * deployment descriptors.
+ *
+ * @param componentName name of the component; must be non-null and
+ * non-empty
+ * @return <code>true</code> if the named component accepts deployments;
+ * <code>false</code> if the named component does not accept
+ * deployments or it does not exist
+ *
+ */
+ boolean canDeployToComponent(String componentName);
+
+ /**
+ * Start the service assembly. This puts the assembly into the {@link
+ * #STARTED} state.
+ *
+ * @param serviceAssemblyName name of the assembly to be started; must be
+ * non-null and non-empty
+ * @return result / status string giving the results of starting (and
+ * possibly initializing) each service unit in the assembly; must
+ * be non-null and non-empty
+ * @exception Exception if there is no such assembly
+ * @exception Exception if the assembly fails to start
+ *
+ */
+ String start(String serviceAssemblyName) throws Exception;
+
+ /**
+ * Stop the service assembly. This puts the assembly into the {@link
+ * #STOPPED} state.
+ *
+ * @param serviceAssemblyName name of the assembly to be stopped; must be
+ * non-null and non-empty
+ * @return result / status string giving the results of stopping each
+ * service unit in the assembly; must be non-null and non-empty
+ * @exception Exception if there is no such assembly
+ * @exception Exception if the assembly fails to stop
+ */
+ String stop(String serviceAssemblyName) throws Exception;
+
+ /**
+ * Shut down the service assembly. This puts the assembly back into the
+ * {@link #SHUTDOWN} state.
+ *
+ * @param serviceAssemblyName name of the assembly to be shut down; must be
+ * non-null and non-empty
+ * @return result / status string giving the results of shutting down
+ * each service unit in the assembly; must be non-null and non-empty
+ * @exception Exception if there is no such assembly
+ * @exception Exception if the assembly fails to shut down
+ */
+ String shutDown(String serviceAssemblyName) throws Exception;
+
+ /**
+ * Get the running state of a service assembly. The possible result values
+ * of this query are enumerated by the following set of constants:
+ * {@link #SHUTDOWN}, {@link #STOPPED}, {@link #STARTED}.
+ *
+ * @param serviceAssemblyName name of the assembly to query; must be
+ * non-null and non-empty
+ * @return the state of the service assembly, as a string value; must be one
+ * of the enumerated string values provided by this interface:
+ * {@link #SHUTDOWN}, {@link #STOPPED}, or {@link #STARTED}
+ * @exception Exception if there is no such assembly
+ */
+ String getState(String serviceAssemblyName) throws Exception;
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/InstallationServiceMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/InstallationServiceMBean.java
new file mode 100644
index 0000000..23d3d93
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/InstallationServiceMBean.java
@@ -0,0 +1,101 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.management.ObjectName;
+
+/**
+ * The installation service MBean allows administrative tools to manage
+ * component and shared library installations. The tasks supported are:
+ * <ul>
+ * <li>Installing (and uninstalling) a shared library</li>
+ * <li>Creating (loading) and destroying (unloading) a component installer
+ * MBean.</li>
+ * <li>Finding an existing component installer MBean.
+ * </ul>
+ *
+ * Installing and uninstalling components is accomplished using
+ * {@link InstallerMBean}s, loaded by this MBean. An individual installer MBean
+ * is needed for each component installation / uninstallation. This is to support
+ * the more complex installation process that some components require.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface InstallationServiceMBean {
+
+ /**
+ * Load the installer for a new component for the given component
+ * installation package.
+ *
+ * @param installZipURL URL locating a ZIP file containing the
+ * JBI Installation package to be installed; must be non-null,
+ * non-empty, and a legal URL
+ * @return the JMX ObjectName of the InstallerMBean loaded from
+ * installZipURL; must be non-null
+ */
+ ObjectName loadNewInstaller(String installZipURL);
+
+ /**
+ * Load the InstallerMBean for a previously installed component.
+ * <p>
+ * The "component name" refers to the
+ * <code><identification><name></code> element value from the
+ * component's installation package (see {@link #loadNewInstaller(String)}).
+ *
+ * @param aComponentName the component name identifying the installer to
+ * load; must be non-null and non-empty
+ * @return the JMX ObjectName of the InstallerMBean loaded from an existing
+ * installation context; <code>null</code> if the installer MBean
+ * doesn't exist
+ */
+ ObjectName loadInstaller(String aComponentName);
+
+ /**
+ * Unload an InstallerMBean previously loaded for a component.
+ *
+ * @param aComponentName the component name identifying the installer to
+ * unload; must be non-null and non-empty
+ * @param isToBeDeleted <code>true</code> if the component is to be deleted
+ * as well
+ * @return true if the operation was successful, otherwise false
+ */
+ boolean unloadInstaller(String aComponentName, boolean isToBeDeleted);
+
+ /**
+ * Install a shared library installation package.
+ * <p>
+ * The return value is the unique name for the shared-library, as found
+ * in the the value of the installation descriptor's
+ * <code><identification><name></code> element.
+ *
+ * @param aSharedLibURI URL locating a zip file containing a shared library
+ * installation package; must be non-null, non-empty, and a legal
+ * URL
+ * @return the unique name of the shared library loaded from slZipURL; must
+ * be non-null and non-empty
+ */
+ String installSharedLibrary(String aSharedLibURI);
+
+ /**
+ * Uninstall a previously installed shared library.
+ *
+ * @param aSharedLibName the name of the shared name space to uninstall; must be
+ * non-null and non-empty
+ * @return true if the uninstall was successful
+ */
+ boolean uninstallSharedLibrary(String aSharedLibName);
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/InstallerMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/InstallerMBean.java
new file mode 100644
index 0000000..d5d4305
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/InstallerMBean.java
@@ -0,0 +1,87 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.management.ObjectName;
+
+/**
+ * The InstallerMBean defines standard installation and uninstallation controls
+ * for components. InstallerMBeans are created by the
+ * {@link InstallationServiceMBean}. The InstallerMBean offers controls to
+ * allow an administrative tool to:
+ * <ul>
+ * <li>Install the component from the installation package.</li>
+ * <li>Uninstall the component.</li>
+ * <li>Check the installation status of the component.</li>
+ * <li>Get the file path to the component's installation root directory.</li>
+ * </ul>
+ *
+ * @author JSR208 Expert Group
+ */
+public interface InstallerMBean {
+
+ /**
+ * Get the installation root directory path for this component.
+ *
+ * @return the full installation path of this component; this must be in
+ * absolute path name form, in platform-specific format; must be
+ * non-null and non-empty
+ */
+ String getInstallRoot();
+
+ /**
+ * Install a component.
+ * <p>
+ * Note that the implementation must leave the component in its
+ * installed, shutdown state. Automatic starting of components during
+ * installation by implementations is not allowed.
+ *
+ * @return JMX ObjectName representing the LifeCycleMBean for the installed
+ * component, or <code>null</code> if the installation did not
+ * complete
+ * @exception javax.jbi.JBIException if the installation fails
+ */
+ ObjectName install() throws javax.jbi.JBIException;
+
+ /**
+ * Determine whether or not the component is installed.
+ *
+ * @return <code>true</code> if this component is currently installed,
+ * otherwise <code>false</code>
+ */
+ boolean isInstalled();
+
+ /**
+ * Uninstall the component. This completely removes the component from the
+ * JBI system.
+ *
+ * @exception javax.jbi.JBIException if the uninstallation fails
+ */
+ void uninstall() throws javax.jbi.JBIException;
+
+ /**
+ * Get the installer configuration MBean name for this component.
+ *
+ * @return the MBean object name of the Installer Configuration MBean;
+ * <code>null</code> if none is provided by this component
+ * @exception javax.jbi.JBIException if the component is not in the
+ * appropriate state (after install() but before life cycle
+ * initialization), or if any error occurs during processing
+ */
+ ObjectName getInstallerConfigurationMBean() throws javax.jbi.JBIException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/LifeCycleMBean.java b/jbi-api-1.0/src/main/java/javax/jbi/management/LifeCycleMBean.java
new file mode 100644
index 0000000..acdb715
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/LifeCycleMBean.java
@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.jbi.JBIException;
+
+/**
+ * LifeCycleMBean is a base interface that defines standard life cycle controls
+ * for JBI implementation services (which are implementation-specific), and JBI
+ * components (bindings and engines).
+ *
+ * @author JSR208 Expert Group
+ */
+public interface LifeCycleMBean {
+
+ /** Value returned by {@link #getCurrentState()} for a shutdown component. */
+ String SHUTDOWN = "Shutdown";
+
+ /** Value returned by {@link #getCurrentState()} for a stopped component. */
+ String STOPPED = "Stopped";
+
+ /** Value returned by {@link #getCurrentState()} for a running component. */
+ String STARTED = "Started";
+
+ /** Value returned by {@link #getCurrentState()} for a component in an unknown state. */
+ String UNKNOWN = "Unknown";
+
+ /**
+ * Start the item.
+ *
+ * @exception javax.jbi.JBIException if the item fails to start.
+ */
+ void start() throws JBIException;
+
+ /**
+ * Stop the item. This suspends current messaging activities.
+ *
+ * @exception javax.jbi.JBIException if the item fails to stop.
+ */
+ void stop() throws JBIException;
+
+ /**
+ * Shut down the item. This releases resources and returns the item
+ * to an uninitialized state.
+ *
+ * @exception javax.jbi.JBIException if the item fails to shut down.
+ */
+ void shutDown() throws JBIException;
+
+ /**
+ * Get the current state of this managed compononent.
+ *
+ * @return the current state of this managed component (must be one of the
+ * string constants defined by this interface)
+ */
+ String getCurrentState();
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/management/MBeanNames.java b/jbi-api-1.0/src/main/java/javax/jbi/management/MBeanNames.java
new file mode 100644
index 0000000..e6055ff
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/management/MBeanNames.java
@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.management;
+
+import javax.management.ObjectName;
+
+/**
+ * This interface provides methods to create JMX object names for component-
+ * supplied MBeans. This ensures that component-supplied MBeans follow the
+ * JBI implementation-determined naming convention.
+ *
+ * Components obtain instances of this name creator using {@link
+ * javax.jbi.component.ComponentContext#getMBeanNames()}.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface MBeanNames {
+
+ /** The custom name that must be used for bootstrap extensions */
+ String BOOTSTRAP_EXTENSION = "BootstrapExtension";
+
+ /** The custom name that must be used for component life cycle extensions */
+ String COMPONENT_LIFE_CYCLE_EXTENSION = "LifeCycleExtension";
+
+ /**
+ * Formulate and return an MBean ObjectName for a custom control
+ * of this name creator's JBI component.
+ * <p>
+ * This is used by components to create JMX names for their own JMX
+ * controls, allowing the JBI implementation to prefix the created name
+ * to fit within the implementation's own naming scheme.
+ * <p>
+ * Standard extensions must use the following custom name constants:
+ * <ul>
+ * <li>Bootstrap (installer) extension: {@link #BOOTSTRAP_EXTENSION}.</li>
+ * <li>Component life cycle extension:
+ * {@link #COMPONENT_LIFE_CYCLE_EXTENSION}.
+ * </li>
+ * </ul>
+ * All other custom component MBeans must use custom names that do not
+ * collide with the standard extension names.
+ *
+ * @param customName the name of the custom control; must be non-null and
+ * non-empty; must be legal for use in a JMX object name
+ * @return the JMX ObjectName of the MBean, or <code>null</code> if
+ * the <code>customName</code> is invalid
+ */
+ ObjectName createCustomComponentMBeanName(String customName);
+
+ /**
+ * Retrieve the default JMX Domain Name for MBeans registered in
+ * this instance of the JBI implementation.
+ *
+ * @return the JMX domain name for this instance of the JBI implemention;
+ * must be non-null and non-empty
+ */
+ String getJmxDomainName();
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/DeliveryChannel.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/DeliveryChannel.java
new file mode 100644
index 0000000..77bab93
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/DeliveryChannel.java
@@ -0,0 +1,133 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+import javax.jbi.servicedesc.ServiceEndpoint;
+
+import javax.xml.namespace.QName;
+
+/**
+ * Bi-directional communication channel used to interact with the Normalized
+ * Message Service.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface DeliveryChannel
+{
+ /**
+ * Closes the delivery channel, halting all message traffic.
+ *
+ * @throws MessagingException fatal error while closing channel.
+ */
+ void close() throws MessagingException;
+
+ /**
+ * Create a message exchange factory. This factory will create exchange
+ * instances with all appropriate properties set to null.
+ *
+ * @return a message exchange factory
+ */
+ MessageExchangeFactory createExchangeFactory();
+
+ /**
+ * Create a message exchange factory for the given interface name.
+ *
+ * @param interfaceName name of the interface for which all exchanges
+ * created by the returned factory will be set
+ * @return an exchange factory that will create exchanges for the given
+ * interface; must be non-null
+ */
+ MessageExchangeFactory createExchangeFactory(QName interfaceName);
+
+ /**
+ * Create a message exchange factory for the given service name.
+ *
+ * @param serviceName name of the service for which all exchanges
+ * created by the returned factory will be set
+ * @return an exchange factory that will create exchanges for the given
+ * service; must be non-null
+ */
+ MessageExchangeFactory createExchangeFactoryForService(QName serviceName);
+
+ /**
+ * Create a message exchange factory for the given endpoint.
+ *
+ * @param endpoint endpoint for which all exchanges created by the
+ * returned factory will be set for
+ * @return an exchange factory that will create exchanges for the
+ * given endpoint
+ */
+ MessageExchangeFactory createExchangeFactory(ServiceEndpoint endpoint);
+
+ /**
+ * Blocking call used to service a MessageExchange instance which has
+ * been initiated by another component. This method supports concurrent
+ * invocation for multi-threaded environments.
+ *
+ * @return mesage exchange instance
+ * @throws MessagingException failed to accept
+ */
+ MessageExchange accept() throws MessagingException;
+
+ /**
+ * Identical to accept(), but returns after specified interval even if
+ * a message exchange is unavailable.
+ *
+ * @param timeout time to wait in milliseconds
+ * @return mesage exchange instance or null if timeout is reached
+ * @throws MessagingException failed to accept
+ */
+ MessageExchange accept(long timeout) throws MessagingException;
+
+ /**
+ * Routes a MessageExchange instance through the Normalized Message Service
+ * to the appropriate servicing component. This method supports concurrent
+ * invocation for multi-threaded environments.
+ *
+ * @param exchange message exchange to send
+ * @throws MessagingException unable to send exchange
+ */
+ void send(MessageExchange exchange) throws MessagingException;
+
+ /**
+ * Routes a MessageExchange instance through the Normalized Message Service
+ * to the appropriate servicing component, blocking until the exchange is
+ * returned. This method supports concurrent invocation for multi-threaded
+ * environments.
+ *
+ * @param exchange message exchange to send
+ * @return true if the exchange has been processed and returned by the
+ * servicing component, false otherwise.
+ * @throws MessagingException unable to send exchange
+ */
+ boolean sendSync(MessageExchange exchange) throws MessagingException;
+
+ /**
+ * Routes a MessageExchange instance through the Normalized Message Service
+ * to the appropriate servicing component, blocking until the specified
+ * timeout is reached. This method supports concurrent invocation for
+ * multi-threaded environments.
+ *
+ * @param exchange message exchange to send
+ * @param timeout time to wait in milliseconds
+ * @return true if the exchange has been processed and returned by the
+ * servicing component, false in the case of timeout.
+ * @throws MessagingException unable to send exchange
+ */
+ boolean sendSync(MessageExchange exchange, long timeout) throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/ExchangeStatus.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/ExchangeStatus.java
new file mode 100644
index 0000000..49ace7a
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/ExchangeStatus.java
@@ -0,0 +1,100 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Typesafe enumeration containing status values for a message exchange.
+ *
+ * @author JSR208 Expert Group
+ */
+public final class ExchangeStatus {
+
+ /**
+ * Indicates that an ME has not been processed to completion.
+ */
+ public static final ExchangeStatus ACTIVE = new ExchangeStatus("Active");
+
+ /**
+ * Indicates that an ME has terminated abnormally within the JBI environment.
+ */
+ public static final ExchangeStatus ERROR = new ExchangeStatus("Error");
+
+ /**
+ * Indicates that an ME has been processed to completion.
+ */
+ public static final ExchangeStatus DONE = new ExchangeStatus("Done");
+
+ /** String representation of status. */
+ private String mStatus;
+
+ /**
+ * Private constructor used to create a new ExchangeStatus type.
+ *
+ * @param status value
+ */
+ private ExchangeStatus(String status) {
+ mStatus = status;
+ }
+
+ /**
+ * Returns string value of enumerated type.
+ *
+ * @return String representation of status value.
+ */
+ public String toString() {
+ return mStatus;
+ }
+
+ /**
+ * Returns instance of ExchangeStatus that corresponds to given string.
+ *
+ * @param status string value of status
+ * @return ExchangeStatus
+ * @throws java.lang.IllegalArgumentException if string can't be translated
+ */
+ public static ExchangeStatus valueOf(String status) {
+ ExchangeStatus instance;
+
+ //
+ // Convert symbolic name to object reference.
+ //
+ if (status.equals(DONE.toString())) {
+ instance = DONE;
+ } else if (status.equals(ERROR.toString())) {
+ instance = ERROR;
+ } else if (status.equals(ACTIVE.toString())) {
+ instance = ACTIVE;
+
+ } else {
+ //
+ // Someone has a problem.
+ //
+ throw new java.lang.IllegalArgumentException(status);
+ }
+
+ return instance;
+ }
+
+ /**
+ * Returns hash code value for this object.
+ *
+ * @return hash code value
+ */
+ public int hashCode() {
+ return mStatus.hashCode();
+ }
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/Fault.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/Fault.java
new file mode 100644
index 0000000..1f8729f
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/Fault.java
@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Models WSDL fault messages.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface Fault extends NormalizedMessage {
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOnly.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOnly.java
new file mode 100644
index 0000000..7ef2978
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOnly.java
@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Supports operations used to process an In Only MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface InOnly extends MessageExchange {
+
+ /**
+ * Retrieves the <i>in</i> normalized message from this exchange.
+ *
+ * @return in message
+ */
+ NormalizedMessage getInMessage();
+
+ /**
+ * Sets the <i>in</i> normalized message for this exchange.
+ *
+ * @param msg in message
+ * @throws MessagingException unable to set in message
+ */
+ void setInMessage(NormalizedMessage msg) throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOptionalOut.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOptionalOut.java
new file mode 100644
index 0000000..8dcfc08
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOptionalOut.java
@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Supports operations used to process an In Optional Out MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface InOptionalOut extends MessageExchange {
+
+ /**
+ * Retrieves the <i>in</i> normalized message from this exchange.
+ *
+ * @return in message
+ */
+ NormalizedMessage getInMessage();
+
+ /**
+ * Retrieves the <i>out</i> normalized message from this exchange.
+ *
+ * @return out message
+ */
+ NormalizedMessage getOutMessage();
+ /**
+ * Sets the <i>in</i> normalized message for this exchange.
+ *
+ * @param msg in message
+ * @throws MessagingException unable to set in message
+ */
+ void setInMessage(NormalizedMessage msg) throws MessagingException;
+
+ /**
+ * Sets the <i>out</i> normalized message for this exchange.
+ *
+ * @param msg out message
+ * @throws MessagingException unable to set out message
+ */
+ void setOutMessage(NormalizedMessage msg) throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOut.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOut.java
new file mode 100644
index 0000000..34f5a19
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/InOut.java
@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Supports operations used to process an In Out MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface InOut extends MessageExchange {
+
+ /**
+ * Retrieves the <i>in</i> normalized message from this exchange.
+ *
+ * @return in message
+ */
+ NormalizedMessage getInMessage();
+
+ /**
+ * Retrieves the <i>out</i> normalized message from this exchange.
+ *
+ * @return out message
+ */
+ NormalizedMessage getOutMessage();
+ /**
+ * Sets the <i>in</i> normalized message for this exchange.
+ *
+ * @param msg in message
+ * @throws MessagingException unable to set in message
+ */
+ void setInMessage(NormalizedMessage msg) throws MessagingException;
+
+ /**
+ * Sets the <i>out</i> normalized message for this exchange.
+ *
+ * @param msg out message
+ * @throws MessagingException unable to set out message
+ */
+ void setOutMessage(NormalizedMessage msg) throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchange.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchange.java
new file mode 100644
index 0000000..ef441b7
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchange.java
@@ -0,0 +1,254 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+import java.net.URI;
+
+import javax.jbi.servicedesc.ServiceEndpoint;
+
+import javax.xml.namespace.QName;
+
+/**
+ * MessageExchange represents a container for normalized messages which
+ * are described by an exchange pattern. The exchange pattern defines the
+ * names, sequence, and cardinality of messages in an exchange.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface MessageExchange {
+
+ /**
+ * JTA transaction context property name.
+ */
+ String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta";
+
+ /**
+ * Returns the URI of the pattern for this exchange.
+ *
+ * @return pattern URI for this exchange
+ */
+ URI getPattern();
+
+ /**
+ * Returns the unique identifier assigned by the NMS for this exchange.
+ *
+ * @return unique id for this exchange
+ */
+ String getExchangeId();
+
+ /**
+ * Returns the processing status of the exchange.
+ *
+ * @return status of the exchange
+ */
+ ExchangeStatus getStatus();
+
+ /**
+ * Sets the processing status of the exchange.
+ *
+ * @param status exchange status
+ * @throws MessagingException failed to set status, possibly due to
+ * an invalid state transition.
+ */
+ void setStatus(ExchangeStatus status) throws MessagingException;
+
+ /**
+ * Used to specify the source of a failure status. Invoking this method
+ * automatically adjusts the status of the ME to {@link ExchangeStatus#ERROR}.
+ *
+ * @param error error cause
+ */
+ void setError(Exception error);
+
+ /**
+ * Retrieves the Exception describing the exchanges error status.
+ *
+ * @return exception associated with this exchange
+ */
+ Exception getError();
+
+ /**
+ * Retrieves the fault message for this exchange, if one exists. A fault/message
+ * reference is unnecessary, since an exchange can carry at most one fault, and
+ * it is always the final message in an exchange.
+ *
+ * @return fault associated with the exchange, or null if not present
+ */
+ Fault getFault();
+
+ /**
+ * Specifies the fault message for this exchange, if one exists. A fault/message
+ * reference is unnecessary, since an exchange can carry at most one fault, and
+ * it is always the final message in an exchange.
+ *
+ * @param fault fault
+ * @throws MessagingException operation not permitted in the current exchange state
+ */
+ void setFault(Fault fault) throws MessagingException;
+
+ /**
+ * Creates a normalized message based on the specified message reference. The pattern
+ * governing this exchange must contain a definition for the reference name supplied.
+ *
+ * @return a new normalized message
+ * @throws MessagingException failed to create message
+ */
+ NormalizedMessage createMessage() throws MessagingException;
+
+ /**
+ * Generic factory method for Fault objects.
+ *
+ * @return a new fault
+ * @throws MessagingException failed to create fault
+ */
+ Fault createFault() throws MessagingException;
+
+ /**
+ * Retrieves a normalized message based on the specified message reference.
+ *
+ * @param name message reference
+ * @return message with the specified reference name
+ */
+ NormalizedMessage getMessage(String name);
+
+ /**
+ * Sets a normalized message with the specified message reference. The pattern
+ * governing this exchange must contain a definition for the reference name
+ * supplied.
+ *
+ * @param msg normalized message
+ * @param name message reference
+ * @throws MessagingException operation not permitted in the current exchange state
+ */
+ void setMessage(NormalizedMessage msg, String name) throws MessagingException;
+
+ /**
+ * Retrieves the specified property from the exchange.
+ *
+ * @param name property name
+ * @return property value
+ */
+ Object getProperty(String name);
+
+ /**
+ * Specifies a property for the exchange.
+ *
+ * @param name property name
+ * @param obj property value
+ */
+ void setProperty(String name, Object obj);
+
+ /**
+ * Specifies the endpoint used by this exchange.
+ *
+ * @param endpoint endpoint address
+ */
+ void setEndpoint(ServiceEndpoint endpoint);
+
+ /**
+ * Specifies the service used by this exchange.
+ *
+ * @param service service address
+ */
+ void setService(QName service);
+
+ /**
+ * Specifies the interface name used by this exchange.
+ *
+ * @param interfaceName interface name
+ */
+ void setInterfaceName(QName interfaceName);
+
+ /**
+ * Specifies the operation used by this exchange.
+ *
+ * @param name operation name
+ */
+ void setOperation(QName name);
+
+ /**
+ * Retrieves the endpoint used by this exchange.
+ *
+ * @return endpoint address for this message exchange
+ */
+ ServiceEndpoint getEndpoint();
+
+ /**
+ * Retrieves the interface name used by this exchange.
+ *
+ * @return interface used for this message exchange
+ */
+ QName getInterfaceName();
+
+ /**
+ * Retrieves the service used by this exchange.
+ *
+ * @return service address for this message exchange
+ */
+ QName getService();
+
+ /**
+ * Retrieves the operation used by this exchange.
+ *
+ * @return operation name for this message exchange
+ */
+ QName getOperation();
+
+ /**
+ * Queries the existence of a transaction context.
+ *
+ * @return boolean transactional state of the exchange
+ */
+ boolean isTransacted();
+
+ /**
+ * Queries the role that the caller plays in the exchange.
+ *
+ * @return Role expected of caller.
+ */
+ Role getRole();
+
+ /**
+ * Returns the name of all properties for this exchange.
+ *
+ * @return a set of all the property names, as Strings.
+ */
+ java.util.Set getPropertyNames();
+
+ /**
+ * Typesafe enum containing the roles a component can play in a service.
+ *
+ */
+ public static final class Role {
+
+ /**
+ * Service provider.
+ */
+ public static final Role PROVIDER = new Role();
+
+ /**
+ * Service Consumer.
+ */
+ public static final Role CONSUMER = new Role();
+
+ /**
+ * Prevent direct instantiation.
+ */
+ private Role() {
+ }
+ }
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
new file mode 100644
index 0000000..3e938a3
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessageExchangeFactory.java
@@ -0,0 +1,102 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+import java.net.URI;
+
+import javax.xml.namespace.QName;
+
+/**
+ * A message exchange factory is used used to create new instances of
+ * MessageExchange. Service consumers use these factories to create
+ * message exchanges when initiating a new service request. Message
+ * exchange factories are created using the
+ * {@link javax.jbi.component.ComponentContext} given to the component
+ * during its initialization (see
+ * {@link javax.jbi.component.ComponentLifeCycle}). There are a variety
+ * of ways to creating such factories, each of which creates a context
+ * that is used to provide some of the default properties of
+ * MessageExchange instances created by the factory instances. For example,
+ * a factory can be created for a particular endpoint, ensuring that all exchanges
+ * created by the factory have that endpoint set as the default endpoint property
+ * of the exchange. This allows components to retain factories as a way of aligning
+ * internal processing context with the context contained in the factory, ensuring
+ * that the exchanges created consistently reflect that context.
+ */
+public interface MessageExchangeFactory {
+
+ /**
+ * Creates a new MessageExchange instance used to initiate a service
+ * invocation. JBI defines a set of four basic message exchange types,
+ * corresponding to the predefined in-* WSDL 2.0 Message Exchange Patterns.
+ *
+ * @param serviceName name of the service to be invoked
+ * @param operationName name of the operation to be invoked
+ * @return new message exchange, initialized for invoking the given service and operation
+ * @throws MessagingException if the given service or operation are not registered
+ * with the NMR or the factory was created for a particular
+ * interface, and the given serviceName does not implement
+ * that interface.
+ */
+ MessageExchange createExchange(QName serviceName, QName operationName) throws MessagingException;
+
+ /**
+ * Creates a new MessageExchange instance used to initiate a service invocation.
+ * JBI defines a set of eight fundamental message exchange types which are created
+ * using binding and engine delivery channels. This base method is provided for
+ * extensibility, to satisfy the need for vendor-specific message exchange patterns.
+ * The registration and administration of these patterns is not addressed by JBI.
+ *
+ * @param pattern message exchange pattern
+ * @return new message exchange
+ * @throws MessagingException specified pattern is not registered to a message exchange type
+ */
+ MessageExchange createExchange(URI pattern) throws MessagingException;
+
+ /**
+ * Convenience method that creates an In-Only message exchange.
+ *
+ * @return new In-Only message exchange
+ * @throws MessagingException failed to create exchange
+ */
+ InOnly createInOnlyExchange() throws MessagingException;
+
+ /**
+ * Convenience method that creates an In-Optional-Out message exchange.
+ *
+ * @return new In-Optional-Out message exchange
+ * @throws MessagingException failed to create exchange
+ */
+ InOptionalOut createInOptionalOutExchange() throws MessagingException;
+
+ /**
+ * Convenience method that creates an In-Out message exchange.
+ *
+ * @return new In-Out message exchange
+ * @throws MessagingException failed to create exchange
+ */
+ InOut createInOutExchange() throws MessagingException;
+
+ /**
+ * Convenience method that creates an Robust-In-Only message exchange.
+ *
+ * @return new Robust-In-Only message exchange
+ * @throws MessagingException failed to create exchange
+ */
+ RobustInOnly createRobustInOnlyExchange() throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessagingException.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessagingException.java
new file mode 100644
index 0000000..044d139
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/MessagingException.java
@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Generic exception used to report messaging related errors
+ * in the Normalized Message Service.
+ *
+ * @author JSR208 Expert Group
+ */
+public class MessagingException extends javax.jbi.JBIException {
+
+ /**
+ * Create a new MessagingException.
+ *
+ * @param msg error detail
+ */
+ public MessagingException(String msg) {
+ super(msg);
+ }
+
+ /**
+ * Create a new MessagingException with the specified cause and error text.
+ *
+ * @param msg error detail
+ * @param cause underlying error
+ */
+ public MessagingException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+
+ /**
+ * Create a new MessagingException with the specified cause.
+ *
+ * @param cause underlying error
+ */
+ public MessagingException(Throwable cause) {
+ super(cause);
+ }
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/NormalizedMessage.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/NormalizedMessage.java
new file mode 100644
index 0000000..ede90a5
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/NormalizedMessage.java
@@ -0,0 +1,116 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+import java.util.Set;
+
+import javax.activation.DataHandler;
+import javax.security.auth.Subject;
+import javax.xml.transform.Source;
+
+/**
+ * Represents a JBI Normalized Message.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface NormalizedMessage {
+
+ /**
+ * Add an attachment to the message.
+ *
+ * @param id unique identifier for the attachment
+ * @param content attachment content
+ * @throws MessagingException failed to add attachment
+ */
+ void addAttachment(String id, DataHandler content) throws MessagingException;
+
+ /**
+ * Retrieve the content of the message.
+ *
+ * @return message content
+ */
+ Source getContent();
+
+ /**
+ * Retrieve attachment with the specified identifier.
+ *
+ * @param id unique identifier for attachment
+ * @return DataHandler representing attachment content, or null if an attachment
+ * with the specified identifier is not found
+ */
+ DataHandler getAttachment(String id);
+
+ /**
+ * Returns a list of identifiers for each attachment to the message.
+ *
+ * @return iterator over String attachment identifiers
+ */
+ Set getAttachmentNames();
+
+ /**
+ * Removes attachment with the specified unique identifier.
+ *
+ * @param id attachment identifier
+ * @throws MessagingException failed to remove attachment
+ */
+ void removeAttachment(String id) throws MessagingException;
+
+ /**
+ * Set the content of the message.
+ *
+ * @param content message content
+ * @throws MessagingException failed to set content
+ */
+ void setContent(Source content) throws MessagingException;
+
+ /**
+ * Set a property on the message.
+ *
+ * @param name property name
+ * @param value property value
+ */
+ void setProperty(String name, Object value);
+
+ /**
+ * Set the security Subject for the message.
+ *
+ * @param subject Subject to associated with message.
+ */
+ void setSecuritySubject(Subject subject);
+
+ /**
+ * Retrieve a list of property names for the message.
+ *
+ * @return list of property names
+ */
+ Set getPropertyNames();
+
+ /**
+ * Retrieve a property from the message.
+ *
+ * @param name property name
+ * @return property value, or null if the property does not exist
+ */
+ Object getProperty(String name);
+
+ /**
+ * Retrieve the security Subject from the message.
+ *
+ * @return security Subject associated with message, or null.
+ */
+ Subject getSecuritySubject();
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/messaging/RobustInOnly.java b/jbi-api-1.0/src/main/java/javax/jbi/messaging/RobustInOnly.java
new file mode 100644
index 0000000..e7a925c
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/messaging/RobustInOnly.java
@@ -0,0 +1,41 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.messaging;
+
+/**
+ * Supports operations used to process an Robust In Only MEP to completion.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface RobustInOnly extends MessageExchange {
+
+ /**
+ * Retrieves the <i>in</i> normalized message from this exchange.
+ *
+ * @return in message
+ */
+ NormalizedMessage getInMessage();
+
+ /**
+ * Sets the <i>in</i> normalized message for this exchange.
+ *
+ * @param msg in message
+ * @throws MessagingException unable to set in message
+ */
+ void setInMessage(NormalizedMessage msg) throws MessagingException;
+
+}
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/package.html b/jbi-api-1.0/src/main/java/javax/jbi/package.html
new file mode 100644
index 0000000..c97de60
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/package.html
@@ -0,0 +1,25 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<html>
+<head>
+</head>
+<body>
+
+Java Business Integration APIs/SPIs
+
+</body>
+</html>
diff --git a/jbi-api-1.0/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java b/jbi-api-1.0/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java
new file mode 100644
index 0000000..4d53053
--- /dev/null
+++ b/jbi-api-1.0/src/main/java/javax/jbi/servicedesc/ServiceEndpoint.java
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package javax.jbi.servicedesc;
+
+import javax.xml.namespace.QName;
+
+/**
+ * Reference to an endpoint, used to refer to an endpoint as well as
+ * query information about the endpoint. An endpoint is an addressable
+ * entity in the JBI system, used for accessing the provider of a
+ * specific service.
+ *
+ * @author JSR208 Expert Group
+ */
+public interface ServiceEndpoint {
+
+ /**
+ * Get a reference to this endpoint, using an endpoint reference
+ * vocabulary that is known to the provider.
+ *
+ * @param operationName the name of the operation to be performed by a
+ * consumer of the generated endpoint reference. Set
+ * to null if this is not applicable.
+ * @return endpoint reference as an XML fragment; null if the provider
+ * does not support such references.
+ */
+ org.w3c.dom.DocumentFragment getAsReference(QName operationName);
+
+ /**
+ * Returns the name of this endpoint.
+ *
+ * @return the endpoint name
+ */
+ String getEndpointName();
+
+ /**
+ * Get the qualified names of all the interfaces implemented by this
+ * service endpoint.
+ *
+ * @return array of all interfaces implemented by this service endpoint;
+ * must be non-null and non-empty.
+ */
+ javax.xml.namespace.QName[] getInterfaces();
+
+ /**
+ * Returns the service name of this endpoint.
+ *
+ * @return the qualified service name.
+ */
+ javax.xml.namespace.QName getServiceName();
+}
diff --git a/pom.xml b/pom.xml
index 85a667f..3eb023e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -42,6 +42,7 @@
<module>jaxb-api-2.1</module>
<module>jaxws-api-2.0</module>
<module>jaxws-api-2.1</module>
+ <module>jbi-api-1.0</module>
<module>scripting-api-1.0</module>
</modules>
