Source for javax.rmi.CORBA.Stub

   1: /* Stub.java --
   2:    Copyright (C) 2004, 2004, 2005 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package javax.rmi.CORBA;
  40: 
  41: import gnu.javax.rmi.CORBA.DelegateFactory;
  42: import gnu.javax.rmi.CORBA.StubDelegateImpl;
  43: 
  44: import java.io.IOException;
  45: import java.io.ObjectInputStream;
  46: import java.io.ObjectOutputStream;
  47: import java.io.Serializable;
  48: import java.rmi.RemoteException;
  49: 
  50: import javax.rmi.PortableRemoteObject;
  51: 
  52: import org.omg.CORBA.ORB;
  53: import org.omg.CORBA_2_3.portable.ObjectImpl;
  54: 
  55: /**
  56:  * A Stub descendants provide access to the object on the client side. This base
  57:  * class implements methods, required for remote or local invocation using CORBA
  58:  * mechanisms. The most of the functionality is forwarded to the stub delegate.
  59:  * This delegate can be altered by setting the system property
  60:  * "javax.rmi.CORBA.StubClass" to the name of the alternative class that must
  61:  * implement {@link StubDelegate}. Hence Stub contains two delegates, one for
  62:  * Stub-related operations and another inherited from the ObjectImpl.
  63:  * 
  64:  * @specnote GNU Classpath uses separate delegate per each Stub. The delegate
  65:  * holds information about the ORB and other data, specific for the each Stub.
  66:  * 
  67:  * @author Audrius Meskauskas (AudriusA@Bioinformatics.org)
  68:  */
  69: public abstract class Stub
  70:   extends ObjectImpl
  71:   implements Serializable
  72: {
  73:   /**
  74:    * For compatability with Sun's JDK 1.4.2 rev. 5
  75:    */
  76:   private static final long serialVersionUID = 1087775603798577179L;
  77: 
  78:   /**
  79:    * The hashcode, computed once (expensive operation).
  80:    */
  81:   transient int m_hash = Integer.MIN_VALUE;
  82: 
  83:   /**
  84:    * The stringified reference, computed once (expensive operation).
  85:    */
  86:   transient String m_ior;
  87: 
  88:   /**
  89:    * The ORB, where the stub is connected on the client side.
  90:    */
  91:   transient ORB m_orb;
  92: 
  93:   /**
  94:    * The associated delegate, responsible for the major of the functionality of
  95:    * this stub.
  96:    */
  97:   static StubDelegate delegate = (StubDelegate) DelegateFactory.getInstance(DelegateFactory.STUB);
  98: 
  99:   /**
 100:    * Returns the same hashcode for all stubs that point to the same remote
 101:    * object.
 102:    */
 103:   public int hashCode()
 104:   {
 105:     if (m_hash == Integer.MIN_VALUE)
 106:       m_hash = delegate.hashCode(this);
 107:     // This should finally result to the IOR comparison.
 108:     return m_hash;
 109:   }
 110: 
 111:   /**
 112:    * The stubs are equal if they point to the same remote object.
 113:    */
 114:   public boolean equals(java.lang.Object obj)
 115:   {
 116:     return delegate.equals(this, obj);
 117:   }
 118: 
 119:   /**
 120:    * Get the string representation of this Stub.
 121:    * 
 122:    * @return the CORBA IOR reference.
 123:    */
 124:   public String toString()
 125:   {
 126:     if (m_ior == null)
 127:       m_ior = delegate.toString(this);
 128:     return m_ior;
 129:   }
 130: 
 131:   /**
 132:    * <p>
 133:    * Finds the suitable {@link Tie} for this Stub and connects it to the given
 134:    * ORB. The tie is found by the name pattern. If the found tie is derived from
 135:    * {@link org.omg.CORBA.PortableServer.Servant}, it is connected to the root
 136:    * POA, also activating it (if not already active).
 137:    * </p>
 138:    * <p>
 139:    * This method does not allow to specify, to which POA the found Tie must be
 140:    * connected and requires to use the deprecated method {@link ORB#connect}.
 141:    * Many useful POA features remain unaccessible. A better alternative it might
 142:    * be to generate a {@link org.omg.CORBA.PortableServer.Servant} - derived Tie
 143:    * (-poa key in rmic) and connect it to POA in one of the many ways, listed in
 144:    * the description of the {@link orb.omg.PortableServer} package). The
 145:    * obtained CORBA object can be narrowed into stub using
 146:    * {@link PortableRemoteObject#narrow}.
 147:    * </p>
 148:    * <p>
 149:    * It is frequently easier to call {@link PortableRemoteObject#connect} rather
 150:    * than this method.
 151:    * </p>
 152:    * 
 153:    * @param orb the ORB where the Stub must be connected.
 154:    * 
 155:    * @throws RemoteException if the stub is already connected to some other ORB.
 156:    * If the stub is already connected to the ORB that was passed as parameter,
 157:    * the method returns without action.
 158:    * 
 159:    * @throws BAD_PARAM if the name of this stub does not match the stub name
 160:    * pattern, "_*_Stub" or if the Tie class, "_*Impl_Tie", does not exists or an
 161:    * instance of this class cannot be instantiated.
 162:    */
 163:   public void connect(ORB orb)
 164:     throws RemoteException
 165:   {
 166:     if (m_orb != null && orb != null)
 167:       {
 168:         if (m_orb.equals(orb))
 169:           throw new RemoteException("Stub " + this
 170:             + " is connected to another ORB, " + orb);
 171:         else
 172:           return;
 173:       }
 174:     m_orb = orb;
 175:     delegate.connect(this, orb);
 176:   }
 177: 
 178:   /**
 179:    * Required by serialized form of Java API doc.
 180:    */
 181:   private void readObject(ObjectInputStream input)
 182:     throws IOException, ClassNotFoundException
 183:   {
 184:     if (delegate instanceof StubDelegateImpl)
 185:       ((StubDelegateImpl) delegate).readObject(this, input, m_orb);
 186:     else
 187:       delegate.readObject(this, input);
 188:   }
 189: 
 190:   /**
 191:    * Required by serialized form of Java API doc.
 192:    */
 193:   private void writeObject(ObjectOutputStream output)
 194:     throws IOException
 195:   {
 196:     // The m_orb in this case may be either known or not.
 197:     if (delegate instanceof StubDelegateImpl)
 198:       ((StubDelegateImpl) delegate).writeObject(this, output, m_orb);
 199:     else
 200: 
 201:       delegate.writeObject(this, output);
 202:   }