===============================================================================
JProxy Bundle
===============================================================================

The download includes:

2 Directories:

docs - JProxy API, help html-files
and
examples - source code of JProxy examples:

The "examples" directory contains 2 subdirectories:

samples - source code of Stateful Session EJB Test and Performance EJB Test. 
samples.jar is compiled EJB-archive of the examples that contains both Client 
and Server for the tests. Both tests can be executed from command line. 

online_samples - source code of JProxy online samples: JMS Clock, JMS Massager, 
EJB Mail


Files:

proxy.ear - J2EE Application. It contains:
  proxyservlet.war - servlet-based JProxy Server
  samples.jar - Stateful Session EJB Test Client/Server and 
    Performance EJB Test Client/Server

proxyclient.jar - client-side JProxy

j2api.jar - standard J2EE API. It includes API for EJB, JMS and JTA. 

*.sh, *.bat - UNIX and NT shell scripts for JProxy testing. 


The Deployment of JProxy Server proxy.ear

To deploy proxy.ear on JBoss 3.x.x, just copy the file in deployment directory 
jboss/server/default/deploy
For JBoss 2.x.x copy it to jboss/deploy 
And for Orion copy to orion/applications. 
To deploy on BEA WebLogic use WebLogic Console. 
Check server-side stack trace to be sure that proxy.ear is properly deployed.  


The Testing of JProxy Server 

After deployment of JProxy Server you can test it from Web Browser:
  http://localhost/proxyservlet

For testing JProxy from command line and for setting up tests for CORBA, RMI and SOAP please 
read instruction below. 

JProxy uses the servlet for HTTP/HTTPS communication. 
To "ping" the servlet type from Web Browser: 
  http://localhost/proxyservlet/servlet/proxyservlet?test 
If the servlet works then in Web Browser you can see server response:
>>> Success! JProxy Tunnel Servlet works!
>>> JProxy Tunnel URI: /proxyservlet/servlet/proxyservlet

You may also check JProxy from Web Browser from URL:
  http://localhost/proxyservlet/test.jsp
The test.jsp is locate in proxy.ear/proxyservlet.war. 
It executes Session EJB Test and outputs server time to web client. 

samples.jar may be used for testing of JProxy from command line. 
The file is also included in proxy.ear. 

The file contains following JProxy compiled and packaged tests that can be 
executed from command line.
The sample bean and client have been successfully tested on JBoss, 
WebLogic and Orion Application Servers. 
Try the tests first. 

1. Performance EJB Test
2. Statefull Session EJB Test. 
3. RMI Test
4. CORBA Test
5. SOAP JAX-RPC Test

There are in most of examples two cases of communication are included 
WITH and WITHOUT JProxy. 

For simplicity reason samples.jar contains both client and server. 
It includes source code and classes. 
You may simply unzip samples.jar. 
For convenience samples.jar is included in proxy.ear for deployment of 
EJB located in the tests. 

Before trying sample, deploy proxy.ear. 
Check server-side stack trace to be sure that proxy.ear is properly deployed.  

To deploy proxy.ear on JBoss 3.x.x, just copy the file in deployment directory 
jboss/server/default/deploy
For JBoss 2.x.x - copy it to jboss/deploy 
And for Orion copy to orion/applications. 
To deploy on BEA WebLogic use WebLogic Console. 


For first 3 tests (EJB, RMI and CORBA tests) the server implementation returns 
server local time to the client in format:
>>>Server Time: Tue Feb 12 10:08:21 EST 2002

Debug information will be printed during the test on both client and server. 
To disable output of debuging information you have to modify proxy.properties 
"com.jproxy.proxy.log.level". 
You my set it to "NONE" to completly disable output to stdout. 
See configuration.html for more information. 

To use "https" protocol you have to enable SSL on your server. 

If you get following exception:

java.io.FileNotFoundException: http://localhost/proxyservlet/servlet/proxyservlet
 at sun.net.www.protocol.http.HttpURLConnection.getInputStream(Unknown Source)

...then you did not specify server URL properly. Be sure that port number is correct. 

