QPID-4001 Added the interfaces for review. Kept it in a separate module

for folks who like to review the code in their editor. Added a
client-jms module to move the new destination work and house the new jms
work. This makes reviewing a bit easy and also allows the possiblity of
the new and old client code to live side by side until we make a
decision to archive the old client. At some point we need to trim the
common module to contain code that is truly common to both broker and
clients.

git-svn-id: https://svn.apache.org/repos/asf/qpid/branches/address-refactor2@1339264 13f79535-47bb-0310-9956-ffa450edef68

9 files changed, 523 insertions, 1 deletions

diff --git a/qpid/java/build.deps b/qpid/java/build.deps
index 1531bdfb4b..3e26bf1c37 100644
--- a/qpid/java/build.deps
+++ b/qpid/java/build.deps
@@ -147,3 +147,5 @@ bdb-je=lib/bdbstore/je-5.0.34.jar
 bdbstore.libs=${bdb-je}
 bdbstore.test.libs=${test.libs}
 
+client-api.libs=${slf4j-api}
+client-jms.libs=${geronimo-jms}
diff --git a/qpid/java/build.xml b/qpid/java/build.xml
index a77469eff6..5fd9d7ceda 100644
--- a/qpid/java/build.xml
+++ b/qpid/java/build.xml
@@ -26,7 +26,7 @@
   <findSubProjects name="client-plugins" dir="client-plugins"/>
   <findSubProjects name="management" dir="management" excludes="common,example"/>
 
-  <property name="modules.core"       value="junit-toolkit common management/common broker client tools"/>
+  <property name="modules.core"       value="junit-toolkit common management/common broker client tools client-api client-jms"/>
   <property name="modules.examples"   value="client/example management/example"/>
   <property name="modules.tests"      value="systests perftests integrationtests testkit"/>
   <property name="modules.management" value="${management}"/>
