/*

 * Copyright (c) 1995, 2009, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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 General Public License

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package org.omg.CORBA;

import org.omg.CORBA.portable.*;

import org.omg.CORBA.ORBPackage.InvalidName;

import java.util.Properties;

import java.applet.Applet;

import java.io.File;

import java.io.FileInputStream;

import java.security.AccessController;

import java.security.PrivilegedAction;

/**

 * A class providing APIs for the CORBA Object Request Broker

 * features.  The <code>ORB</code> class also provides

 * "pluggable ORB implementation" APIs that allow another vendor's ORB

 * implementation to be used.

 * <P>

 * An ORB makes it possible for CORBA objects to communicate

 * with each other by connecting objects making requests (clients) with

 * objects servicing requests (servers).

 * <P>

 *

 * The <code>ORB</code> class, which

 * encapsulates generic CORBA functionality, does the following:

 * (Note that items 5 and 6, which include most of the methods in

 * the class <code>ORB</code>, are typically used with the <code>Dynamic Invocation

 * Interface</code> (DII) and the <code>Dynamic Skeleton Interface</code>

 * (DSI).

 * These interfaces may be used by a developer directly, but

 * most commonly they are used by the ORB internally and are

 * not seen by the general programmer.)

 * <OL>

 * <li> initializes the ORB implementation by supplying values for

 *      predefined properties and environmental parameters

 * <li> obtains initial object references to services such as

 * the NameService using the method <code>resolve_initial_references</code>

 * <li> converts object references to strings and back

 * <li> connects the ORB to a servant (an instance of a CORBA object

 * implementation) and disconnects the ORB from a servant

 * <li> creates objects such as

 *   <ul>

 *   <li><code>TypeCode</code>

 *   <li><code>Any</code>

 *   <li><code>NamedValue</code>

 *   <li><code>Context</code>

 *   <li><code>Environment</code>

 *   <li>lists (such as <code>NVList</code>) containing these objects

 *   </ul>

 * <li> sends multiple messages in the DII

 * </OL>

 *

 * <P>

 * The <code>ORB</code> class can be used to obtain references to objects

 * implemented anywhere on the network.

 * <P>

 * An application or applet gains access to the CORBA environment

 * by initializing itself into an <code>ORB</code> using one of

 * three <code>init</code> methods.  Two of the three methods use the properties

 * (associations of a name with a value) shown in the

 * table below.<BR>

 * <TABLE BORDER=1 SUMMARY="Standard Java CORBA Properties">

 * <TR><TH>Property Name</TH>   <TH>Property Value</TH></TR>

 * <CAPTION>Standard Java CORBA Properties:</CAPTION>

 *     <TR><TD>org.omg.CORBA.ORBClass</TD>

 *     <TD>class name of an ORB implementation</TD></TR>

 *     <TR><TD>org.omg.CORBA.ORBSingletonClass</TD>

 *     <TD>class name of the ORB returned by <code>init()</code></TD></TR>

 * </TABLE>

 * <P>

 * These properties allow a different vendor's <code>ORB</code>

 * implementation to be "plugged in."

 * <P>

 * When an ORB instance is being created, the class name of the ORB

 * implementation is located using

 * the following standard search order:<P>

 *

 * <OL>

 *     <LI>check in Applet parameter or application string array, if any

 *

 *     <LI>check in properties parameter, if any

 *

 *     <LI>check in the System properties

 *

 *     <LI>check in the orb.properties file located in the user.home

 *         directory (if any)

 *

 *     <LI>check in the orb.properties file located in the java.home/lib

 *         directory (if any)

 *

 *     <LI>fall back on a hardcoded default behavior (use the Java&nbsp;IDL

 *         implementation)

 * </OL>

 * <P>

 * Note that Java IDL provides a default implementation for the

 * fully-functional ORB and for the Singleton ORB.  When the method

 * <code>init</code> is given no parameters, the default Singleton

 * ORB is returned.  When the method <code>init</code> is given parameters

 * but no ORB class is specified, the Java IDL ORB implementation

 * is returned.

 * <P>

 * The following code fragment creates an <code>ORB</code> object

 * initialized with the default ORB Singleton.

 * This ORB has a

 * restricted implementation to prevent malicious applets from doing

 * anything beyond creating typecodes.

 * It is called a singleton

 * because there is only one instance for an entire virtual machine.

 * <PRE>

 *    ORB orb = ORB.init();

 * </PRE>

 * <P>

 * The following code fragment creates an <code>ORB</code> object

 * for an application.  The parameter <code>args</code>

 * represents the arguments supplied to the application's <code>main</code>

 * method.  Since the property specifies the ORB class to be

 * "SomeORBImplementation", the new ORB will be initialized with

 * that ORB implementation.  If p had been null,

 * and the arguments had not specified an ORB class,

 * the new ORB would have been

 * initialized with the default Java IDL implementation.

 * <PRE>

 *    Properties p = new Properties();

 *    p.put("org.omg.CORBA.ORBClass", "SomeORBImplementation");

 *    ORB orb = ORB.init(args, p);

 * </PRE>

 * <P>

 * The following code fragment creates an <code>ORB</code> object

 * for the applet supplied as the first parameter.  If the given

 * applet does not specify an ORB class, the new ORB will be

 * initialized with the default Java IDL implementation.

 * <PRE>

 *    ORB orb = ORB.init(myApplet, null);

 * </PRE>

 * <P>

 * An application or applet can be initialized in one or more ORBs.

 * ORB initialization is a bootstrap call into the CORBA world.

 * @since   JDK1.2

 */