Below are test descriptions. 
URL in command line has following format:
protocol - "http" or "https". Default is "http". To use "https" protocol you 
have to enable SSL on your server. 
your_server_name - name of the host where your EJB Server is running. 
If it is local then just use "localhost". Default is "localhost".
port - port of your Web Server (Servlet Engine) where JProxy deployed. 
Default is 80.


===============================================================================
RMI and CORBA initialization for JProxy Testing
===============================================================================
You may skip the bullet if you do not have plans to execute JProxy tests for RMI and CORBA. 

Most of tests (except tests for RMI, CORBA and SOAP) are immediately available after deployment of proxy.ear. 
If you want to test just EJB or JMS (Message-Driven EJB) then go directly to: http://localhost/proxyservlet

For very first test please read instructions after deploying proxy.ear: http://localhost/proxyservlet 

For RMI, CORBA and SOAP extra deployment or initialization steps have to be performed. 
Because usually Application Server (EJB) container cannot automatically activate RMI and CORBA servants they have to be initialized separately. 

The easiest way to start RMI servant is from link: http://localhost/proxyservlet/samples_init.jsp
The same link attempts to launch CORBA servant. But for starting CORBA servant, CORBA NameService has to run. 
To start CORBA COS Naming Service for Sun CORBA:
on JDK 1.3.1 and earlier:
  tnameserv -ORBInitialPort 1050
on JDK 1.4.x
  orbd -ORBInitialPort 1050

On WebLogic you may see exception for CORBA initialization when you hit the link. 
But RMI Servant will be initialized and you can execute Performance Test for RMI.

If CORBA initialization from JSP fails, try to initialize from command line.
To start CORBA Server:
  orbd -ORBInitialPort 1050
  java -cp samples.jar;proxyclient.jar com.jproxy.samples.corba.test.TestServer -ORBInitialPort 1050  

Source code of RMI and CORBA initialization from JSP is located in: com.jproxy.samples.SampleInitializer.java

For the RMI tests you can use JNDI Service of container where proxy.ear is deployed.  
If you have AppServer (JBoss, WebLogic, etc.) you may use its JNDI Service for your RMI objects bindings, 
you do not need to launch rmiregistry at all. 
If your AppServer does not have JNDI Naming Service then execute: rmiregistry

If RMI initialization from JSP fails, try to initialize from command line.
  If your AppServer does not have JNDI Naming Service, execute: rmiregistry
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=localhost -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory com.jproxy.samples.rmi.test.TestServer



===============================================================================
Performance Test
===============================================================================
packages: com.jproxy.samples.*.test, com.jproxy.samples.interfaces

The test is available online on JProxy Site. 

The sample can be executed in your environment from Web Browser or from command prompt. 
Web Browser:
  http://localhost/proxyservlet/performance.html

The sample is tested for following Web Browsers: 
  1. MS IE 5,6 with Sun and MS JVM
    To switch between Sun and MS JVM use: Properties -> Advanced -> Java (Sun) -> "Use Java <applet>"
  2. Linux KDE 2.0 Konqueror with Sun JRE
  3. Opera with Sun JRE
  4. Netscape with Sun JRE

The test demonstrates communication with SOAP, CORBA, EJB, RMI
Both synchronous and asynchronous communication modes are supported for all cases (SOAP, CORBA, EJB, RMI)
The communication mode may be selected by pressing either "Test" or "TestCallback"
The test allows execution of multiple simultaneous client requests. 
The default number of threads is 1, max - 10
It also allows to specify number of loops (tests): default - 1, max - 100
Number of bytes per loop (test) can be also specified: default - 0, max - 100000

The fastest way setup the test for localhost for all APIs: EJB, CORBA, RMI, SOAP:
1. unzip proxydistr.zip and "cd" to its root directory

2. Deploy to your AppServer (for instance JBoss) propxy.ear located in proxydistr.zip

3. Start CORBA Server:
  orbd -ORBInitialPort 1050
  java -cp samples.jar;proxyclient.jar com.jproxy.samples.corba.test.TestServer -ORBInitialPort 1050  

