1 /************************************************************************* 2 * 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * Copyright 2000, 2010 Oracle and/or its affiliates. 6 * 7 * OpenOffice.org - a multi-platform office productivity suite 8 * 9 * This file is part of OpenOffice.org. 10 * 11 * OpenOffice.org is free software: you can redistribute it and/or modify 12 * it under the terms of the GNU Lesser General Public License version 3 13 * only, as published by the Free Software Foundation. 14 * 15 * OpenOffice.org is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License version 3 for more details 19 * (a copy is included in the LICENSE file that accompanied this code). 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * version 3 along with OpenOffice.org. If not, see 23 * <http://www.openoffice.org/license.html> 24 * for a copy of the LGPLv3 License. 25 * 26 ************************************************************************/ 27 28 package com.sun.star.lib.uno.environments.remote; 29 30 import com.sun.star.lib.uno.typedesc.TypeDescription; 31 import java.io.IOException; 32 33 /** 34 * An abstraction of remote bridge protocols. 35 * 36 * <p>A class implementing a given protocol <var>prot</var> must be named 37 * <code>com.sun.star.lib.uno.protocols.<var>prot</var>.<var>prot</var></code> 38 * and must have a public constructor that takes four arguments: The first 39 * argument of type <code>com.sun.star.uno.IBridge</code> must not be null. The 40 * second argument of type <code>String</code> represents any attributes; it may 41 * be null if there are no attributes. The third argument of type 42 * <code>java.io.InputStream</code> must not be null. The fourth argument of 43 * type <code>java.io.OutputStream</code> must not be null.</p> 44 */ 45 public interface IProtocol { 46 /** 47 * Initializes the connection. 48 * 49 * <p>This method must be called exactly once, after the 50 * <code>readMessage</code> loop has already been established.</p> 51 */ 52 void init() throws IOException; 53 54 void terminate(); 55 56 /** 57 * Reads a request or reply message. 58 * 59 * <p>Access to this method from multiple threads must be properly 60 * synchronized.</p> 61 * 62 * @return a non-null message; if the input stream is exhausted, a 63 * <code>java.io.IOException</code> is thrown instead 64 */ 65 Message readMessage() throws IOException; 66 67 /** 68 * Writes a request message. 69 * 70 * @param oid a non-null OID 71 * @param type a non-null UNO type 72 * @param function a non-null function (the name of a UNO interface method 73 * or attribute compatible with the given <code>type</code>, or either 74 * <code>"queryInterface"</code> or <code>"release"</code>) 75 * @param threadId a non-null TID 76 * @param arguments a list of UNO arguments compatible with the given 77 * <code>type</code> and <code>function</code>; may be null to represent 78 * an empty list 79 * @return <code>true</code> if the request message is sent as a synchronous 80 * request 81 */ 82 boolean writeRequest( 83 String oid, TypeDescription type, String function, ThreadId tid, 84 Object[] arguments) 85 throws IOException; 86 87 /** 88 * Writes a reply message. 89 * 90 * @param exception <code>true</code> if the reply corresponds to a raised 91 * exception 92 * @param tid a non-null TID 93 * @param result if <code>exception</code> is <code>true</code>, a non-null 94 * UNO exception; otherwise, a UNO return value, which may be null to 95 * represent a <code>VOID</code> return value 96 */ 97 void writeReply(boolean exception, ThreadId tid, Object result) 98 throws IOException; 99 } 100