QPID-4027 Added MessageEncoding, MessageNotWritable exception classes to

mnotify encoding/decoding related errors and write operations on Immutable messages.
Modified the API classes to include exceptions.
Added an Adapter to make a message immutable.

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

8 files changed, 331 insertions, 67 deletions

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
index 17f68a4f57..73fe49cb0f 100644
--- 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
@@ -26,17 +26,17 @@ 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();
+    public void open() throws ConnectionException;
 
     /**
      * Returns true if the connection is open.
      */
-    public boolean isOpen();
+    public boolean isOpen() throws ConnectionException;
 
     /**
      * Close the connection and any sessions associated with this connection.
      */
-    public void close();
+    public void close() throws ConnectionException;
 
     /**
      * Creates a session with the given name.The name should be unique.
@@ -44,7 +44,7 @@ public interface Connection
      * @param name Unique identifier for the session.
      * @return Session
      */
-    public Session createSession(String name);
+    public Session createSession(String name)throws ConnectionException;
 
     /**
      * Creates a transactional session with the given name.
@@ -53,13 +53,13 @@ public interface Connection
      * @param name Unique identifier for the session.
      * @return Session
      */
-    public Session createTransactionalSession(String name);
+    public Session createTransactionalSession(String name)throws ConnectionException;
 
     /**
      * 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.
+     * For KERBEROS 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
index 0f3eb6d6f6..af3019e9ec 100644
--- 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
@@ -24,53 +24,53 @@ import java.util.Map;
  */
 public interface Message
 {
-    public Object getContent();
+    public Object getContent() throws MessagingException;
 
-    public String getMessageId();
+    public String getMessageId() throws MessagingException;
 
-    public void setMessageId(String messageId);
+    public void setMessageId(String messageId)throws MessagingException;
 
-    public String getSubject();
+    public String getSubject()throws MessagingException;
 
-    public void setSubject(String subject);
+    public void setSubject(String subject)throws MessagingException;
 
-    public String getContentType();
+    public String getContentType()throws MessagingException;
 
-    public void setContentType(String contentType);
+    public void setContentType(String contentType)throws MessagingException;
 
-    public String getCorrelationId();
+    public String getCorrelationId()throws MessagingException;
 
-    public void setCorrelationId(String correlationId);
+    public void setCorrelationId(String correlationId)throws MessagingException;
 
-    public String getReplyTo();
+    public String getReplyTo()throws MessagingException;
 
-    public void setReplyTo(String replyTo);
+    public void setReplyTo(String replyTo)throws MessagingException;
 
-    public String getUserId();
+    public String getUserId()throws MessagingException;
 
-    public void setUserId(String userId);
+    public void setUserId(String userId)throws MessagingException;
 
-    public boolean isDurable();
+    public boolean isDurable()throws MessagingException;
 
-    public void setDurable(boolean durable);
+    public void setDurable(boolean durable)throws MessagingException;
 
-    public boolean isRedelivered();
+    public boolean isRedelivered()throws MessagingException;
 
-    public void setRedelivered(boolean redelivered);
+    public void setRedelivered(boolean redelivered)throws MessagingException;
 
-    public int getPriority();
+    public int getPriority()throws MessagingException;
 
-    public void setPriority(int priority);
+    public void setPriority(int priority)throws MessagingException;
 
-    public long getTtl();
+    public long getTtl()throws MessagingException;
 
-    public void setTtl(long ttl);
+    public void setTtl(long ttl)throws MessagingException;
 
-    public long getTimestamp();
+    public long getTimestamp()throws MessagingException;
 
-    public void setTimestamp(long timestamp);
+    public void setTimestamp(long timestamp)throws MessagingException;
 
-    public Map<String, Object> getProperties();
+    public Map<String, Object> getProperties()throws MessagingException;
 
-    public void setProperty(String key, Object value);
+    public void setProperty(String key, Object value)throws MessagingException;
 }
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageEncodingException.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageEncodingException.java
new file mode 100644
index 0000000000..c6bd462dac
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageEncodingException.java
@@ -0,0 +1,37 @@
+/* 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;
+
+/**
+ *  Notifies if an unsupported content type is used,
+ *  or if there is an error when encoding/decoding a message.
+ */
+public class MessageEncodingException extends MessagingException
+{
+
+    public MessageEncodingException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+
+    public MessageEncodingException(String message)
+    {
+        super(message);
+    }
+
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageNotWritableException.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageNotWritableException.java
new file mode 100644
index 0000000000..7d5924c780
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/MessageNotWritableException.java
@@ -0,0 +1,36 @@
+/* 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;
+
+/**
+ *  When trying to modify a read-only message.
+ */
+public class MessageNotWritableException extends MessagingException
+{
+
+    public MessageNotWritableException(String message, Throwable cause)
+    {
+        super(message, cause);
+    }
+
+    public MessageNotWritableException(String message)
+    {
+        super(message);
+    }
+
+}
diff --git a/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/ReadOnlyMessageAdapter.java b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/ReadOnlyMessageAdapter.java
new file mode 100644
index 0000000000..0dfd6e735d
--- /dev/null
+++ b/qpid/java/client-api/src/main/java/org/apache/qpid/messaging/ReadOnlyMessageAdapter.java
@@ -0,0 +1,191 @@
+/* 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.Collections;
+import java.util.Map;
+
+/**
+ *  Ensures the message is read only by blocking the delegates
+ *  setter methods.
+ */
+public class ReadOnlyMessageAdapter implements Message
+{
+    private Message _delegate;
+
+    ReadOnlyMessageAdapter(Message delegate)
+    {
+        _delegate = delegate;
+    }
+
+    @Override
+    public Object getContent() throws MessagingException
+    {
+        return _delegate.getContent();
+    }
+
+    @Override
+    public String getMessageId() throws MessagingException
+    {
+        return _delegate.getMessageId();
+    }
+
+    @Override
+    public void setMessageId(String messageId) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public String getSubject() throws MessagingException
+    {
+        return _delegate.getSubject();
+    }
+
+    @Override
+    public void setSubject(String subject) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public String getContentType() throws MessagingException
+    {
+        return _delegate.getContentType();
+    }
+
+    @Override
+    public void setContentType(String contentType) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public String getCorrelationId() throws MessagingException
+    {
+        return _delegate.getCorrelationId();
+    }
+
+    @Override
+    public void setCorrelationId(String correlationId) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public String getReplyTo() throws MessagingException
+    {
+        return _delegate.getReplyTo();
+    }
+
+    @Override
+    public void setReplyTo(String replyTo) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public String getUserId() throws MessagingException
+    {
+        return _delegate.getUserId();
+    }
+
+    @Override
+    public void setUserId(String userId) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public boolean isDurable() throws MessagingException
+    {
+        return _delegate.isDurable();
+    }
+
+    @Override
+    public void setDurable(boolean durable) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public boolean isRedelivered() throws MessagingException
+    {
+        return _delegate.isRedelivered();
+    }
+
+    @Override
+    public void setRedelivered(boolean redelivered) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public int getPriority() throws MessagingException
+    {
+        return _delegate.getPriority();
+    }
+
+    @Override
+    public void setPriority(int priority) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public long getTtl() throws MessagingException
+    {
+        return _delegate.getTtl();
+    }
+
+    @Override
+    public void setTtl(long ttl) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public long getTimestamp() throws MessagingException
+    {
+        return _delegate.getTimestamp();
+    }
+
+    @Override
+    public void setTimestamp(long timestamp) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    @Override
+    public Map<String, Object> getProperties() throws MessagingException
+    {
+        return Collections.unmodifiableMap(_delegate.getProperties());
+    }
+
+    @Override
+    public void setProperty(String key, Object value) throws MessagingException
+    {
+        throwMessageNotWritableException();
+    }
+
+    private void throwMessageNotWritableException() throws MessageNotWritableException
+    {
+        throw new MessageNotWritableException("Message is read-only");
+    }
+
+}
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
index 899fd78699..dbb6c88b7a 100644
--- 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
@@ -28,7 +28,7 @@ public interface Receiver
      * @param timeout Timeout in milliseconds.
      * @return The message received and null if not.
      */
-    public Message get(long timeout);
+    public Message get(long timeout) throws MessagingException;
 
     /**
      * Retrieves a message for this receivers subscription or waits for up to the specified timeout for one to become available.
@@ -36,51 +36,51 @@ public interface Receiver
      * @param timeout Timeout in milliseconds.
      * @return The message received and null if not.
      */
-    public Message fetch(long timeout);
+    public Message fetch(long timeout) throws MessagingException;
 
     /**
      * Sets the capacity for the receiver.
      * @param capacity Number of messages
      */
-    public void setCapacity (int capacity);
+    public void setCapacity (int capacity) throws MessagingException;
 
     /**
      * Returns the capacity of this receiver
      * @return capacity
      */
-    public int getCapacity();
+    public int getCapacity() throws MessagingException;
 
     /**
      * Returns the number of messages for which there is available capacity.
      * @return available capacity
      */
-    public int getAvailable();
+    public int getAvailable() throws MessagingException;
 
     /**
      * 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();
+    public int getUnsettled() throws MessagingException;
 
     /**
      * Cancels this receiver.
      */
-    public void close();
+    public void close() throws MessagingException;
 
     /**
      * Returns true if the receiver was closed by a call to close()
      */
-    public boolean isClosed();
+    public boolean isClosed() throws MessagingException;
 
     /**
      * Returns the name that uniquely identifies this receiver within the given session.
      * @return Identifier for this Receiver.
      */
-    public String getName();
+    public String getName() throws MessagingException;
 
     /**
      * Returns the session associated with this receiver.
      */
-    public Session getSession();
+    public Session getSession() throws MessagingException;
 
 }
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
index 59607b798b..f3c3788592 100644
--- 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
@@ -27,50 +27,50 @@ public interface Sender
      * @param message The message to be sent.
      * @param sync  Blocks until the peer confirms the message received.
      */
