1   /**
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   package org.apache.openejb.spi;
   18   
   19   import javax.ejb.EJBHome;
   20   import javax.ejb.EJBMetaData;
   21   import javax.ejb.EJBObject;
   22   import javax.ejb.Handle;
   23   import javax.ejb.HomeHandle;
   24   
   25   import org.apache.openejb.ProxyInfo;
   26   
   27   /**
   28    * <h2><b>LOCAL to REMOTE SERIALIZATION</b></h2> <p>
   29    *
   30    * <i>Definition:</i><p>
   31    *     This is a serialization that initiates in the local vm, but
   32    *     is outside the scope of a marked IntraVM local serialization.
   33    * <p>
   34    * <i>Circumstances:</i><p>
   35    *     When an IntraVM implementation of a javax.ejb.* interface is
   36    *     serialized outside the scope of the IntraVM Server
   37    *     <p>
   38    *     These serializations happen when objects are sent from a
   39    *     local bean to a remote client as part of a return value, or
   40    *     when a stateful session bean is passified.
   41    * <p>
   42    * <i>Action:</i><p>
   43    *     Don't serialize the IntraVM javax.ejb.* interface
   44    *     implementation, instead ask the ApplicationServer to nominate
   45    *     its own implementation as a replacement.  This is done via
   46    *     the org.apache.openejb.spi.ApplicationServer interface.
   47    * <p>
   48    * <i>Example Scenario:</i><p>
   49    *     SERIALIZATION<br>
   50    * <br>1.  ObjectOutputStream encounters an IntraVmMetaData instance
   51    *         in the object graph and calls its writeReplace method.
   52    * <br>2.  The IntraVmMetaData instance determines it is being
   53    *         serialized outside the scope of an IntraVM serialization
   54    *         by calling IntraVmCopyMonitor.isIntraVmCopyOperation().
   55    * <br>3.  The IntraVmMetaData instance calls the getEJBMetaData
   56    *         method on the ApplicationServer.
   57    * <br>4.  The IntraVmMetaData instance returns the
   58    *         ApplicationServer's EJBMetaData instance from the
   59    *         writeReplace method.
   60    * <br>5.  The ObjectOutputStream serializes the ApplicationServer's
   61    *         EJBMetaData instance in place of the IntraVmMetaData
   62    *         instance.
   63    *         <p>
   64    *         Note:  The ApplicationServer's EJBMetaData instance can
   65    *         be any object that implements the javax.ejb.EJBMetaData
   66    *         interface and can also implement any serialization
   67    *         methods, such as the writeReplace method, to nominate a
   68    *         replacement or implement protocol specific logic or
   69    *         otherwise gain control over the serialization of
   70    *         EJBMetaData instances destined for its remote clients.
   71    *         <p>
   72    *     DESERIALIZATION<p>
   73    *         The deserialization of the Application Server's
   74    *         javax.ejb.* implementations is implementation specific.
   75    * <p>
   76    *
   77    * @version $Revision: 534559 $ $Date: 2007-05-02 10:29:36 -0700 (Wed, 02 May 2007) $
   78    */
   79   public interface ApplicationServer {
   80   
   81       public EJBMetaData getEJBMetaData(ProxyInfo proxyInfo);
   82   
   83       public Handle getHandle(ProxyInfo proxyInfo);
   84   
   85       public HomeHandle getHomeHandle(ProxyInfo proxyInfo);
   86   
   87       public EJBObject getEJBObject(ProxyInfo proxyInfo);
   88   
   89       public Object getBusinessObject(ProxyInfo proxyInfo);
   90   
   91       public EJBHome getEJBHome(ProxyInfo proxyInfo);
   92   
   93   }