Source for org.omg.PortableInterceptor.ORBInitializer

   1: /* ORBInitializer.java --
   2:    Copyright (C) 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 org.omg.PortableInterceptor;
  40: 
  41: import org.omg.CORBA.Object;
  42: import org.omg.CORBA.portable.IDLEntity;
  43: 
  44: /**
  45:  * <p>
  46:  * Registers the interceptor.
  47:  *
  48:  * Direct interceptor registration would open a security hole. Hence instead the
  49:  * interceptors from the ORB.init(..) method, passing the names of the needed
  50:  * initialized classes via properties.
  51:  * </p>
  52:  * <p>
  53:  * These property names are of the form
  54:  * </p>
  55:  * <p><i>org.omg.PortableInterceptor.ORBInitializerClass.&lt;Service&gt;</i></p>
  56:  * where <i>&lt;Service&gt;</i> is the string name of a class, which implements
  57:  * {@link ORBInitializer}. During <code>ORB.init(..)</code>, the properties
  58:  * begining with <i>org.omg.PortableInterceptor.ORBInitializerClass</i> are
  59:  * collected, the <i>&lt;Service&gt;</i> portion of each property is extracted,
  60:  * the initialiser is instantiated with the <i>&lt;Service&gt;</i> string as its
  61:  * class name and then <code>pre_init</code> and <code>post_init</code>
  62:  * (defined in {@link ORBInitializerOperations}) are called on that initializer.
  63:  * The runtime exceptions, thrown by these two methods, are ignored.
  64:  * </p>
  65:  * <p>
  66:  * <h3>Example</h3>
  67:  * A client-side logging service may have the following ORBInitializer
  68:  * implementation:
  69:  *
  70:  * <code><pre>
  71:  * package gnu.x.logging;
  72:  *
  73:  * import org.omg.PortableInterceptor.*;
  74:  * import org.omg.CORBA.LocalObject;
  75:  *
  76:  * public class LoggingService extends LocalObject implements ORBInitializer
  77:  * {
  78:  *   public void pre_init (ORBInitInfo info)
  79:  *     {
  80:  *       // More than one interceptor can be registered.
  81:  *       ServerRequestInterceptor log_requests = new rLoggingInterceptor();
  82:  *       info.add_server_request_interceptor(log_requests);
  83:  *
  84:  *       IORInterceptor log_iors = new iLoggingInterceptor();
  85:  *       info.add_ior_interceptor(log_iors);
  86:  *     }
  87:  *
  88:  *   public void post_init (ORBInitInfo info)
  89:  *     {
  90:  *       // Unused.
  91:  *     }
  92:  * }
  93:  * </code></pre>
  94:  * <p>
  95:  * Then, one of the used set of properties then must contain the property, named
  96:  * <i>
  97:  * org.omg.PortableInterceptor.ORBInitializerClass.gnu.x.Logging.LoggingService
  98:  * </i>.
  99:  * The value of the property is ignored and may empty string. The
 100:  * agreed locations, where this property will be searched for, are:
 101:  * </p><p>
 102:  * 1. The properties parameter in the ORB.init(..), if any.<br>
 103:  * 2. The System properties.<br>
 104:  * 3. The orb.properties file located in the user.home directory (if any).<br>
 105:  * 4. The orb.properties file located in the java.home/lib directory (if any).
 106:  * </p>
 107:  * <p>
 108:  * The applet parameters and command line arguments are <i>not</i> scanned
 109:  * for the possible initializers.
 110:  * </p>
 111:  * <p>
 112:  * Interceptors are registered on a per-ORB basis. The virtual per-object
 113:  * Interceptors can be simulated by checking the policies on the target from
 114:  * within the interception points to determine whether they should work. The
 115:  * virtual per-POA Interceptors can be obtained instantiating each POA such with
 116:  * a different ORB.
 117:  * </p>
 118:  * <p>
 119:  * The registration code should not call directly any methods on the ORB being
 120:  * registered.
 121:  * </p>
 122:  * <p>
 123:  * The new interceptors cannot be registered after the ORB.init(..) returns.
 124:  * </p>
 125:  *
 126:  * @author Audrius Meskauskas, Lithuania (AudriusA@Bioinformatics.org)
 127:  */
 128: public interface ORBInitializer extends ORBInitializerOperations,
 129:   Object,
 130:   IDLEntity
 131: {