-    public void send (Message message, boolean sync);
+    public void send (Message message, boolean sync) throws MessagingException;
 
     /**
      * Cancels the receiver.
      */
-    public void close();
+    public void close() throws MessagingException;
 
     /**
      * Sets the capacity for the sender.
      * @param capacity Number of messages
      */
-    public void setCapacity (int capacity);
+    public void setCapacity (int capacity) throws MessagingException;
 
     /**
      * Returns the capacity of this sender.
      * @return capacity
      */
-    public int getCapacity();
+    public int getCapacity() throws MessagingException;
 
     /**
      * Returns the number of messages for which there is available capacity.
      * @return available capacity
      */
-    public int getAvailable();
+    public int getAvailable() throws MessagingException;
 
     /**
      * Returns the number of sent messages pending confirmation of receipt by the broker.
      * @return unsettled message count.
      */
-    public int getUnsettled();
+    public int getUnsettled() throws MessagingException;
 
     /**
      * Returns true if the sender was closed by a call to close()
      */
-    public boolean isClosed();
+    public boolean isClosed() throws MessagingException;
 
     /**
      * Returns the name that uniquely identifies this sender within the given session.
      * @return Identifier for this Receiver.
      */
-    public String getName();
+    public String getName() throws MessagingException;
 
     /**
      * Returns the session associated with this sender.
      */
