/*
 * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package com.sun.corba.se.spi.presentation.rmi ;

import java.util.Map ;

import java.lang.reflect.Method ;
import java.lang.reflect.InvocationHandler ;

import javax.rmi.CORBA.Tie ;

import com.sun.corba.se.spi.orb.ORB ;
import com.sun.corba.se.spi.orbutil.proxy.InvocationHandlerFactory ;


/** Provides access to RMI-IIOP stubs and ties.
 * Any style of stub and tie generation may be used.
 * This includes compiler generated stubs and runtime generated stubs
 * as well as compiled and reflective ties.  There is normally
 * only one instance of this interface per VM.  The instance
 * is obtained from the static method
 * com.sun.corba.se.spi.orb.ORB.getPresentationManager.
 * <p>
 * Note that
 * the getClassData and getDynamicMethodMarshaller methods
 * maintain caches to avoid redundant computation.
 */
public interface PresentationManager
{
    /** Creates StubFactory and Tie instances.
     */
    public interface StubFactoryFactory
    {
        /** Return the standard name of a stub (according to the RMI-IIOP specification
         * and rmic).  This is needed so that the name of a stub is known for
         * standalone clients of the app server.
         */
        String getStubName( String className ) ;

        /** Create a stub factory for stubs for the interface whose type is given by
         * className.  className may identify either an IDL interface or an RMI-IIOP
         * interface.
         * @param className The name of the remote interface as a Java class name.
         * @param isIDLStub True if className identifies an IDL stub, else false.
         * @param remoteCodeBase The CodeBase to use for loading Stub classes, if
         * necessary (may be null or unused).
         * @param expectedClass The expected stub type (may be null or unused).
         * @param classLoader The classLoader to use (may be null).
         */
        PresentationManager.StubFactory createStubFactory( String className,
            boolean isIDLStub, String remoteCodeBase, Class expectedClass,
            ClassLoader classLoader);

        /** Return a Tie for the given class.
         */
        Tie getTie( Class cls ) ;

        /** Return whether or not this StubFactoryFactory creates StubFactory
         * instances that create dynamic stubs and ties.  At the top level,
         * true indicates that rmic -iiop is not needed for generating stubs
         * or ties.
         */
        boolean createsDynamicStubs() ;
    }

    /** Creates the actual stub needed for RMI-IIOP remote
     * references.
     */
    public interface StubFactory
    {
        /** Create a new dynamic stub.  It has the type that was
         * used to create this factory.
         */
        org.omg.CORBA.Object makeStub() ;

        /** Return the repository ID information for all Stubs
         * created by this stub factory.
         */
        String[] getTypeIds() ;
    }

    public interface ClassData
    {
        /** Get the class used to create this ClassData instance
         */
        Class getMyClass() ;

        /** Get the IDLNameTranslator for the class used to create
         * this ClassData instance.
         */
        IDLNameTranslator getIDLNameTranslator() ;

        /** Return the array of repository IDs for all of the remote
         * interfaces implemented by this class.
         */
        String[] getTypeIds() ;

        /** Get the InvocationHandlerFactory that is used to create
         * an InvocationHandler for dynamic stubs of the type of the
         * ClassData.
         */
        InvocationHandlerFactory getInvocationHandlerFactory() ;

        /** Get the dictionary for this ClassData instance.
         * This is used to hold class-specific information for a Class
         * in the class data.  This avoids the need to create other
         * caches for accessing the information.
         */
        Map getDictionary() ;
    }

    /** Get the ClassData for a particular class.
     * This class may be an implementation class, in which
     * case the IDLNameTranslator handles all Remote interfaces implemented by
     * the class.  If the class implements more than one remote interface, and not
     * all of the remote interfaces are related by inheritance, then the type
     * IDs have the implementation class as element 0.
     */
    ClassData getClassData( Class cls ) ;

    /** Given a particular method, return a DynamicMethodMarshaller
     * for that method.  This is used for dynamic stubs and ties.
     */
    DynamicMethodMarshaller getDynamicMethodMarshaller( Method method ) ;

    /** Return the registered StubFactoryFactory.
     */
    StubFactoryFactory getStubFactoryFactory( boolean isDynamic ) ;

    /** Register the StubFactoryFactory.  Note that
     * a static StubFactoryFactory is always required for IDL.  The
     * dynamic stubFactoryFactory is optional.
     */
    void setStubFactoryFactory( boolean isDynamic, StubFactoryFactory sff ) ;

    /** Equivalent to getStubFactoryFactory( true ).getTie( null ).
     * Provided for compatibility with earlier versions of PresentationManager
     * as used in the app server.  The class argument is ignored in
     * the dynamic case, so this is safe.
     */
    Tie getTie() ;

    /** Returns the value of the com.sun.CORBA.ORBUseDynamicStub
     * property.
     */
    boolean useDynamicStubs() ;
}