abstract public class ORB {

    //

    // This is the ORB implementation used when nothing else is specified.

    // Whoever provides this class customizes this string to

    // point at their ORB implementation.

    //

    private static final String ORBClassKey = "org.omg.CORBA.ORBClass";

    private static final String ORBSingletonClassKey = "org.omg.CORBA.ORBSingletonClass";

    //

    // The last resort fallback ORB implementation classes in case

    // no ORB implementation class is dynamically configured through

    // properties or applet parameters. Change these values to

    // vendor-specific class names.

    //

    private static final String defaultORB = "com.sun.corba.se.impl.orb.ORBImpl";

    private static final String defaultORBSingleton = "com.sun.corba.se.impl.orb.ORBSingleton";

    //

    // The global instance of the singleton ORB implementation which

    // acts as a factory for typecodes for generated Helper classes.

    // TypeCodes should be immutable since they may be shared across

    // different security contexts (applets). There should be no way to

    // use a TypeCode as a storage depot for illicitly passing

    // information or Java objects between different security contexts.

    //

    static private ORB singleton;

    // Get System property

    private static String getSystemProperty(final String name) {

        // This will not throw a SecurityException because this

        // class was loaded from rt.jar using the bootstrap classloader.

        String propValue = (String) AccessController.doPrivileged(

            new PrivilegedAction() {

                public java.lang.Object run() {

                    return System.getProperty(name);

                }

            }

        );

        return propValue;

    }

    // Get property from orb.properties in either <user.home> or <java-home>/lib

    // directories.

    private static String getPropertyFromFile(final String name) {

        // This will not throw a SecurityException because this

        // class was loaded from rt.jar using the bootstrap classloader.

        String propValue = (String) AccessController.doPrivileged(

            new PrivilegedAction() {

                private Properties getFileProperties( String fileName ) {

                    try {

                        File propFile = new File( fileName ) ;

                        if (!propFile.exists())

                            return null ;

                        Properties props = new Properties() ;

                        FileInputStream fis = new FileInputStream(propFile);

                        try {

                            props.load( fis );

                        } finally {

                            fis.close() ;

                        }

                        return props ;

                    } catch (Exception exc) {

                        return null ;

                    }

                }

                public java.lang.Object run() {

                    String userHome = System.getProperty("user.home");

                    String fileName = userHome + File.separator +

                        "orb.properties" ;

                    Properties props = getFileProperties( fileName ) ;

                    if (props != null) {

                        String value = props.getProperty( name ) ;

                        if (value != null)

                            return value ;

                    }

                    String javaHome = System.getProperty("java.home");

                    fileName = javaHome + File.separator

                        + "lib" + File.separator + "orb.properties";

                    props = getFileProperties( fileName ) ;

                    if (props == null)

                        return null ;

                    else

                        return props.getProperty( name ) ;

                }

            }

        );

        return propValue;

    }