4. start RMI Server:
  If your AppServer does not have JNDI Naming Service then execute: rmiregistry
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=localhost -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory com.jproxy.samples.rmi.test.TestServer

5. To execute SOAP JAX-RPC test deploy Apache Axis on your AppServer if no SOAP Container is present. 
Axis is easy to deploy on any AppServer because it is packaged in war-file. 

6. Start AppServer and execute the PerformanceTest:
  http://localhost/proxyservlet/performance.html


To execute samples type from command prompt: 

to start Performance Test from command line with GUI:
    java -cp samples.jar;proxyclient.jar;j2api.jar;jaxrpc.jar com.jproxy.samples.ejb.test.PerformanceApplet

to start Performance Test without GUI:
    java -cp samples.jar;proxyclient.jar \
        [-Djava.properties] com.jproxy.samples.ejb.test.PerformanceClient \
        [mode=EJB | RMI | CORBA | SOAP ] [loops=1] [bytes=0] [threads=1] [url=localhost]
where:
    nloops - number of loops. Default: 1
    nbytes - number of bytes send(received) to host in request. Default: 0 \
    threads - number of threads. Default: 1 \
    url - server URL. For instance: http://localhost:8080 Default: localhost
				
or with default parameters:
    java -cp samples.jar;proxyclient.jar;jaxrpc.jar;j2api.jar com.jproxy.samples.ejb.test.PerformanceClient

...or from shell script:

UNIX
  test_performance.sh -Djava.naming.provider.url=protocol://your_server_name:port

NT
  test_performance.bat -Djava.naming.provider.url=protocol://your_server_name:port


===============================================================================
Statefull Session EJB Test. 
===============================================================================
packages: com.jproxy.samples.ejb.test, com.jproxy.samples.interfaces

The EJB test WITH JProxy 
To execute the samples type from command prompt: 
  java -cp samples.jar;proxyclient.jar;j2api.jar -Djava.naming.provider.url=protocol://your_server_name:port -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory com.jproxy.samples.ejb.test.SessionClient

...or from the shell script:

UNIX
  test.sh -Djava.naming.provider.url=protocol://your_server_name:port

NT
  test.bat -Djava.naming.provider.url=protocol://your_server_name:port

You may also perform the test WITOUT JProxy on JBoss:
NT
  set CP=\jboss\client
  java -cp samples.jar;proxyclient.jar;j2api.jar;%CP%/jboss-j2ee.jar;%CP%/jboss-client.jar;%CP%/jnp-client.jar;%CP%/jbosssx-client.jar;%CP%/jboss-common-client.jar;%CP%/log4j.jar -Djava.naming.provider.url= your_server_name -Djava.naming.factory.initial=org.jnp.interfaces.NamingContextFactory com.jproxy.samples.ejb.test.SessionClient
Notice how many libraries are necessary to perform the test if you do not use 
JProxy:

...or from the shell script:

UNIX
Open test.sh. Read instructions. They explain what libraries must be included. 
  test.sh -Djava.naming.provider.url=your_server_name

NT
Open test.bat. Read instructions. They explain what libraries must be included. 
  test.bat -Djava.naming.provider.url=your_server_name


===============================================================================
RMI Test
===============================================================================
packages: com.jproxy.samples.rmi.test, com.jproxy.samples.interfaces

The rmic has been used to produce stub and skeleton: 
  rmic com.jproxy.samples.rmi.test.TestImpl
  
Here are command lines to start server and client. First you have to start 
RMI TestServer object:

To use different Application Servers use appropriate libraries for Naming Service. 
For instance to utilize JBoss Naming Service to bind the object include JBoss clients JNDI library to start server: jnp-client.jar.

To start RMI Naming Service (if JBoss is not running):
  rmiregistry

To start RMI Server over JProxy:
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=localhost -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory com.jproxy.samples.rmi.test.TestServer
Notice "-D" parameter. The parameter assumes that TestServer starts from 
directory where samples.jar is. 

