1/*
2 * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.  Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26package com.sun.corba.se.spi.presentation.rmi ;
27
28import java.util.Map ;
29
30import java.lang.reflect.Method ;
31import java.lang.reflect.InvocationHandler ;
32
33import javax.rmi.CORBA.Tie ;
34
35import com.sun.corba.se.spi.orb.ORB ;
36import com.sun.corba.se.spi.orbutil.proxy.InvocationHandlerFactory ;
37
38
39/** Provides access to RMI-IIOP stubs and ties.
40 * Any style of stub and tie generation may be used.
41 * This includes compiler generated stubs and runtime generated stubs
42 * as well as compiled and reflective ties.  There is normally
43 * only one instance of this interface per VM.  The instance
44 * is obtained from the static method
45 * com.sun.corba.se.spi.orb.ORB.getPresentationManager.
46 * <p>
47 * Note that
48 * the getClassData and getDynamicMethodMarshaller methods
49 * maintain caches to avoid redundant computation.
50 */
51public interface PresentationManager
52{
53    /** Creates StubFactory and Tie instances.
54     */
55    public interface StubFactoryFactory
56    {
57        /** Return the standard name of a stub (according to the RMI-IIOP specification
58         * and rmic).  This is needed so that the name of a stub is known for
59         * standalone clients of the app server.
60         */
61        String getStubName( String className ) ;
62
63        /** Create a stub factory for stubs for the interface whose type is given by
64         * className.  className may identify either an IDL interface or an RMI-IIOP
65         * interface.
66         * @param className The name of the remote interface as a Java class name.
67         * @param isIDLStub True if className identifies an IDL stub, else false.
68         * @param remoteCodeBase The CodeBase to use for loading Stub classes, if
69         * necessary (may be null or unused).
70         * @param expectedClass The expected stub type (may be null or unused).
71         * @param classLoader The classLoader to use (may be null).
72         */
73        PresentationManager.StubFactory createStubFactory( String className,
74            boolean isIDLStub, String remoteCodeBase, Class expectedClass,
75            ClassLoader classLoader);
76
77        /** Return a Tie for the given class.
78         */
79        Tie getTie( Class cls ) ;
80
81        /** Return whether or not this StubFactoryFactory creates StubFactory
82         * instances that create dynamic stubs and ties.  At the top level,
83         * true indicates that rmic -iiop is not needed for generating stubs
84         * or ties.
85         */
86        boolean createsDynamicStubs() ;
87    }
88
89    /** Creates the actual stub needed for RMI-IIOP remote
90     * references.
91     */
92    public interface StubFactory
93    {
94        /** Create a new dynamic stub.  It has the type that was
95         * used to create this factory.
96         */
97        org.omg.CORBA.Object makeStub() ;
98
99        /** Return the repository ID information for all Stubs
100         * created by this stub factory.
101         */
102        String[] getTypeIds() ;
103    }
104
105    public interface ClassData
106    {
107        /** Get the class used to create this ClassData instance
108         */
109        Class getMyClass() ;
110
111        /** Get the IDLNameTranslator for the class used to create
112         * this ClassData instance.
113         */
114        IDLNameTranslator getIDLNameTranslator() ;
115
116        /** Return the array of repository IDs for all of the remote
117         * interfaces implemented by this class.
118         */
119        String[] getTypeIds() ;
120
121        /** Get the InvocationHandlerFactory that is used to create
122         * an InvocationHandler for dynamic stubs of the type of the
123         * ClassData.
124         */
125        InvocationHandlerFactory getInvocationHandlerFactory() ;
126
127        /** Get the dictionary for this ClassData instance.
128         * This is used to hold class-specific information for a Class
129         * in the class data.  This avoids the need to create other
130         * caches for accessing the information.
131         */
132        Map getDictionary() ;
133    }
134
135    /** Get the ClassData for a particular class.
136     * This class may be an implementation class, in which
137     * case the IDLNameTranslator handles all Remote interfaces implemented by
138     * the class.  If the class implements more than one remote interface, and not
139     * all of the remote interfaces are related by inheritance, then the type
140     * IDs have the implementation class as element 0.
141     */
142    ClassData getClassData( Class cls ) ;
143
144    /** Given a particular method, return a DynamicMethodMarshaller
145     * for that method.  This is used for dynamic stubs and ties.
146     */
147    DynamicMethodMarshaller getDynamicMethodMarshaller( Method method ) ;
148
149    /** Return the registered StubFactoryFactory.
150     */
151    StubFactoryFactory getStubFactoryFactory( boolean isDynamic ) ;
152
153    /** Register the StubFactoryFactory.  Note that
154     * a static StubFactoryFactory is always required for IDL.  The
155     * dynamic stubFactoryFactory is optional.
156     */
157    void setStubFactoryFactory( boolean isDynamic, StubFactoryFactory sff ) ;
158
159    /** Equivalent to getStubFactoryFactory( true ).getTie( null ).
160     * Provided for compatibility with earlier versions of PresentationManager
161     * as used in the app server.  The class argument is ignored in
162     * the dynamic case, so this is safe.
163     */
164    Tie getTie() ;
165
166    /** Returns the value of the com.sun.CORBA.ORBUseDynamicStub
167     * property.
168     */
169    boolean useDynamicStubs() ;
170}
171