JDeveloper is a full-featured, integrated development environment for creating multi-tier Java applications. It enables you to develop, debug, and deploy Java client applications, dynamic HTML applications, Web and application server components and database stored procedures based on industry-standard models. JDeveloper can also be used to develop and debug Java portlets for Oracle9iAS Portal.
This document explains how you can use JDeveloper3.2 to develop, debug and deploy your Java portlets for Oracle9iAS Portal. This document covers:
JDeveloper comes with extensive online documentation that will help you get started. The section "Starting a New Programming Project" under the Help Menu covers most of these details.
As part of this exercise, we provide a simple set of steps for you to follow.
Create a new Workspace From the File menu, click New Workspace. Next, choose Rename from the File menu and rename this as MyPortal. This creates a MyPortal.jws entry in your Jdeveloper Workspace window.
Add a new Project From the File menu, click New Project. This option takes you through a few screens before creating a new project. Follow the online help for further details. We provide a few screenshots to provide a quick illustration.
Add a File to the Project. In the Workspace tab window, click on the + icon, to add a file to the project. You can now add an existing PDK-Java sample java file to the project. Later you could add new empty files and code new Java files in JDeveloper itself. For now, add the HelloWorldRenderer.java file from where you have installed JPDK under jpdk\src\oracle\portal\sample\portlet\helloworld. Save the changes. Follow the online help for further details. We provide a screenshot to provide a quick illustration.
Your first Java portlet project is now setup.
To setup JDeveloper for PDK-Java, you need to add the JPDK library to the project. The section "Including Libraries in a Project" under the Help Menu covers most of these details.
As part of this exercise, we provide a simple set of steps for you to follow.
Create a new Library for PDK-Java. Right click on the MyPortalJavaProject1 Project and choose Properties. From the Libraries option, click New to create a new JPDK Library. For the CLASSPATH, provide the complete path for your provider.jar file as well as the samples.jar file. For the source path, point to \jpdk\lib.
Add the JPDK Library to the project. You can now add the JPDK Library to your project. You can now always add this JPDK library to other projects you create by selecting it from the list of Available Java Libraries.
You can deploy your Web provider on the local Oracle HTTP Server by following the PDK-Java instructions for this purpose.
Note: The PDK-Java sample HelloWorld portlet was deployed to your server as part of the JDK-Java installation process. Therefore, you don't need to do anything else for this section.
However, when you build a new portlet, remember to follow the required steps to deploy them to the Oracle HTTP Server.
Add a new CLASSPATH entry for your portlet. To allow the Provider Adapter to locate the class file, you must place the class file in the Oracle HTTP Server classpath. To do this, you must first Zip or Jar your class file and point the wrapper.classpath to this path. The article How to build a Java portlet provides details on doing this.
Create a provider.xml. The article How to build a Java portlet provides details on doing this.
Update zone.properties. You need to add an entry for the Servlet Alias that can be used to access the servlet. Also make an entry for the Servlet's initArgs that points the Adapter to the directory where the provider.xml for the new portlet resides. The article How to build a Java portlet provides details on doing this.
You can test that your portlet has been deployed to your local server by accessing the URL with the newly added alias. For example, type in the URL:
http://host.domain:port/servlet/<ServletAliasName>
In this exercise, we simply use the sample provider that comes with PDK-Java. To check that your provider has been successfully deployed on the local server, use your browser to access http://host.domain:port/servlet/sample and check that you get the message "Congratulations! You have successfully reached your Provider's Test Page."
You can register your Web Provider with a local or even a remote Oracle Portal installation like the Portal Studio. Portal Studio is a hosted service where you can test your Java portlets by simply registering your Web provider and providing the URL of your local server where you deployed the portlets. To use Portal Studio you need to provide a URL that is accessible outside of any firewall. This way, you don't need a local Oracle Portal installation to test your Java portlets.
Login to the Oracle Portal environment you choose to use and then register your provider. Note: You can skip this step if you have already registered the JPDK sample provider with this Oracle Portal instance.
Under the Administer tab, click on Add a Portlet Provider within the portlet called Provider.
Name: SampleWebProvider
Display Name: Sample Web Provider
Timeout: 100
Timeout Message: Application Timed Out
Implementation Style: Web
Provider Login Frequency: Once per User Session
Register on Remote Nodes: No
URL: http://myserver.mydomain.com:port/servlets/sample (replace this with your URL). Note: In case you've built a new portlet and provider, give the URL for the alias that you created in the zone.properties file. e.g. http://myserver.mydomain.com:port/servlet/myfirst
Check the following radio button: The user has the same identity in the HTTP providers application as in the Single Sign-On identity.
Proxy: No (As long as no proxy is required to contact the Provider Adapter).
Click OK.
Add Portlet to a Page
You have now successfully registered the sample Web provider with the HelloWorld portlet and run the portlet from the Oracle Portal environment.
The JDeveloper online help section on "Remote Debugging Servlets" under the Help Menu covers most of the details on setting up Remote Debugging. The section below covers the setup requirements, but feel free to use the online documentation as reference.
JDeveloper allows you to use one of two protocols for remote debugging - the Oracle Java Virtual Machine (OJVM) debugging protocol, or the Sun Java Platform Debugging Architecture (JPDA). Before you start your remote debugging session, you must choose which method to use. If you use the OJVM protocol, your debugging session will run more quickly and you will have some additional features to assist you. You can only use OJVM on a Windows NT system. If your server is running UNIX or another operating system, you must use the "classic" JVM.
Configure the Oracle HTTP
Server
Note: This section will update three Oracle HTTP Server configuration files. Please backup these files prior to making changes. The jserv.properties is located at: %ORACLE_HOME%\Apache\Jserv\conf on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX. The zone.properties is located at %ORACLE_HOME%\Apache\Jserv\servlets on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX. The jserv.conf is located at: %ORACLE_HOME%\Apache\Jserv\conf on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX.
The following options must be changed on the host running the Apache/Jserv server. These instructions assume the server is running Windows NT.
Stop the HTTP Server before you make these configuration changes.
Open the jserv.properties file and change the option that controls which Java Virtual Machine is used and how it is loaded.
For
the Java Virtual Machine interpreter parameter wrapper.bin, comment
out any existing entries by putting a # at the beginning of the line. For example:
#wrapper.bin=C:\java1.1.8\bin\java.exe
Add a new entry with the full path of the java.exe that you want to use. For example, to use the JDeveloper 1.3 OJVM enter:
wrapper.bin=C:\ProgramFiles\Oracle_Home\JDeveloper3.2\java1.2\bin\java.exe
The next option controls the parameters passed to Java interpreter by the wrapper.bin.parameters. The value you put for this parameter depends on which Debugging Protocol you will choose in the Remote Debugging Dialog in JDeveloper when you start debugging.
If you want to use the JDeveloper 3.2 OJVM, enter:
wrapper.bin.parameters=-ferrari -XXdebugondemandquietport4000
If you want to use Java Platform DebuggingArchitecture,enter:
wrapper.bin.parameters=-classic-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=4000 -Xdebug -Xnoagent -Djava.compiler=NONE
Note: The 4000 parameter defines the port number which the JDeveloper debugger will use to
communicate with the server. You can specify a different port number, but it
must match the port which you will enter in the Remote Debugging Dialog in
JDeveloper when you start debugging.
For the PATH environment value passed to the JVM
parameter wrapper.path, enter the location of jdwp.dll, which is part of the Java Platform Debugging Architecture.
This parameter is only necessary if you will choose the Java Platform Debugging Architecture debugging protocol:
wrapper.path=C:\jpda\bin
For the CLASSPATH environment value passed to the JVM parameter wrapper.classpath:
Add the location of servlet.jar from JDeveloper 3.2:
wrapper.classpath=C:\Program Files\Oracle_Home\JDeveloper3.2\lib\servlet.jar
Add the locations of jdeveloper.zip and ojsp.jar from JDeveloper:
wrapper.classpath=C:\Program Files\Oracle_Home\JDeveloper 3.2\lib\jdeveloper.zip
wrapper.classpath=C:\Program Files\Oracle_Home\JDeveloper 3.2\lib\ojsp.jar
Keep the location of ApacheJServ.jar.
If it is not already there, add it:
wrapper.classpath=C:\Program Files\Oracle_Home\Apache\JServ\ApacheJServ.jar
Note: Do not comment out the location of
jsdk.jar as indicated by the Remote Debugging help of
JDeveloper. You need the jsdk.jar to run your portlets. Keep
the location of the jsdk.jar file or add it if it does not exist:
wrapper.classpath=C:\Program Files\Oracle_Home\\Apache\Jsdk\lib\jsdk.jar
Save and close the jserv.properties file.
Open the zone.properties file. This document uses the root zone which has a virtual path of "/servlets". For manageability, you may choose to use a different zone.
In the Servlet Init Parameters section, add the following lines:
servlet.oracle.jsp.JspServlet.initArgs=emit_debuginfo=true
servlet.oracle.jsp.JspServlet.initArgs=jspcompiler=oracle.jdeveloper.jsp.JspOjcCompiler
servlet.oracle.jsp.JspServlet.initArgs=classpath=C:\Program Files\Oracle\JDeveloper 3.2\java1.3\jre\lib\frt.jar
Save and close the zone.properties file.
Open the jserv.conf file.
For the ApJServAction
parameter, comment out any existing ApJServAction .jsp entries by putting a # at the beginning of the line:
#ApJServAction .jsp /servlets/org.gjt.jsp.JSPServlet
Add a new ApJServAction .jsp entry like this:
ApJServAction .jsp /servlets/oracle.jsp.JspServlet
Save and close the jserv.conf file.
Restart your HTTP Server.
Setting up your project for Remote Debugging
You now need to set your project options so that remote debugging is enabled:
From the Project menu, select Project Properties.
Click the Run/Debug tab.
From Debug Files as: dropdown list, select Remote Debugging.
Click OK.
Debugging a portlet
Debugging a portlet is very similar to debugging any other Java program.
Set a breakpoint in the Java portlet code.
Start the debugger by selecting the Run->Debug menu option. This will bring up the Remote Debugging dialog. Choose the Oracle JVM
option if you are using the Oracle JVM, or Java Platform Debugging Architecture for a classic VM. Specify the hostname
where JServ is running. The port number has to be identical to the one specified in the JServ properties file. Clicking on
Attach will start the debugger in JDeveloper.
In this example we have specified the VM to debug on demand. Start your Web browser and open a connection to the Oracle9iAS Portal page with the HelloWorld portlet you created earlier.
When we refresh the Java portlet page from the browser, the portlet will stop at the breakpoint specified. From this point onwards you can debug the portlet as if you were debugging any other Java file. You can look at the value of variables and expressions or jump to conditional breakpoints or the next breakpoint.
You can also make changes to the code, save, compile and test it in the debug mode to check the required functionality. Use the "Reset" icon (red circle) when you want to stop the debugging.
When you use JDeveloper to develop and debug your portlets, you should keep the following guidelines in mind.
When debugging, invoke only a single portlet on an Oracle9iAS Portal page. If you are trying to debug a portlet, you will find it easier to create a page that only contains that portlet (or only a single portlet from the provider you are trying to debug). Otherwise you will receive multiple requests and JDeveloper may jump around strangely when stepping through the code. This is because the Parallel Page engine invokes multiple threads that may hit the same break point in which case JDeveloper switches to the one that just hit the breakpoint and drops the one you were working with.
Be aware that portlets time out on the Portal page during lengthy debugging bouts. Don't be surprised if your portlet has been timed out by the Portal by the time you have finished debugging. The Parallel Page engine only waits for so long before giving up. This timeout is configurable when you register your provider and can be overridden for each portlet in your provider.xml file.
For detailed information on building your own Web portlet, please review How to Build a Java Portlet . For more information about Remote Debugging, read the article Remote Debugging Server Side Java. The JDeveloper Online Demo Walkthroughs are also very helpful.
Revision History:
March 15, 2001