...or if you want to start the server WITHOUT JProxy then:
  java -cp samples.jar; -Djava.naming.provider.url=rmi://your_server_name:1099 -Djava.naming.factory.initial=com.sun.jndi.rmi.registry.RegistryContextFactory -Djava.rmi.server.codebase=file://samples.jar com.jproxy.samples.rmi.test.TestServer

- To perform test for RMI over JProxy
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=localhost -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory com.jproxy.samples.rmi.test.TestClient

To perform the test for RMI WITHOUT JProxy:
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=rmi://your_server_name -Djava.naming.factory.initial=com.sun.jndi.rmi.registry.RegistryContextFactory com.jproxy.samples.rmi.test.TestClient


...or from shell script:

UNIX
To start Server:
  test_rmi_server.sh -Djava.naming.provider.url=protocol://your_server_name:port

To execute client:
  test_rmi_client.sh -Djava.naming.provider.url=protocol://your_server_name:port

NT
To start Server:
  test_rmi_server.bat -Djava.naming.provider.url=protocol://your_server_name:port

To execute client:
  test_rmi_client.bat -Djava.naming.provider.url=protocol://your_server_name:port


===============================================================================
CORBA Test
===============================================================================
packages: com.jproxy.samples.corba.test, com.jproxy.samples.interfaces

The samples show how to communicate with CORBA over JProxy.
The samples have been tested for Sun CORBA included in any JDK since 1.2 and 
also freely available separately for older JDKs.

Sun CORBA is used for the sample.
If JacORB is present in AppServer where JProxy Server deployed the sample may not work. 
JacORB libraries  includes its own "org.omg" package that causes the problem. 
The sample can be adjusted for any ORB by recompiling test.idl and changing JNDI properties. 

In the test JProxy was deployed in JBoss 3.2.x environment. 

It uses JNDI CORBA Naming SPI for remote object navigation. 
Notice that no one CORBA API class is used. 
It means that CORBA may not be present at all on client-side!

Here is a reference for COS Naming Service Provider for the Java Naming and 
Directory Interface TM (JNDI): 
http://www.iona.com/devcenter/appserv/apis/jdk1.3/docs/guide/jndi/jndi-cos.html

Here is a tutorial explaining how to write a CORBA server and client: 
http://java.sun.com/docs/books/tutorial/idl/hello/index.html

The CORBA saples already include compiled Test.idl. 
Test.idl is located in samples.jar/com/jproxy/samples/corba/test
If you want to compile Test.idl for CORBA samples then execute:
  idlj -fall Test.idl

Be sure that CORBA Server is running.

Below are instructions how to compile and execute CORBA Sample under Sun CORBA implementation:

If you want to compile Test.idl for Sun CORBA samples then execute:
  idlj -fall Test.idl

To start CORBA COS Naming Service for Sun CORBA:
on JDK 1.3.1 and earlier:
  tnameserv -ORBInitialPort 1050
on JDK 1.4.x
  orbd -ORBInitialPort 1050

If you cannot execute on default port 900 then you have to specify port greater then 1024 with option -ORBInitialPort on both client and server. 

To start CORBA Test Server under Sun CORBA:
  java -cp samples.jar;proxyclient.jar com.jproxy.samples.corba.test.TestServer -ORBInitialPort 1050

Below are instructions how to execute command-line CORBA Sample under Sun CORBA implementation. 

Here is a tutorial explaining how to write a CORBA server and client utilizing Sun CORBA: 
http://java.sun.com/docs/books/tutorial/idl/hello/index.html

To perform command-line test for CORBA (JNDI with Sun CORBA SPI) over JProxy:
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=http://localhost -Djava.naming.factory.initial=com.jproxy.proxy.NamingContextFactory -Dcom.jproxy.proxy.provider.url=iiop://localhost:1050 -Dcom.jproxy.proxy.initial=com.sun.jndi.cosnaming.CNCtxFactory com.jproxy.samples.corba.test.TestClient

To perform command-line test for CORBA (JNDI with Sun CORBA SPI, WITHOUT JProxy):
  java -cp samples.jar;proxyclient.jar -Djava.naming.provider.url=iiop://localhost:1050 -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory com.jproxy.samples.corba.test.TestClient

