1// BEGIN LICENSE BLOCK 2// Version: CMPL 1.1 3// 4// The contents of this file are subject to the Cisco-style Mozilla Public 5// License Version 1.1 (the "License"); you may not use this file except 6// in compliance with the License. You may obtain a copy of the License 7// at www.eclipse-clp.org/license. 8// 9// Software distributed under the License is distributed on an "AS IS" 10// basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11// the License for the specific language governing rights and limitations 12// under the License. 13// 14// The Original Code is The ECLiPSe Constraint Logic Programming System. 15// The Initial Developer of the Original Code is Cisco Systems, Inc. 16// Portions created by the Initial Developer are 17// Copyright (C) 2000 - 2006 Cisco Systems, Inc. All Rights Reserved. 18// 19// Contributor(s): Stefano Novello / Josh Singer, Parc Technologies 20// 21// END LICENSE BLOCK 22 23 //Title: Java/ECLiPSe interface 24//Version: $Id: EclipseConnection.java,v 1.1 2006/09/23 01:54:08 snovello Exp $ 25//Author: Josh Singer / Stefano Novello 26//Company: Parc Technologies 27//Description: Java interface representing a connection to an ECLiPSe engine. 28package com.parctechnologies.eclipse; 29import java.io.*; 30 31/** 32 * Interface of objects which provide a connection to an ECLiPSe engine. 33 * Classes implementing <i>EclipseConnection</i> provide the following areas of 34 * functionality: 35 * <ul> 36 * <li> "RPC" calls: deterministic ECLiPSe goals which are executed in ECLiPSe 37 * and whose resulting instantiation is returned to Java. </li> 38 * <li> The ability to create/access "queues" between Java and ECLiPSe. </li> 39 * <li> The ability to register a handler to be called when ECLiPSe 40 * enters/leaves multitasking phases.</li> 41 * </ul> 42 * @see EmbeddedEclipse 43 * @see RemoteEclipse 44 * @see OutOfProcessEclipse 45 * @see EclipseEngine 46 */ 47public interface EclipseConnection 48{ 49 /** 50 * Make an "RPC" (remote predicate call) to the ECLiPSe engine. 51 * @param goal the goal as it would be typed in on the ECLiPSe command line, 52 * (the full stop is unnecessary). 53 * @throws EclipseException if execution of the goal fails or throws an 54 * ECLiPSe exception. 55 * @throws IOException if there was an I/O problem communicating with the 56 * ECLiPSe engine. 57 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 58 * been terminated. 59 * @return a <i>CompoundTerm</i> representing the goal, with any variables 60 * possibly further instantiated with the results of the computation. 61 */ 62 public CompoundTerm rpc(String goal) throws EclipseException, IOException; 63 64 /** 65 * Make an "RPC" (remote predicate call) to the ECLiPSe engine. 66 * @param goal the goal represented as a <i>CompoundTerm</i>. 67 * @throws EclipseException if execution of the goal fails or throws an 68 * ECLiPSe exception. 69 * @throws IOException if there was an I/O problem communicating with the 70 * ECLiPSe engine. 71 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 72 * been terminated. 73 * @return a <i>CompoundTerm</i> representing the goal, with any variables 74 * possibly further instantiated with the results of the computation. 75 */ 76 public CompoundTerm rpc(CompoundTerm goal) throws EclipseException, IOException; 77 78 /** 79 * Create or access a queue to transfer data from ECLiPSe to Java. If a 80 * <i>FromEclipseQueue</i> 81 * with this name has already been created for this EclipseConnection, it 82 * is returned. The supplied name should not be in use by any 83 * ECLiPSe stream which is not a <i>FromEclipseQueue</i> between ECLiPSe and 84 * this EclipseConnection: 85 * if it is, an <i>EclipseException</i> is thrown. Otherwise, a new 86 * <i>FromEclipseQueue</i> with the specified name is returned. 87 * 88 * @param name the name to be used for the stream representing the queue on 89 * the ECLiPSe side. 90 * @return a <i>FromEclipseQueue</i> object which can be used by Java to read data 91 * on the queue which was written there by ECLiPSe. 92 * @throws EclipseException if the name for the ECLiPSe stream is already in use, 93 * or ECLiPSe could not create its side of the queue for some reason. 94 * @throws IOException if there was an I/O problem while accessing ECLiPSe. 95 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 96 * been terminated. 97 */ 98 public FromEclipseQueue getFromEclipseQueue(String name) throws EclipseException, IOException; 99 /** 100 * Create or access a queue to transfer data from Java to ECLiPSe. If a 101 * <i>ToEclipseQueue</i> 102 * with this name has already been created for this EclipseConnection, it 103 * is returned. The supplied name should not be in use by any 104 * ECLiPSe stream which is not a <i>ToEclipseQueue</i> between ECLiPSe and 105 * this EclipseConnection: 106 * if it is, an <i>EclipseException</i> is thrown. Otherwise, a new 107 * <i>ToEclipseQueue</i> with the specified name is returned. 108 * 109 * 110 * @param name the name to be used for the stream representing the queue on 111 * the ECLiPSe side. 112 * @return a <i>ToEclipseQueue</i> object which can be used by Java to write data 113 * on the queue which can be read by ECLiPSe. 114 * @throws EclipseException if the name for the ECLiPSe stream is already in use, 115 * or ECLiPSe could not create its side of the queue for some reason. 116 * @throws IOException if there was an I/O problem while accessing ECLiPSe. 117 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 118 * been terminated. 119 */ 120 public ToEclipseQueue getToEclipseQueue(String name) throws EclipseException, IOException; 121 /** 122 * Create or access an asynchronous queue to transfer data between Java 123 * and ECLiPSe. If an <i>AsyncEclipseQueue</i> 124 * with this name has already been created for this EclipseConnection, it 125 * is returned. The supplied name should not be in use by any 126 * ECLiPSe stream which is not a <i>AsyncEclipseQueue</i> between ECLiPSe and 127 * this EclipseConnection: 128 * if it is, an <i>EclipseException</i> is thrown. Otherwise, a new 129 * <i>AsyncEclipseQueue</i> with the specified name is returned. 130 * 131 * 132 * @param name the name to be used for the stream representing the queue on 133 * the ECLiPSe side. 134 * @return a <i>AsyncEclipseQueue</i> object which can be used by Java 135 * to obtain an InputStream object (which can be used to read data from 136 * the queue which was written there by ECLiPSe) and/or an OutputStream 137 * object (which can be used to write data on the queue which can be read 138 * by ECLiPSe). 139 * @throws EclipseException if the name for the ECLiPSe stream is already in use, 140 * or ECLiPSe could not create its side of the queue for some reason. 141 * @throws IOException if there was an I/O problem while accessing ECLiPSe. 142 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 143 * been terminated. 144 */ 145 public AsyncEclipseQueue getAsyncEclipseQueue(String name) throws EclipseException, IOException; 146 147 /** 148 * Direct ECLiPSe to compile a named object file. 149 * 150 * @param file the path of the ECLiPSe object file which is to be compiled. 151 * 152 * @throws EclipseException if ECLiPSe failed or threw an exception whilst trying 153 * to compile the file. 154 * @throws IOException if there was an I/O problem while communicating with 155 * ECLiPSe. 156 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 157 * been terminated. 158 */ 159 public void compile(File f) throws EclipseException, IOException; 160 161 /** 162 * Convert a file path from the Java representation to the ECLiPSe 163 * representation. 164 * 165 * @param f the file path to be converted. 166 * 167 * @throws EclipseException if ECLiPSe failed or threw an exception whilst trying 168 * to convert the file path. 169 * @throws IOException if there was an I/O problem while communicating with 170 * ECLiPSe. 171 * @return a String: the file path in the ECLiPSe representation 172 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 173 * been terminated. 174 */ 175 public String getPath(File f) throws EclipseException, IOException; 176 177 178 /** 179 * Convenience <code>rpc</code> method. The user supplies the functor string and 180 * 1 argument. 181 * @see EclipseConnection#rpc(CompoundTerm) 182 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 183 * been terminated. 184 */ 185 public CompoundTerm rpc(String functor, Object arg1) throws EclipseException, IOException; 186 187 /** 188 * Convenience <code>rpc</code> method. The user supplies the functor string and 189 * 2 arguments. 190 * @see EclipseConnection#rpc(CompoundTerm) 191 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 192 * been terminated. 193 */ 194 public CompoundTerm rpc(String functor, Object arg1, 195 Object arg2) throws EclipseException, IOException; 196 197 /** 198 * Convenience <code>rpc</code> method. The user supplies the functor string and 199 * 3 arguments. 200 * @see EclipseConnection#rpc(CompoundTerm) 201 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 202 * been terminated. 203 */ 204 public CompoundTerm rpc(String functor, Object arg1, 205 Object arg2, Object arg3) throws EclipseException, IOException; 206 207 /** 208 * Convenience <code>rpc</code> method. The user supplies the functor string and 209 * 4 arguments. 210 * @see EclipseConnection#rpc(CompoundTerm) 211 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 212 * been terminated. 213 */ 214 public CompoundTerm rpc(String functor, Object arg1, 215 Object arg2, Object arg3, Object arg4) throws EclipseException, IOException; 216 217 /** 218 * Convenience <code>rpc</code> method. The user supplies the functor string and 219 * 5 arguments. 220 * @see EclipseConnection#rpc(CompoundTerm) 221 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 222 * been terminated. 223 */ 224 public CompoundTerm rpc(String functor, Object arg1, 225 Object arg2, Object arg3, Object arg4, 226 Object arg5) throws EclipseException, IOException; 227 228 /** 229 * Convenience <code>rpc</code> method. The user supplies the functor string and 230 * an array of arguments. 231 * @see EclipseConnection#rpc(CompoundTerm) 232 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 233 * been terminated. 234 */ 235 public CompoundTerm rpc(String functor, Object[] args) throws EclipseException, IOException; 236 237 /** 238 * Convenience <code>rpc</code> method. The user supplies an array. Element 0 239 * is the functor of the goal term and the remaining elements are the arguments. 240 * @see EclipseConnection#rpc(CompoundTerm) 241 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 242 * been terminated. 243 */ 244 public CompoundTerm rpc(Object[] goalTerm) throws EclipseException, IOException; 245 246 /** 247 * Return the name by which the peer representing the Java side of the 248 * connection is indexed in ECLiPSe. 249 * 250 * @return an Atom, the peer name. 251 */ 252 public Atom getPeerName(); 253 254 255 /** 256 * Register this peer as desiring participation in any multitasking 257 * phases that ECLiPSe enters. 258 * 259 * @param multitaskListener A listener whose methods are called when 260 * ECLiPSe enters/leaves multitasking phases. 261 * @throws EclipseException if registration fails or throws an 262 * ECLiPSe exception. 263 * @throws IOException if there was an I/O problem communicating with the 264 * ECLiPSe engine. 265 * @throws EclipseTerminatedException if this <i>EclipseConnection</i> has 266 * been terminated. 267 * @return An object which can be used to perform RPCs during 268 * ECLiPSe multitasking phases. */ 269 public EclipseMultitaskConnection registerMultitask(MultitaskListener multitaskListener) throws EclipseException,IOException; 270} 271