readme.txt

JNLP sample, from Java.sun.com

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 has any .jar files required at the
            compilation time.

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.

build.xml - This file is used by Ant for building the application.
            It is kind of a Makefile for ant tool.

Makefile  - Makefile can also be used for building and running the
            applications.

Building & Deployment of Application :


1) Ant is a Java based build tool we used for building this application. 
   For more information, check out http://jakarta.apache.org/.

   Build .class and .jar files by running 
   
   ant main

   in the parent directory where build.xml file resides.

2) Applications by default run in a restricted environment where they 
   have limited access to local computing resources, such as storage 
   devices and the local network. Please note that you don't need to
   sign the jar file for this sample.However it may fail with a security
   error (access denied java.io.FilePermission orb.properties read )
   when the client application is deployed by JWS. This is a known
   CORBA implementation issue which is fixed in 1.4 (merlin) release.

   To workaround this error in earlier releases 1.3.x of JDK, Sign the 
   jar file using keytool and jarsigner utility. To do this run :

   keytool -genkey -keystore myKeystore -alias myself 
 
   jarsigner -keystore myKeystore war/app/HelloWorld.jar jws

   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 JAVA_HOME, 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 JDK 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. 
   
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.

   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.