INTEGRATION: CWS sb23 (1.8.26); FILE MERGED

2006/08/18 16:20:43 sb 1.8.26.6: RESYNC: (1.8-1.9); FILE MERGED
2005/03/14 10:55:35 sb 1.8.26.5: #i35277# Further cleanup.
2005/02/18 16:48:42 sb 1.8.26.4: #i35277# More cleanup; first part of supporting CurrentContext in URP.
2005/02/18 09:21:47 sb 1.8.26.3: #i35277# More cleanup; functionality moved from java_remote_bridge to urp, so that urp can autonomously handle protocol property requests.
2005/02/17 08:47:51 sb 1.8.26.2: #i35277# Improved documentation.
2005/02/16 16:54:43 sb 1.8.26.1: #i35277# More cleanup.

1 files changed, 57 insertions, 22 deletions

diff --git a/jurt/com/sun/star/lib/uno/environments/remote/IProtocol.java b/jurt/com/sun/star/lib/uno/environments/remote/IProtocol.java
index 20b3bbf89..eb5603dfb 100644
--- a/jurt/com/sun/star/lib/uno/environments/remote/IProtocol.java
+++ b/jurt/com/sun/star/lib/uno/environments/remote/IProtocol.java
@@ -4,9 +4,9 @@
  *
  *  $RCSfile: IProtocol.java,v $
  *
- *  $Revision: 1.9 $
+ *  $Revision: 1.10 $
  *
- *  last change: $Author: rt $ $Date: 2005-09-07 18:59:27 $
+ *  last change: $Author: rt $ $Date: 2006-12-01 14:50:44 $
  *
  *  The Contents of this file are made available subject to
  *  the terms of GNU Lesser General Public License Version 2.1.
@@ -32,39 +32,74 @@
  *    MA  02111-1307  USA
  *
  ************************************************************************/
+
 package com.sun.star.lib.uno.environments.remote;
 
 import com.sun.star.lib.uno.typedesc.TypeDescription;
-import java.io.DataOutput;
 import java.io.IOException;
-import java.io.InputStream;
 
 /**
- * This interface provides an abstraction for protocols
- * for remote bridges.
+ * An abstraction of remote bridge protocols.
+ *
+ * <p>A class implementing a given protocol <var>prot</var> must be named
+ * <code>com.sun.star.lib.uno.protocols.<var>prot</var>.<var>prot</var></code>
+ * and must have a public constructor that takes four arguments:  The first
+ * argument of type <code>com.sun.star.uno.IBridge</code> must not be null.  The
+ * second argument of type <code>String</code> represents any attributes; it may
+ * be null if there are no attributes.  The third argument of type
+ * <code>java.io.InputStream</code> must not be null.  The fourth argument of
+ * type <code>java.io.OutputStream</code> must not be null.</p>
  */
 public interface IProtocol {
     /**
-     * Gets the name of the protocol.
-     * <p>
-     * @result  the name of the protocol
+     * Initializes the connection.
+     *
+     * <p>This method must be called exactly once, after the
+     * <code>readMessage</code> loop has already been established.</p>
      */
-    String getName();
+    void init() throws IOException;
 
     /**
-     * Reads a job from the given stream.
-     * <p>
-     * @return  thread read job.
-     * @see     com.sun.star.lib.uno.environments.remote.Job
+     * Reads a request or reply message.
+     *
+     * <p>Access to this method from multiple threads must be properly
+     * synchronized.</p>
+     *
+     * @return a non-null message; if the input stream is exhausted, a
+     *     <code>java.io.IOException</code> is thrown instead
      */
-    IMessage readMessage(InputStream inputStream) throws IOException;
+    Message readMessage() throws IOException;
 
-    void writeRequest(
-        String oid, TypeDescription zInterface, String operation,
-        ThreadId threadId, Object[] params, Boolean[] synchron,
-        Boolean[] mustReply);
-
-    public void writeReply(boolean exception, ThreadId threadId, Object result);
+    /**
+     * Writes a request message.
+     *
+     * @param oid a non-null OID
+     * @param type a non-null UNO type
+     * @param function a non-null function (the name of a UNO interface method
+     *     or attribute compatible with the given <code>type</code>, or either
+     *     <code>"queryInterface"</code> or <code>"release"</code>)
+     * @param threadId a non-null TID
+     * @param arguments a list of UNO arguments compatible with the given
+     *     <code>type</code> and <code>function</code>; may be null to represent
+     *     an empty list
+     * @return <code>true</code> if the request message is sent as a synchronous
+     *     request
+     */
+    boolean writeRequest(
+        String oid, TypeDescription type, String function, ThreadId tid,
+        Object[] arguments)
+        throws IOException;
 
-    public void flush(DataOutput dataOutput) throws IOException;
+    /**
+     * Writes a reply message.
+     *
+     * @param exception <code>true</code> if the reply corresponds to a raised
+     *     exception
+     * @param tid a non-null TID
+     * @param result if <code>exception</code> is <code>true</code>, a non-null
+     *     UNO exception; otherwise, a UNO return value, which may be null to
+     *     represent a <code>VOID</code> return value
+     */
+    void writeReply(boolean exception, ThreadId tid, Object result)
+        throws IOException;
 }