/*
 * @(#)PresentationManager.java	1.10 05/11/17
 *
 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
 * SUN 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() ;
}