    /**

     * Returns the <code>ORB</code> singleton object. This method always returns the

     * same ORB instance, which is an instance of the class described by the

     * <code>org.omg.CORBA.ORBSingletonClass</code> system property.

     * <P>

     * This no-argument version of the method <code>init</code> is used primarily

     * as a factory for <code>TypeCode</code> objects, which are used by

     * <code>Helper</code> classes to implement the method <code>type</code>.

     * It is also used to create <code>Any</code> objects that are used to

     * describe <code>union</code> labels (as part of creating a <code>

     * TypeCode</code> object for a <code>union</code>).

     * <P>

     * This method is not intended to be used by applets, and in the event

     * that it is called in an applet environment, the ORB it returns

     * is restricted so that it can be used only as a factory for

     * <code>TypeCode</code> objects.  Any <code>TypeCode</code> objects

     * it produces can be safely shared among untrusted applets.

     * <P>

     * If an ORB is created using this method from an applet,

     * a system exception will be thrown if

     * methods other than those for

     * creating <code>TypeCode</code> objects are invoked.

     *

     * @return the singleton ORB

     */

    public static synchronized ORB init() {

        if (singleton == null) {

            String className = getSystemProperty(ORBSingletonClassKey);

            if (className == null)

                className = getPropertyFromFile(ORBSingletonClassKey);

            if (className == null)

                className = defaultORBSingleton;

            singleton = create_impl(className);

        }

        return singleton;

    }

    private static ORB create_impl(String className) {

        ClassLoader cl = Thread.currentThread().getContextClassLoader();

        if (cl == null)

            cl = ClassLoader.getSystemClassLoader();

        try {

            return (ORB) Class.forName(className, true, cl).newInstance();

        } catch (Throwable ex) {

            SystemException systemException = new INITIALIZE(

               "can't instantiate default ORB implementation " + className);

            systemException.initCause(ex);

            throw systemException;

        }

    }

    /**

     * Creates a new <code>ORB</code> instance for a standalone

     * application.  This method may be called from applications

     * only and returns a new fully functional <code>ORB</code> object

     * each time it is called.

     * @param args command-line arguments for the application's <code>main</code>

     *             method; may be <code>null</code>

     * @param props application-specific properties; may be <code>null</code>

     * @return the newly-created ORB instance

     */

    public static ORB init(String[] args, Properties props) {

        //

        // Note that there is no standard command-line argument for

        // specifying the default ORB implementation. For an

        // application you can choose an implementation either by

        // setting the CLASSPATH to pick a different org.omg.CORBA

        // and it's baked-in ORB implementation default or by

        // setting an entry in the properties object or in the

        // system properties.

        //

        String className = null;

        ORB orb;

        if (props != null)

            className = props.getProperty(ORBClassKey);

        if (className == null)

            className = getSystemProperty(ORBClassKey);

        if (className == null)

            className = getPropertyFromFile(ORBClassKey);

        if (className == null)

            className = defaultORB;

        orb = create_impl(className);

        orb.set_parameters(args, props);

        return orb;

    }

    /**

     * Creates a new <code>ORB</code> instance for an applet.  This

     * method may be called from applets only and returns a new

     * fully-functional <code>ORB</code> object each time it is called.

     * @param app the applet; may be <code>null</code>

     * @param props applet-specific properties; may be <code>null</code>

     * @return the newly-created ORB instance

     */

    public static ORB init(Applet app, Properties props) {

        String className;

        ORB orb;

        className = app.getParameter(ORBClassKey);

        if (className == null && props != null)

            className = props.getProperty(ORBClassKey);

        if (className == null)

            className = getSystemProperty(ORBClassKey);

        if (className == null)

            className = getPropertyFromFile(ORBClassKey);

        if (className == null)

            className = defaultORB;

        orb = create_impl(className);

        orb.set_parameters(app, props);

        return orb;

    }

    /**

     * Allows the ORB implementation to be initialized with the given

     * parameters and properties. This method, used in applications only,

     * is implemented by subclass ORB implementations and called

     * by the appropriate <code>init</code> method to pass in its parameters.

     *

     * @param args command-line arguments for the application's <code>main</code>

     *             method; may be <code>null</code>

     * @param props application-specific properties; may be <code>null</code>

     */

    abstract protected void set_parameters(String[] args, Properties props);

    /**

     * Allows the ORB implementation to be initialized with the given

     * applet and parameters. This method, used in applets only,

     * is implemented by subclass ORB implementations and called

     * by the appropriate <code>init</code> method to pass in its parameters.

     *

     * @param app the applet; may be <code>null</code>

     * @param props applet-specific properties; may be <code>null</code>

     */

    abstract protected void set_parameters(Applet app, Properties props);