-    public Session getSession();
+    public Session getSession() throws MessagingException;
 }
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
index 1d1b10e580..0d5abad6fd 100644
--- 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
@@ -25,63 +25,63 @@ public interface Session
     /**
      * Returns true if the session is closed.
      */
-    public boolean isClosed();
+    public boolean isClosed() throws MessagingException;
 
     /**
      * Closes a session and all associated senders and receivers.
      */
-    public void  close();
+    public void  close() throws MessagingException;
 
     /**
      * Commits all messages sent or received during the current transaction.
      */
-    public void commit();
+    public void commit() throws MessagingException;
 
     /**
      * Rolls back all messages sent or received during the current transaction.
      */
-    public void rollback();
+    public void rollback() throws MessagingException;
 
     /**
      * 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);
+    public void acknowledge(boolean sync) throws MessagingException;
 
     /**
      * 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);
+    public void acknowledge (Message message, boolean sync) throws MessagingException;
 
     /**
      * Rejects the specified message.
      * @param message The message to be rejected.
      */
-    public <T> void reject(Message message);
+    public void reject(Message message) throws MessagingException;
 
     /**
      * Releases the specified message.
      * @param message The message to be released.
      */
-    public <T> void release(Message message);
+    public void release(Message message) throws MessagingException;
 
     /**
      * Request synchronization with the peer.
      * @param block If true, block until synchronization is complete.
      */
-    public void sync(boolean block);
+    public void sync(boolean block) throws MessagingException;
 
     /**
      * Returns the total number of messages received and waiting to be fetched by all Receivers belonging to this session.
      */
-    public int getReceivable();
+    public int getReceivable() throws MessagingException;
 
     /**
      * 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();
+    public int getUnsettledAcks() throws MessagingException;
 
     /**
      * Returns the receiver for the next available message.
@@ -90,35 +90,35 @@ public interface Session
      * @param timeout The timeout value in milliseconds.
      * @return The receiver for the next available message.
      */
-    public Receiver nextReceiver(long timeout);
+    public Receiver nextReceiver(long timeout) throws MessagingException;
 
     /**
      * Create a new sender through which messages can be sent to the specified address.
      * @param address @see Address
      */
-    public Sender createSender(Address address);
+    public Sender createSender(Address address) throws MessagingException;
 
     /**
      * 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);
+    public Sender createSender (String address) throws MessagingException;
 
     /**
      * Create a new receiver through which messages can be received from the specified address.
      * @param address @see Address
      */
-    public Receiver createReceiver (Address address);
+    public Receiver createReceiver (Address address) throws MessagingException;
 
     /**
      * 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);
+    public Receiver createReceiver (String address) throws MessagingException;
 
     /**
      * Returns the connection this session is associated with.
      * @return
      */
-    public Connection getConnection();
+    public Connection getConnection() throws MessagingException;
 }