To perform command-line test for pure Sun CORBA (WITHOUT JProxy):
  java -cp samples.jar;proxyclient.jar com.jproxy.samples.corba.test.TestCORBAClient -ORBInitialPort 1050 -ORBInitialHost localhost

The Client can be executed from command line or in web Browser as Applet. 

For utilizing JacORB CORBA following files have to be present:
$JBOSS_HOME/server/default/lib/jacorb.jar
$JBOSS_HOME/server/default/lib/jboss-iiop.jar
$JBOSS_HOME/server/default/deploy/iiop-service.xml
$JBOSS_HOME/server/default/conf/jacorb.properties
"default" profile does not have the file. You can find them under "all" profile. 


===============================================================================
SOAP JAX-RPC Test
===============================================================================
packages: com.jproxy.samples.soap.test, com.jproxy.samples.interfaces

The sample can be executed from Web Browser: 
  http://localhost/proxyservlet/performance.html
But before execution be sure that Apache Axis ServiceFactory (org.apache.axis.client.ServiceFactory) is set.
You may set the default factory in java.home/lib/jaxrpc.properties or 
in some jar-file under META-INF/services/javax.xml.rpc.ServiceFactory
IONA Artix has its ServiceFactory (com.iona.jbus.jaxrpc.JBusServiceFactory) set in it_bus.jar. 
Check JAXRPC spec or source of javax.xml.rpc.FactoryFinder.java (method find(...)) for details.

Below is jaxrpc.properties with Apache Axis ServiceFactory:
  javax.xml.rpc.ServiceFactory=org.apache.axis.client.ServiceFactory

And here is jaxrpc.properties with IONA Artix ServiceFactory:
  javax.xml.rpc.ServiceFactory=com.iona.jbus.jaxrpc.JBusServiceFactory

Be sure that you found correct "java.home". "java.home" usually is $JAVA_HOME/jre if JAVA_HOME is pointed to JDK installation. 
Or "java.home" is $JAVA_HOME if JAVA_HOME is pointed to JRE installation. 
For instance, if JAVA_HOME is set to home of JDK 1.4.2 then 
"java.home" is: j2sdk1.4.2/jre. 

JProxy Distribution includes compiled SOAP Performance Sample that has been tested on Apache Axis and IONA Artix. 

To execute it you must have Axis installed and proxy.ear from distribution deployed. 
The client is an applet. To test SOAP chose "SOAP" test case in the applet. 

Applet URL for localhost with HTTP port 80: http://localhost/proxyservlet/performance.html

In JProxy we compile all samples with Ant as part of main build-script for distribution. 
Below are the steps to compile Axis SOAPPerformance sample on NT "by hand":

1. System variables for Axis
    set AXIS_HOME=%JBOSS_HOME%\server\default\deploy\axis.war
    set AXIS_LIB=%AXIS_HOME%\WEB-INF\lib
    set AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery.jar;%AXIS_LIB%\commons-logging.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%AXIS_LIB%\xml-apis.jar;%AXIS_LIB%\xercesImpl.jar;%AXIS_LIB%\wsdl4j.jar
    set AXISCLASSPATH=%AXISCLASSPATH%;%JBOSS_HOME%\lib\xercesImpl.jar;%JBOSS_HOME%\lib\xml-apis.jar

2. Creating WSDL from Java Interface
    java -cp %AXISCLASSPATH%;samples.jar; org.apache.axis.wsdl.Java2WSDL -o test.wsdl  -l"http://localhost/axis/services/JProxyTest" -n  "urn:JProxy" -p"com.jproxy.samples.interfaces" "urn:JProxy"  com.jproxy.samples.interfaces.ITest

it produces file: 
    test.wsdl

3. Generating bindings from WSDL
    java -cp %AXISCLASSPATH%;samples.jar; org.apache.axis.wsdl.WSDL2Java -o . -d Application -a -s -S true  -Nurn:JProxy com.jproxy.samples.soap.test test.wsdl