    /**

     * Connects the given servant object (a Java object that is

     * an instance of the server implementation class)

     * to the ORB. The servant class must

     * extend the <code>ImplBase</code> class corresponding to the interface that is

     * supported by the server. The servant must thus be a CORBA object

     * reference, and inherit from <code>org.omg.CORBA.Object</code>.

     * Servants created by the user can start receiving remote invocations

     * after the method <code>connect</code> has been called. A servant may also be

     * automatically and implicitly connected to the ORB if it is passed as

     * an IDL parameter in an IDL method invocation on a non-local object,

     * that is, if the servant object has to be marshalled and sent outside of the

     * process address space.

     * <P>

     * Calling the method <code>connect</code> has no effect

     * when the servant object is already connected to the ORB.

     * <P>

     * Deprecated by the OMG in favor of the Portable Object Adapter APIs.

     *

     * @param obj The servant object reference

     */

    public void connect(org.omg.CORBA.Object obj) {

        throw new NO_IMPLEMENT();

    }

    /**

     * Destroys the ORB so that its resources can be reclaimed.

     * Any operation invoked on a destroyed ORB reference will throw the

     * <code>OBJECT_NOT_EXIST</code> exception.

     * Once an ORB has been destroyed, another call to <code>init</code>

     * with the same ORBid will return a reference to a newly constructed ORB.<p>

     * If <code>destroy</code> is called on an ORB that has not been shut down,

     * it will start the shut down process and block until the ORB has shut down

     * before it destroys the ORB.<br>

     * If an application calls <code>destroy</code> in a thread that is currently servicing

     * an invocation, the <code>BAD_INV_ORDER</code> system exception will be thrown

     * with the OMG minor code 3, since blocking would result in a deadlock.<p>

     * For maximum portability and to avoid resource leaks, an application should

     * always call <code>shutdown</code> and <code>destroy</code>

     * on all ORB instances before exiting.

     *

     * @throws org.omg.CORBA.BAD_INV_ORDER if the current thread is servicing an invocation

     */

    public void destroy( ) {

        throw new NO_IMPLEMENT();

    }

    /**

     * Disconnects the given servant object from the ORB. After this method returns,

     * the ORB will reject incoming remote requests for the disconnected

     * servant and will send the exception

     * <code>org.omg.CORBA.OBJECT_NOT_EXIST</code> back to the

     * remote client. Thus the object appears to be destroyed from the

     * point of view of remote clients. Note, however, that local requests issued

     * using the servant  directly do not

     * pass through the ORB; hence, they will continue to be processed by the

     * servant.

     * <P>

     * Calling the method <code>disconnect</code> has no effect

     * if the servant is not connected to the ORB.

     * <P>

     * Deprecated by the OMG in favor of the Portable Object Adapter APIs.

     *

     * @param obj The servant object to be disconnected from the ORB

     */

    public void disconnect(org.omg.CORBA.Object obj) {

        throw new NO_IMPLEMENT();

    }

    //

    // ORB method implementations.

    //

    // We are trying to accomplish 2 things at once in this class.

    // It can act as a default ORB implementation front-end,

    // creating an actual ORB implementation object which is a

    // subclass of this ORB class and then delegating the method

    // implementations.

    //

    // To accomplish the delegation model, the 'delegate' private instance

    // variable is set if an instance of this class is created directly.

    //

    /**

     * Returns a list of the initially available CORBA object references,

     * such as "NameService" and "InterfaceRepository".

     *

     * @return an array of <code>String</code> objects that represent

     *         the object references for CORBA services

     *         that are initially available with this ORB

     */

    abstract public String[] list_initial_services();

    /**

     * Resolves a specific object reference from the set of available

     * initial service names.

     *

     * @param object_name the name of the initial service as a string

     * @return  the object reference associated with the given name

     * @exception InvalidName if the given name is not associated with a

     *                         known service

     */

    abstract public org.omg.CORBA.Object resolve_initial_references(String object_name)

        throws InvalidName;

    /**

     * Converts the given CORBA object reference to a string.

     * Note that the format of this string is predefined by IIOP, allowing

     * strings generated by a different ORB to be converted back into an object

     * reference.

     * <P>

     * The resulting <code>String</code> object may be stored or communicated

     * in any way that a <code>String</code> object can be manipulated.

     *

     * @param obj the object reference to stringify

     * @return the string representing the object reference

     */

    abstract public String object_to_string(org.omg.CORBA.Object obj);

    /**