1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 package com.sun.star.lib.uno.environments.remote; 25 26 import com.sun.star.lib.uno.typedesc.TypeDescription; 27 import java.io.IOException; 28 29 /** 30 * An abstraction of remote bridge protocols. 31 * 32 * <p>A class implementing a given protocol <var>prot</var> must be named 33 * <code>com.sun.star.lib.uno.protocols.<var>prot</var>.<var>prot</var></code> 34 * and must have a public constructor that takes four arguments: The first 35 * argument of type <code>com.sun.star.uno.IBridge</code> must not be null. The 36 * second argument of type <code>String</code> represents any attributes; it may 37 * be null if there are no attributes. The third argument of type 38 * <code>java.io.InputStream</code> must not be null. The fourth argument of 39 * type <code>java.io.OutputStream</code> must not be null.</p> 40 */ 41 public interface IProtocol { 42 /** 43 * Initializes the connection. 44 * 45 * <p>This method must be called exactly once, after the 46 * <code>readMessage</code> loop has already been established.</p> 47 */ init()48 void init() throws IOException; 49 terminate()50 void terminate(); 51 52 /** 53 * Reads a request or reply message. 54 * 55 * <p>Access to this method from multiple threads must be properly 56 * synchronized.</p> 57 * 58 * @return a non-null message; if the input stream is exhausted, a 59 * <code>java.io.IOException</code> is thrown instead 60 */ readMessage()61 Message readMessage() throws IOException; 62 63 /** 64 * Writes a request message. 65 * 66 * @param oid a non-null OID 67 * @param type a non-null UNO type 68 * @param function a non-null function (the name of a UNO interface method 69 * or attribute compatible with the given <code>type</code>, or either 70 * <code>"queryInterface"</code> or <code>"release"</code>) 71 * @param threadId a non-null TID 72 * @param arguments a list of UNO arguments compatible with the given 73 * <code>type</code> and <code>function</code>; may be null to represent 74 * an empty list 75 * @return <code>true</code> if the request message is sent as a synchronous 76 * request 77 */ writeRequest( String oid, TypeDescription type, String function, ThreadId tid, Object[] arguments)78 boolean writeRequest( 79 String oid, TypeDescription type, String function, ThreadId tid, 80 Object[] arguments) 81 throws IOException; 82 83 /** 84 * Writes a reply message. 85 * 86 * @param exception <code>true</code> if the reply corresponds to a raised 87 * exception 88 * @param tid a non-null TID 89 * @param result if <code>exception</code> is <code>true</code>, a non-null 90 * UNO exception; otherwise, a UNO return value, which may be null to 91 * represent a <code>VOID</code> return value 92 */ writeReply(boolean exception, ThreadId tid, Object result)93 void writeReply(boolean exception, ThreadId tid, Object result) 94 throws IOException; 95 } 96