the command produces files: 

    deploy.wsdd
    undeploy.wsdd
    com/jproxy/samples/soap/ITest.java
    com/jproxy/samples/soap/ITestCallback.java
    com/jproxy/samples/soap/ITestService.java
    com/jproxy/samples/soap/ITestServiceLocator.java
    com/jproxy/samples/soap/JProxyTestSoapBindingImpl.java
    com/jproxy/samples/soap/JProxyTestSoapBindingSkeleton.java
    com/jproxy/samples/soap/JProxyTestSoapBindingStub.java

4. Modifying generated source files
The changes are neccessary only for callback demonstration and for reusing 
interfaces that are common for ALL samples: 
    com.jproxy.samples.interface.ITestCallback and 
    com.jproxy.samples.interface.ITest

To find all changes search under com/jproxy/samples/soap for comment with pattern "#JProxy". 

For SOAP callback test replace every where in generated *.java files 
"com.jproxy.samples.soap.test.ITestCallback" to "com.jproxy.samples.interfaces.ITestCallback"

5. Compiling the sample
     javac -classpath %AXISCLASSPATH%;samples.jar com/jproxy/samples/soap/*.java


6. testing:
Deploying service on Axis server weth port 80:
java -cp %AXISCLASSPATH%; org.apache.axis.client.AdminClient -p 80 deploy.wsdd

Command line testing
to start Performance Test from command line with GUI:
    java -cp %AXISCLASSPATH%;samples.jar;proxyclient.jar;j2api.jar;jaxrpc.jar com.jproxy.samples.ejb.test.PerformanceApplet

to start Performance Test without GUI:
    java -cp %AXISCLASSPATH%;samples.jar;proxyclient.jar;jaxrpc.jar;j2api.jar com.jproxy.samples.ejb.test.PerformanceClient


===============================================================================
JMS Test
===============================================================================
The JMS test can be executed from Performance Test if "JMS" mode is selected. 
Because the test is based on Enterprise Message Driven Bean (MDB) it needs queue been present in your AppServer. 
JBoss automatically creates temporary queue with name of MDB. But for WebLogic queue has to be 
explicitly specified: queue/TestMessageDrivenBean
To enable MDB please uncomment <message-driven> section in deployment descriptor samples.jar/META-INF/ejb-jar.xml


===============================================================================
Notes:
===============================================================================
1. 
JProxy Properties located: 
  proxyclient.jar/com/jproxy/proxy/proxy.properties
  proxyservlet.jar/WEB-INF/classes/com/jproxy/proxy/proxy.properties
The property also can be set outside of the files in $JAVA_HOME/lib/proxy.properties

Be sure that you found correct "java.home". "java.home" usually is $JAVA_HOME/jre if JAVA_HOME is pointed to JDK installation. 
Or "java.home" is $JAVA_HOME if JAVA_HOME is pointed to JRE installation. 
For instance, if JAVA_HOME is set to home of JDK 1.4.2 then 
"java.home" is: j2sdk1.4.2/jre. 

2.
During execution of PerformanceTest on IONA Artix you may see stack trace:
  [STDOUT] [INFO] java.lang.UnsupportedOperationException: getTypeMappingRegistry not yet supported
The exception is thrown because JProxy attempts to set its Serializer/Deserializer for callback support. 
Artix does not have yet implemented functionnality of JAX-RPC custom type mapping. 
Here is an exact JProxy Server code fragment where it attempts to set custom type mapping:
    TypeMappingRegistry registry = service.getTypeMappingRegistry();
    TypeMapping mapping = registry.getTypeMapping("http://schemas.xmlsoap.org/soap/encoding/");
    mapping.register(
        Class.forName("com.jproxy.samples.interfaces.ITestCallback"),
        new QName("urn:JProxy", "ITestCallback"),
        new com.jproxy.proxy.providers.AxisObjectSerializerFactory(),
        new com.jproxy.proxy.providers.AxisObjectDeserializerFactory());
    registry.register("http://schemas.xmlsoap.org/soap/encoding/", mapping);

In order to support callbacks the code above has to be executable by Artix. 


[JProxy]

