RMI-IIOP CORBA Sample
---------------------

Brief Description :

This sample demonstrates on how to use CORBA within Java Web Start. It 
shows how a simple Java  program using CORBA can be packaged, downloaded 
and executed as a JNLP application by Java Web Start. RMI-IIOP utilizes 
the Java CORBA Object Request Broker (ORB) and IIOP, so you can write all 
of your code in Java, and use the rmic compiler to generate the code 
necessary for connecting your applications via the Internet InterORB 
Protocol (IIOP) to others written in any CORBA-compliant language. 
Please note that this sample does n't use any of the JNLP APIs. 

It uses RMI Compiler (rmic) with -iiop option to generate IIOP stubs and 
tie classes. This sample consists of a remote interface (HelloInterface), 
a remote object implementation (HelloImpl), an RMI server that creates an 
instance of remote object implementation (HelloServer) and a client 
application (HelloClient) that invokes the remote method - sayHello().  

A remote object is an instance of a class that implements a Remote interface.
Your remote interface will declare each of the methods that you would like to 
call from other machines. Implementation of the remote method - sayHello()
in this example just returns the string "Hello from Java Web Start" to the
caller. HelloServer is the class which has a main method that creates an 
instance of the remote object implementation, and binds that instance to a
name ("HelloService") in the Naming Service using JNDI API. Once a remote 
object is registered on the server, callers (HelloClient) can look up the 
object by name (using a naming service that is part of the ORB Daemon), obtain 
a remote object reference, and then remotely invoke methods on the object. 

ORBD and HelloServer should be started successfully before launching the 
client. Java Web Start will execute the HelloWorld Client application as 
specified in the .jnlp file. Client and Server will be passed the host and 
port number information of the orbd at the runtime. For the client, host and 
the port number information are specified in the .jnlp file.

Java Web Start is launched automatically by browser when the user clicks on
a link which is associated with a JNLP file.It then downloads and caches the
client application on the local client machine where browser is running.
This cached application when invoked next time is already downloaded and
runs as fast as a traditionally installed application.By default applications
are run in a protective environment (sandbox) with restricted access to
local disk and network resources. Java Web Start only transfers JAR files
from the Web server to the location determined by it on the client machine. 

To provide a simple and convenient packaging format of Applications, Java
Web Start includes a servlet in the developer's pack. The name of the servlet
is JnlpDownloadServlet and is packaged into the jnlp-servlet.jar file. This
servlet eases deployment of application on any J2EE-complaint application
server by packing a JNLP files and its associated resources in a Web Archive
(.war) file. 

For more details on Java Web Start product and JNLP API, Please check out
online docs at
http://java.sun.com/products/javawebstart/developers.html

For the latest documentation on RMI-IIOP, Please refer to
http://java.sun.com/j2se/1.4/docs/guide/rmi-iiop/index.html




Files :

src       - This directory has all the required source files :
            core directory has the code required for HelloClient
            and HelloServer java programs. stubs consists of remote
            interface, remote object implementation and the stuff
            generated by rmic compiler.

lib       - This directory contains the jar files generated after the build process.

class     - This directory contains all the  .class files generated
            by the build process. 

war       - This directory contains all the files required
            for deploying a web based application. Application
            related .jnlp files and .jar files are inside app. 
            helloworld.jnlp and HelloWorld.jar are the main 
            application resources. myKeystore is a keystore used 
            mainly for the purpose of signing jar files.

Building & Deployment of Application :


1) Build .class and .jar files by running
  
   gnumake

   in the directory where GNUmakefile file resides.

   The following environment variable must be set:

   # environment variable SDK_HOME should point to SDK directory
   # environment variable FILE_SEPARATOR variable for file separator (; on win32 and : on unix)


   If you are running on windows platform, it also assume you have MKS Toolkit installed and it is in your path environment variable.  (We need commands like cp, echo, mkdir, rm)  

   The generated classes will go to the classes directory, and the resulting jar files will be in the lib directory by default.  You can adjust the output directory to anything you want by changing the GNUmakefile.



2) Sign the HelloWorld.jar generated in lib directory using keytool and 
   jarsigner utility.

   To sign the jar file:

   keytool -genkey -keystore myKeystore -alias myself 
 
   jarsigner -keystore myKeystore HelloWorld.jar myself

   Read more details about Signing JAR Files process in 
   Java Web Start Developer's Guide.
     

3) ORB dameon and the Hello Server needs to be started first before
   executing the client application. If they are already running on a
   different machine, then you need not start them on the local machine.
   All you need to do is specify the correct hostname and the port number
   of the orbd in the helloworld.jnlp file:
  
   <property name="java.naming.provider.url" value="iiop://ord_host:port_number
"/>

   These values will be used by HelloClient upon started by Java Web Start. 
   
   ORB daemon can be started by running the following command :
   
   $JAVA_HOME/bin/orbd -ORBInitialPort <Port Number> &

   You can also start using 'gnumake runorbd' command in the current
   directory. Please note that you need to modify ORB_INITIAL_
   HOST and ORB_INITIAL_PORT values accordingly in the Makefile.
   
   NOTE: orbd tool is shipped only starting with J2SE 1.4 release. Use
   Transient Naming Service, tnameserv tool in releases prior to 1.4.
   ORBD includes both a Transient Naming Service and a Persistent Naming 
   Service. If you are using SDK 1.3.x, then it will be

   $JAVA_HOME/bin/tnameserv -ORBInitialPort <Port Number> &

4) HelloServer should be started next either at the command line
   
   $JAVA_HOME/bin/java -Djava.naming.factory.initial=com.sun.jndi.
   cosnaming.CNCtxFactory -Djava.naming.provider.url=iiop://${ORB_INITIAL_
   HOST}:${ORB_INITIAL_PORT}  -classpath <value> HelloServer &

 
   or using Makefile command 'gnumake runserver'.


5) For HelloClient, the war/app/helloworld.jnlp file consists of two
   property elements. Please modify them accordingly especially the
   naming provider url.

   You can also run 'gnumake runclient' to make sure
   everything is working fine in standalone java mode first. 
   
Note: Please make sure that the initial host names and  port numbers used
   for starting the orbd should match with the values specified in
   java.naming.provider.url property specified during the Client and Server
   startup. 

6) To ease the deployment of application to on any J2EE-complaint
   server all the resources required including .jnlp and jar files
   are packed into a Web Archive (.war) file.

	
   Please put the following files into the war directory:

   war/WEB-INF/lib/jnlp-servlet.jar (from building the JNLPDownloadServlet)
   war/WEB-INF/lib/<jar files for XML parser> (not needed if servlet container is running J2SE 1.4+; or if the servlet container already comes with a XML parser in it)
   war/app/HelloWorld.jar (generated in the lib directory)

   To build .war file, run below command inside the war directory


   jar -cvf ../rmi-iiop.war .


7) Copy rmi-iiop.war file to the your web server directory.
   For Tomcat server, copy rmi-iiop.war file to 
   $TOMCAT_HOME/webapps directory and restart the web server.
   HelloClient will be started automatically by Java Web Start when
   the link containing .jnlp file is clicked by the User.