channeliface.java

这是外国一个开源推理机

/*
 *  Copyright (C) 2004 OntoText Lab, Sirma AI OOD
 *
 *  Address:
 *  Europe            135 Tsarigradsko Shose, Sofia 1784, Bulgaria
 *                    (IT Center Office Express, 3rd floor)
 *
 *  North America     438 Isabey Str, Suite 103, Montreal, Canada H4T 1V3
 *
 *  Phone: [phone]
 *  Fax: [phone]
 *
 *
 *  E-mail:                          [e-mail]
 *  Web:                             http://www.ontotext.com
 *  Sirma Group International Corp.  http://www.sirma.com
 *  Sirma AI Ltd.                    http://www.sirma.bg
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with this library; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

package org.openrdf.util.rmirouting;

/**
 * <p>Title: RMI routing</p>
 * <p>Description: The basic interface trough which all the routing occur.
 * </p>
 * <p>Copyright: Copyright (c) 2004</p>
 * <p>Company: <A href='www.ontotext.com'>Ontotext Lab. Sirma AI</A>, Bulgaria</p>
 * @author Damyan Ognyanoff
 * @version 1.0
 */
import java.rmi.Remote;
import java.rmi.RemoteException;

/**
 * This is the main interface through which we route the method invocations.
 * Here I give a short description of the lifecycle of a typical remote instance
 * that implements it and also will try clarify the usage of the methods by showing
 * when and why they are invoked.
 *
 * Lets begin with the usual initial use case - when a server needs to expose
 * an object implementing some, well known by the client, interfaces for a remote usage.
 * So what we need to do is to create a proxy that handles the method invokation
 * requests made by a client at server side.
 *
 * Once passed to the cleint, this server proxy should be wraped there in a way so that all
 * the method invokation requests to be received back here in the server then processed by the
 * 'real' target and the result received back to the client.
 *
 * In such a scheme the actual communincation between the client stub and the server
 * proxy is made through an remote instance implementing <code>ChannelIface</code>.
 * The tricky part is to construct the client wraper in a way to be undistinguisheable
 * from the server side object.
 *
 * To ease the situation a bit we need to restrict the objects that can be exposed
 * to only those which implements some set of interfaces that are well known
 * to both sides involved in such a routing scheme.
 *
 * So to archieve this, we use the <code>java.reflect.Proxy</code> to build a dynamic
 * proxy at client side, by passing a set of interfaces we need also an wraper
 * thet impelemnts <code>java.reflect.InvocationHandler</code>.
 *
 * Once created, such a client proxy will behave as an object that implpements all
 * those interfaces mentioned at create time and also the real invokation will be
 * passed to its method <code>invoke</code>. In that way we can easylypass these
 * requests to the server trough our interface.
 *
 * As you can imagine we use the <code>invoke</code> method to pass a method invocation
 * request from the client to serever.
 *
 * The method <code>getInterfaces</code> is when we build a client side wraper to get
 * a set of intefaces we need to apply to such a wraper
 *
 * Once the remote wraper is 'garabge collected' we use <code>gotFinalized</code> to notify
 * the server side part of the routing scheme that the last remote instance is not
 * used anymore and we can safely remove the remote instance from the RMI object table.
 * Just to mention that all the instances of <code>ChannelIfaceImpl</code> are kept
 * on the server in a table so to be resoved to the real instances they wrap, when such a need occur.
 * as an example ot such case is a when we receive as an argument of a method being
 * invoked a, previously created by this server, proxy.
 *
 * @see ChannelIfaceImpl
 * @see ChannelIfaceInvocation
 *
 */
public interface ChannelIface extends Remote {

  /**
   * Method <code>invoke</code> is used to send/receive a method invokation request
   * from a client to the object server. The actual method being invoked is desribed
   * in <code>method</code> argument and is identified by its name followed by the
   * names of the classes of the expected arguments (as they appear in the declaration).
   * @param method the method description
   * @param args the real arguments to be used
   * @return what value the invoked method returns or <code>null</code> if it is a <code>void</code>.
   * @throws RemoteException which wraps as a <code>cause</code> what an Exception, the invoked
   * method throws.
   */
  public Object invoke(Object method, Object[] args) throws RemoteException;

  /**
   * <code>getInterfaces</code> return all the interfaces implemented by the wraped instance
   * as an array of strings. It goes down through the class hierarchy to the <code>Object</code> class
   * and collect all the implemented interfaces by eny of the mentioned classes
   * in the subclass chain.
   * @return an String[] with the names of the implemented interfaces by the wraped instance.
   * @throws RemoteException in a case of unexpected contition
   */
  public String[] getInterfaces() throws RemoteException;

  /**
   * <code>gotFinalized</code> should be invoked through the <code>finalize</code>
   * when the client garbage collector clears the remote wraper of a serfer stub.
   * In This way we can remove the stub from our Object table and release it for CG
   * in server side
   * @throws RemoteException in a case of unexpected contition
   */
  public void gotFinalized() throws RemoteException;

  /**
   * <code>batch</code> is used to send several method invocation requests in
   * a single remote call. It can batch only <code>void</code> methods which
   * arguments are either <code>java.io.Serializable</code> or native (e.g. byte, long, etc.)
   * @param jobs
   * @throws RemoteException which wraps as a <code>cause</code> what an Exception, any
   * of the invoked methods throws.
   */
  public void batch(Object[] jobs) throws RemoteException;
}