bundles/org.simantics.databoard/src/org/simantics/databoard/method/MethodInterface.java

   1 /*******************************************************************************\r
   2  *  Copyright (c) 2010 Association for Decentralized Information Management in\r
   3  *  Industry THTH ry.\r
   4  *  All rights reserved. This program and the accompanying materials\r
   5  *  are made available under the terms of the Eclipse Public License v1.0\r
   6  *  which accompanies this distribution, and is available at\r
   7  *  http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  *  Contributors:\r
  10  *      VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.databoard.method;
  13
  14 import java.util.concurrent.TimeUnit;\r
  15 \r
  16 import org.simantics.databoard.Datatypes;\r
  17
  18 /**\r
  19  * MethodInterface is an interface for invoking methods.<p>
  20  *\r
  21  * If MethodInterface is executed on TCP/IP socket, the current\r
  22  * Connection can be acquired with Connection#getCurrentConnection().\r
  23  * You can attach close listener this way.<p>\r
  24  * \r
  25  * MethodInterface may be used from multiple-threads simultaneously.
  26  *
  27  * @see Server puts a MethodInterface in a server socket
  28  * @see Client creates a MethodInterface from a socket connection
  29  * @see Datatypes to create MethodInterface from an interface
  30  * @see Datatypes to create MethodInterface implementation from an object
  31  * @author Toni Kalajainen <toni.kalajainen@vtt.fi>
  32  * @author Hannu Niemisto
  33  */
  34 public interface MethodInterface {
  35
  36         /**
  37          * Get method descriptions
  38          *
  39          * @return method descriptions
  40          */
  41         Interface getInterface();
  42
  43         /**
  44          * Get an access to the implementation of a method. The binding is suggested by the producer.
  45          *
  46          * @param description method description
  47          * @return method access
  48          * @throws MethodNotSupportedException
  49          */
  50         Method getMethod(MethodTypeDefinition description)
  51         throws MethodNotSupportedException;
  52
  53         /**
  54          * Get an access to the implementation of a method. The binding is suggested by the consumer.
  55          *
  56          * @param binding binding to use
  57          * @return method access
  58          * @throws MethodNotSupportedException
  59          */
  60         Method getMethod(MethodTypeBinding binding)
  61         throws MethodNotSupportedException;
  62
  63         /**
  64          * Access to the implementation of a method.
  65          */
  66         public interface Method {
  67                 AsyncResult invoke(Object request);
  68                 MethodTypeBinding getMethodBinding();
  69         }
  70
  71         public interface AsyncResult {
  72
  73                 /**
  74                  * Add a listener. It will be notified immediately if the response is
  75                  * available.
  76                  *
  77                  * @param listener (listener may not block) or null to remove listener
  78                  */
  79                 void setListener(InvokeListener listener);
  80
  81                 /**
  82                  *
  83                  * @return response or null
  84                  */
  85                 Object getResponse();
  86
  87                 Object getExecutionError();
  88
  89                 InvokeException getInvokeException();
  90
  91                 AsyncRequestStatus getStatus();
  92
  93                 /**
  94                  *
  95                  * @return response
  96                  * @throws InterruptedException block was canceled
  97                  * @throws InvokeException network error, e.g. IOException of MethodNotSupportedException
  98                  * @throws ExecutionError error that occured while executing the method
  99                  */
 100                 Object waitForResponse()
 101                 throws InvokeException, ExecutionError, InterruptedException;
 102
 103                 /**
 104                  *
 105                  * @return response
 106                  * @throws InterruptedException
 107                  * @throws InvokeException network error, e.g. IOException of MethodNotSupportedException
 108                  * @throws ExecutionError error that occured while executing the method
 109                  */
 110                 Object waitForResponse(long timeout, TimeUnit unit)
 111                 throws InvokeException, ExecutionError, InterruptedException;
 112
 113         }
 114
 115         enum AsyncRequestStatus {Waiting, Succeed, Failed}
 116
 117         public interface InvokeListener {
 118                 void onCompleted(Object result);
 119                 void onExecutionError(Object error);
 120                 void onException(Exception cause);
 121         }
 122
 123         /**
 124          * A wrapper to an error that occured in the execution of the method.
 125          */
 126         public static class ExecutionError extends Exception {
 127                 private static final long serialVersionUID = 1L;
 128                 Object error;
 129                 public ExecutionError(Object error) {
 130                         this.error = error;
 131                 }
 132                 public Object getError() {
 133                         return error;
 134                 }
 135         }
 136
 137 }
 138