diff --git a/qpid/java/client-api/build.xml b/qpid/java/client-api/build.xml
new file mode 100644
index 0000000000..f6c6176f2e
--- /dev/null
+++ b/qpid/java/client-api/build.xml
@@ -0,0 +1,50 @@
+<!--
+ -
+ - 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.
+ -
+ -->
+<project name="Qpid Client API" default="build">
+
+  <property name="module.depends" value="common"/>
+  <property name="module.test.depends" value="common/test" />
+  <property name="module.genpom" value="true"/>
+
+  <import file="../module.xml"/>
+
+<!--  <property name="output.dir" value="${module.precompiled}/org/apache/qpid/filter/selector"/>
+
+  <target name="precompile">
+    <mkdir dir="${output.dir}"/>
+    <javacc target="src/main/grammar/SelectorParser.jj"
+            outputdirectory="${output.dir}"
+            javacchome="${project.root}/lib"/>
+  </target>
+-->
+
+  <target name="release-bin-copy-readme">
+      <copy todir="${module.release}" overwrite="true" failonerror="true">
+          <fileset file="${basedir}/README.txt" />
+      </copy>
+  </target>
+
+  <target name="release-bin-other" depends="release-bin-copy-readme"/>
+
+  <target name="release-bin" depends="release-bin-tasks"/>
+
+  <target name="bundle" depends="bundle-tasks"/>
+</project>
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Connection.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Connection.java
new file mode 100644
index 0000000000..17f68a4f57
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Connection.java
@@ -0,0 +1,66 @@
+/* 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 org.apache.qpid.messaging;
+
+/**
+ * A connection represents a network connection to a remote endpoint.
+ */
+public interface Connection
+{
+    /**
+     * Creates a network connection to the peer and negotiates with the peer to establish a protocol level connection.
+     * When this method returns the connection is ready to be used.
+     */
+    public void open();
+
+    /**
+     * Returns true if the connection is open.
+     */
+    public boolean isOpen();
+
+    /**
+     * Close the connection and any sessions associated with this connection.
+     */
+    public void close();
+
+    /**
+     * Creates a session with the given name.The name should be unique.
+     * It is advised to use a UUID for generating the name.
+     * @param name Unique identifier for the session.
+     * @return Session
+     */
+    public Session createSession(String name);
+
+    /**
+     * Creates a transactional session with the given name.
+     * Messages sent or received through this session, will only be settled once commit is called on this session.
+     * The name should be unique. It is advised to use a UUID for generating the name.
+     * @param name Unique identifier for the session.
+     * @return Session
+     */
+    public Session createTransactionalSession(String name);
+
+    /**
+     * Returns the authenticated username for this connection.
+     * For the simple username/password case, this just returns the same username.
+     * For EXTERNAL The username will be constructed from the subject distinguished name.
+     * For KERBEROR the username will be the kerberos username.
+     * @return The authenticated username.
+     */
+    public String getAuthenticatedUsername();
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Message.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Message.java
new file mode 100644
index 0000000000..6d08a43fbb
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Message.java
@@ -0,0 +1,76 @@
+/* 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 org.apache.qpid.messaging;
+
+import java.util.Map;
+
+/**
+ * Representation of a message.
+ */
+public interface Message
+{
+    public Object getContent();
+
+    public String getMessageId();
+
+    public void setMessageId(String messageId);
+
+    public String getSubject();
+
+    public void setSubject(String subject);
+
+    public String getContentType();
+
+    public void setContentType(String contentType);
+
+    public String getCorrelationId();
+
+    public void setCorrelationId(String correlationId);
+
+    public String getReplyTo();
+
+    public void setReplyTo(String replyTo);
+
+    public String getUserId();
+
+    public void setUserId(String userId);
+
+    public boolean isDurable();
+
+    public void setDurable(boolean durable);
+
+    public boolean isRedelivered();
+
+    public void setRedelivered(boolean redelivered);
+
+    public int getPriority();
+
+    public void setPriority(int priority);
+
+    public long getTtl();
+
+    public void setTtl(long ttl);
+
+    public long getTimestamp();
+
+    public void setTimestamp(long timestamp);
+
+    public Map<String, Object> getProperties();
+
+    public void setProperties(Map<String, Object> properties);
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Receiver.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Receiver.java
new file mode 100644
index 0000000000..899fd78699
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Receiver.java
@@ -0,0 +1,86 @@
+/* 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 org.apache.qpid.messaging;
+
+/**
+ * Interface through which messages are received.
+ */
+public interface Receiver
+{
+    /**
+     * Retrieves a message from this receivers local queue, or waits for upto the specified timeout for a message to become available.
+     * A timeout of zero never expires, and the call blocks indefinitely until a message arrives.
+     * @param timeout Timeout in milliseconds.
+     * @return The message received and null if not.
+     */
+    public Message get(long timeout);
+
+    /**
+     * Retrieves a message for this receivers subscription or waits for up to the specified timeout for one to become available.
+     * A timeout of zero never expires, and the call blocks indefinitely until a message arrives.
+     * @param timeout Timeout in milliseconds.
+     * @return The message received and null if not.
+     */
+    public Message fetch(long timeout);
+
+    /**
+     * Sets the capacity for the receiver.
+     * @param capacity Number of messages
+     */
+    public void setCapacity (int capacity);
+
+    /**
+     * Returns the capacity of this receiver
+     * @return capacity
+     */
+    public int getCapacity();
+
+    /**
+     * Returns the number of messages for which there is available capacity.
+     * @return available capacity
+     */
+    public int getAvailable();
+
+    /**
+     * Returns The number of messages received (by this receiver) that have been acknowledged, but for which that acknowledgment has not yet been confirmed by the peer.
+     * @return unsettled message count.
+     */
+    public int getUnsettled();
+
+    /**
+     * Cancels this receiver.
+     */
+    public void close();
+
+    /**
+     * Returns true if the receiver was closed by a call to close()
+     */
+    public boolean isClosed();
+
+    /**
+     * Returns the name that uniquely identifies this receiver within the given session.
+     * @return Identifier for this Receiver.
+     */
+    public String getName();
+
+    /**
+     * Returns the session associated with this receiver.
+     */
+    public Session getSession();
+
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Sender.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Sender.java
new file mode 100644
index 0000000000..59607b798b
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Sender.java
@@ -0,0 +1,76 @@
+/* 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 org.apache.qpid.messaging;
+
+/**
+ * Interface through which messages are sent
+ */
+public interface Sender
+{
+    /**
+     * Sends a message.
+     * @param message The message to be sent.
+     * @param sync  Blocks until the peer confirms the message received.
+     */
+    public void send (Message message, boolean sync);
+
+    /**
+     * Cancels the receiver.
+     */
+    public void close();
+
+    /**
+     * Sets the capacity for the sender.
+     * @param capacity Number of messages
+     */
+    public void setCapacity (int capacity);
+
+    /**
+     * Returns the capacity of this sender.
+     * @return capacity
+     */
+    public int getCapacity();
+
+    /**
+     * Returns the number of messages for which there is available capacity.
+     * @return available capacity
+     */
+    public int getAvailable();
+
+    /**
+     * Returns the number of sent messages pending confirmation of receipt by the broker.
+     * @return unsettled message count.
+     */
+    public int getUnsettled();
+
+    /**
+     * Returns true if the sender was closed by a call to close()
+     */
+    public boolean isClosed();
+
+    /**
+     * Returns the name that uniquely identifies this sender within the given session.
+     * @return Identifier for this Receiver.
+     */
+    public String getName();
+
+    /**
+     * Returns the session associated with this sender.
+     */
+    public Session getSession();
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Session.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Session.java
new file mode 100644
index 0000000000..1d1b10e580
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/Session.java
@@ -0,0 +1,124 @@
+/* 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 org.apache.qpid.messaging;
+
+/**
+ * A session represents a distinct 'conversation' which can involve sending and receiving messages to and from different addresses.
+ */
+public interface Session
+{
+    /**
+     * Returns true if the session is closed.
+     */
+    public boolean isClosed();
+
+    /**
+     * Closes a session and all associated senders and receivers.
+     */
+    public void  close();
+
+    /**
+     * Commits all messages sent or received during the current transaction.
+     */
+    public void commit();
+
+    /**
+     * Rolls back all messages sent or received during the current transaction.
+     */
+    public void rollback();
+
+    /**
+     * Acknowledges all outstanding messages that have been received by the application on this session.
+     * @param sync If true, request synchronization with the peer.
+     */
+    public void acknowledge(boolean sync);
+
+    /**
+     * Acknowledges the specified message.
+     * @param message The message to be acknowledged
+     * @param sync If true, request synchronization with the peer.
+     */
+    public <T> void acknowledge (Message message, boolean sync);
+
+    /**
+     * Rejects the specified message.
+     * @param message The message to be rejected.
+     */
+    public <T> void reject(Message message);
+
+    /**
+     * Releases the specified message.
+     * @param message The message to be released.
+     */
+    public <T> void release(Message message);
+
+    /**
+     * Request synchronization with the peer.
+     * @param block If true, block until synchronization is complete.
+     */
+    public void sync(boolean block);
+
+    /**
+     * Returns the total number of messages received and waiting to be fetched by all Receivers belonging to this session.
+     */
+    public int getReceivable();
+
+    /**
+     * Returns The number of messages received by this session that have been acknowledged, but for which that acknowledgment has not yet been confirmed by the peer.
+     */
+    public int getUnsettledAcks();
+
+    /**
+     * Returns the receiver for the next available message.
+     * This method blocks until a message arrives or the timeout expires.
+     * A timeout of zero never expires, and the call blocks indefinitely until a message arrives.
+     * @param timeout The timeout value in milliseconds.
+     * @return The receiver for the next available message.
+     */
+    public Receiver nextReceiver(long timeout);
+
+    /**
+     * Create a new sender through which messages can be sent to the specified address.
+     * @param address @see Address
+     */
+    public Sender createSender(Address address);
+
+    /**
+     * Create a new sender through which messages can be sent to the specified address.
+     * @param address The string containing a valid address @see Address for the format.
+     */
+    public Sender createSender (String address);
+
+    /**
+     * Create a new receiver through which messages can be received from the specified address.
+     * @param address @see Address
+     */
+    public Receiver createReceiver (Address address);
+
+    /**
+     * Create a new receiver through which messages can be received from the specified address.
+     * @param address The string containing a valid address @see Address for the format.
+     */
+    public Receiver createReceiver (String address);
+
+    /**
+     * Returns the connection this session is associated with.
+     * @return
+     */
+    public Connection getConnection();
+}
diff --git a/qpid/java/client-jms/build.xml b/qpid/java/client-jms/build.xml
new file mode 100644
index 0000000000..f17a093878
--- /dev/null
+++ b/qpid/java/client-jms/build.xml
@@ -0,0 +1,42 @@
+<!--
+ -
+ - 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.
+ -
+ -->
+<project name="Qpid JMS Client" default="build">
+
+  <property name="module.depends" value="client-api"/>
+  <property name="module.test.depends" value="common/test" />
+  <property name="module.genpom" value="true"/>
+
+  <import file="../module.xml"/>
+
+  <property name="output.dir" value="${module.precompiled}/org/apache/qpid/filter/selector"/>
+
+  <target name="release-bin-copy-readme">
+      <copy todir="${module.release}" overwrite="true" failonerror="true">
+          <fileset file="${basedir}/README.txt" />
+      </copy>
+  </target>
+
+  <target name="release-bin-other" depends="release-bin-copy-readme"/>
+
+  <target name="release-bin" depends="release-bin-tasks"/>
+
+  <target name="bundle" depends="bundle-tasks"/>
+</project>