I386LINUX/util/I386LINUX/doc/mico/examples/interop/jboss/README

   1 SUMMARY
   2
   3    1. MICO/JBoss Interoperability
   4    2. Prerequisites
   5    3. Running the examples
   6    4. Why different versions of the examples for JDK 1.3.x and for JDK 1.4.x?
   7
   8
   9 1. MICO/JBoss Interoperability
  10    ---------------------------
  11
  12 The subdirectories of this directory contain examples of MICO/JBoss
  13 interoperability. Two versions of the same set of three examples are
  14 provided. You should chose one of these versions depending on whether
  15 you run the JBoss server with JDK 1.3.x or with JDK 1.4.x:
  16
  17   - the subdirectory jdk1.3.x contain three examples that demonstrate
  18     the interoperability between MICO and a JBoss server on JDK 1.3.x;
  19
  20   - the subdirectory jdk1.4.x contain three examples that demonstrate
  21     the interoperability between MICO and a JBoss server on JDK 1.4.x.
  22
  23 These examples are in the subdirectories
  24
  25     jdk1.3.x/converter-ejb              jdk1.4.x/converter-ejb
  26     jdk1.3.x/cart-ejb                   jdk1.4.x/cart-ejb
  27     jdk1.3.x/corba-friendly-ejb         jdk1.4.x/corba-friendly-ejb
  28
  29 Each such subdirectory contains an example of EJB, a C++ client that
  30 accesses that EJB, and a Makefile that generates both the client and
  31 an EJB jar file ready to be deployed into a JBoss server running on
  32 the corresponding JDK.
  33
  34 The examples are:
  35
  36   - converter-ejb: Sun's well-known "converter" example, a very simple
  37         stateless session bean. This is the same example in directory
  38         interop/ejb. No value types are passed between the client
  39         and the server in this example.
  40
  41   - cart-ejb: this stateful session bean is a version of Sun's well-known
  42         "cart" example. Value types are passed between the client and the
  43          server. Moreover, a Java exception thrown by the session bean is
  44          caught by the C++ client.
  45
  46   - corba-friendly-ejb: this stateless session bean exemplifies the use
  47          of IDL entities as "data objects" passed between the client and
  48          the server. IDL-defined "data objects" minimize the use of value
  49          types.
  50
  51
  52 2. Prerequisites
  53    -------------
  54
  55  - Sun's JDK (a.k.a. J2SE) 1.3.x or 1.4.x, available from java.sun.com
  56
  57  - JBoss 3.2.0 or higher, available from the JBoss Files page at SourceForge:
  58    http://sourceforge.net/project/showfiles.php?group_id=22866
  59
  60  - Either MICO snapshot with date 2003/04/04 (or later) or the upcoming
  61    MICO 2.3.10
  62
  63
  64 3. Running the examples
  65    --------------------
  66
  67 Depending on your JDK version, edit one of the setenv.sh files (either
  68 jdk1.3.x/setenv.sh or jdk1.4.x/setenv.sh) and use it to prepare your
  69 environment by typing 'source setenv.sh' in the corresponding subdirectory.
  70 Compile all the necessary binaries by typing 'make' in each example
  71 subdirectory (converter-ejb, cart-ejb, and corba-friendly-ejb). This will
  72 generate a MICO client and an EJB jar file in each example subdirectory.
  73 Before you can run each client, you need to deploy the EJB jar file in a
  74 JBoss server. To do this, copy the EJB jar file to the "deploy" directory
  75 of the JBoss server. (If you are not familiar with JBoss, read the "NOTE ON
  76 JBOSS" below.) Once the EJB jar file is deployed (and the JBoss server
  77 running), simply type 'run-client' to run the MICO client.
  78
  79 The output of the converter-ejb client should be:
  80
  81     Looking up examples/MyConverter... Done.
  82     Result: 1100
  83
  84 The output of the cart-ejb client should be:
  85
  86     Looking up examples/CartExample... Done.
  87     Cart contents:
  88             The Martian Chronicles
  89             2001 A Space Odyssey
  90             The Left Hand of Darkness
  91     Caught expected exception examples::BookEx:
  92             Alice in Wonderland not in cart.
  93
  94 The output of the corba-friendly-ejb client should be:
  95
  96     Looking up examples/MyCorbaFriendlySession... Done.
  97     Before echo call:               7       Hello, world!
  98     After echo call:                8       Hello, world!!
  99     Before echoSequence call:       8       Hello, world!!
 100                                     8       Hello, world!!
 101                                     8       Hello, world!!
 102                                     8       Hello, world!!
 103     After echoSequence call:        12      Hello, world!!!!!!
 104                                     12      Hello, world!!!!!!
 105                                     12      Hello, world!!!!!!
 106                                     12      Hello, world!!!!!!
 107
 108 NOTE ON JBOSS:
 109
 110 JBoss comes with three server configurations: "min", "default", and "all".
 111 Each of them corresponds to a subdirectory of $JBOSS_HOME/server, e.g.:
 112 $JBOSS_HOME/server/default.
 113
 114 The "default" JBoss configuration does not include IIOP support. To run
 115 these examples, you should use the "all" configuration:
 116
 117   - To start the server, go to $JBOSS_HOME/bin and say
 118
 119         ./run.sh -c all
 120
 121     (rather than just `./run.sh', which would start a server with the
 122      "default" config)
 123
 124   - To deploy an EJB, copy the EJB jar file to $JBOSS_HOME/server/all/deploy
 125     (rather than to $JBOSS_HOME/server/default/deploy).
 126
 127 Alternatively, you can use a customized "iiop" configuration, with ejb/IIOP
 128 and little else. (This saves machine resources and makes the server startup
 129 time much shorter.) Creating a customized "iiop" configuration is very easy:
 130
 131   - Recursively copy  $JBOSS_HOME/server/all to $JBOSS_HOME/server/iiop:
 132
 133         cd $JBOSS_HOME/server
 134         cp -a all iiop
 135
 136   - Remove all subdirectories and files in $JBOSS_HOME/server/iiop,
 137     EXCEPT the subdirectories jmx-rmi-adaptor.sar and jbossweb-jetty.sar
 138     and the following files:
 139
 140         hsqldb-ds.xml
 141         iiop-service.xml
 142         jboss-jca.sar
 143         jboss-local-jdbc.rar
 144         jboss-xa-jdbc.rar
 145         transaction-service.xml
 146
 147   - Use the "iiop" configuration instead of the "all" configuration:
 148
 149         * Start the server by saying `./run.sh -c iiop' at the $JBOSS/bin
 150           directory.
 151
 152         * Deploy an EJB by copying the EJB jar file to the directory
 153           $JBOSS_HOME/server/iiop/deploy.
 154
 155
 156 4. Why different versions of the examples for JDK 1.3.x and for JDK 1.4.x?
 157    -----------------------------------------------------------------------
 158
 159 Due to a change in class java.lang.Throwable, from which all Java
 160 exceptions inherit. In order to support exception chaining, two new
 161 fields were added to class Throwable in JDK 1.4: a cause field (which
 162 is itself a Throwable) and a stackTrace field (which is an array of
 163 StackTraceElements). Recall that a Java exception is mapped to an IDL
 164 exception that contains the Java exception in a value field. The
 165 addition of new fields to Throwable (and, by inheritance, to each and
 166 every Java exception) means that a different stub must be used to
 167 unmarshal the corresponding IDL exception. Therefore different C++
 168 stubs are needed depending on whether the JBoss server runs on JDK 1.3.x
 169 or on JDK 1.4.x.
 170
 171 Besides adding new fields to class Throwable, JDK 1.4 also added a
 172 writeObject method to this class. According to the Java to IDL mapping
 173 specification, a Java serializable object with a writeObject method
 174 is mapped to a *custom* value type. Therefore a java.lang.Throwable
 175 should now be mapped to an IDL exception that has a custom value type
 176 in its value field. Moreover, CORBA says that "non-custom value
 177 types may not (transitively) inherit from custom value types". As a
 178 consequence, *any* Java exception should now (from JDK 1.4 on) be
 179 mapped to an IDL exception that has a *custom* value field.
 180
 181 The rmic utility in JDK 1.4.x, however, does not map Java exceptions
 182 in a CORBA-compliant way. The command 'rmic -idl' correctly maps
 183 java.lang.Throwable into an IDL exception that has a custom value field
 184 containing the java.lang.Throwable. But it fails to do this in the case
 185 of a Java exception class that does not explicitly define a writeObject
 186 method. As an example: it maps java.lang.Exception into an IDL exception
 187 that contains a field whose type is a non-custom value type that
 188 (incorrectly) inherits from the custom value type Throwable. In other
 189 words, 'rmic -idl' maps Java exception classes into *invalid* IDL
 190 definitions. The current version of the MICO IDL compiler (both MICO
 191 2.3.9 and mico-snapshot-030404) fails to detect that such IDL definitions
 192 are invalid and translates them into C++ code that does not compile.
 193
 194 A solution to this problem would be to add the missing `custom' modifier
 195 to the exception value type definitions generated by rmic. There is a
 196 simpler solution, though. Even though class java.lang.Throwable has a
 197 writeObject method, it does not really need custom marshaling. Its
 198 writeObject method merely ensures that that the stackTrace field of
 199 the java.lang.Throwable instance is properly set before this instance
 200 gets marshaled in the standard way. So we can safely discard the
 201 rmic-generated custom value type for Throwable and replace it by a
 202 non-custom value type. This is the approach we took in the jdk1.4.x
 203 examples. It spares users from the trouble of (1) adding the missing
 204 'custom' modifier to several value type definitions generated by rmic
 205 and (2) writing custom marshaling code for each such value type.
 206 The Makefiles for the jdk1.4.x examples discard the Throwable.idl
 207 file generated by 'rmic -idl' and replace it by a file copied from
 208 the subdirectory jdk1.4-Throwable.
 209
 210
 211 That's it!
 212
 213
 214  -- Francisco Reverbel (reverbel@ime.usp.br)