 | Level: Introductory Marcy Howerter (howerter@us.ibm.com), Software Engineer, IBM
28 Sep 2004 Learn how to debug Integrated Solutions Console components using WebSphere® Studio Application Developer Version 5.1 and WebSphere Portal Toolkit Version 5.0.2. This article shows you how you can use the ISC Framework to manage the administrative console functions as solutions rather than as specific products -- a serious time saver.
Introduction
The IBM® Integrated Solutions Console components manage administrative console functions in the Integrated Solutions Console framework. Using the Integrated Solutions Console Framework, you can manage the administrative console functions as solutions rather than as specific products. The Integrated Solutions Console framework is based on a lightweight version IBM WebSphere Portal Server Version 5.0.2 and hosts the administrative console functions as Integrated Solutions Console components. This article illustrates the process of debugging Integrated Solutions Console components using WebSphere Studio Application Developer Version 5.1 and WebSphere Portal Toolkit Version 5.0.2.
Before you begin to develop your Integrated Solutions Console components, you should set up an environment that makes it easier to develop, compile, package, and debug. The Integrated Solutions Console Toolkit gives you an environment to develop your components, but it does not include a local test environment where you can run and debug your components. In this article, I'll show you how to set up your Integrated Solutions Console development environment to debug your components remotely. Using the steps in this article, you can set up this remote debugging environment quickly, so you can more efficiently develop your Integrated Solutions Console components.
Setting up the Integrated Solutions Console Toolkit environment
To debug Integrated Solutions Console Components using the WebSphere Studio Application Developer Version 5.1, the WebSphere Portal Toolkit plug-in Version 5.0.2, and Integrated Solutions Console plug-in Version 5.0.2, I recommend the following two-machine setup, although it is certainly possible to keep both parts on one machine.
- On the Integrated Solutions Console run-time machine, install the Integrated Solutions Console Version 5.0.2 to deploy and test the Integrated Solutions Console components.
- On your development machine, install WebSphere Studio Application Developer Version 5.1.2 with WebSphere Portal Toolkit Version 5.0.2.2, and the Integrated Solutions Console Toolkit plug-in Version 5.0.2 to develop Integrated Solutions Console components.
Download and install these components:
For more information on setting up an Integrated Solutions Console development environment, select References > Installing the Toolkit section in the Developer InfoCenter (http://isc_development_hostname:help_port_number/help/index.jsp) on the development server.
Developing, packaging, and deploying an Integrated Solutions Console component
An instance of an Integrated Solutions Console consists of the Integrated Solutions Console framework hosting a set of console components built by various development organizations. Integrated Solutions Console components include a collection of portlets that enable administration and management functions. A variety of tools are available for developing your component's portlet applications; the tools you use depend on your requirements and your product team guidelines. To help in the development of Integrated Solutions Console components, the Toolkit installation program provides the option to install a plug-in for WebSphere Studio Application Developer. The following topics guide you through using the WebSphere Studio Application Developer environment to develop, package, and deploy your component
Create a new project in WebSphere Studio Application Developer
The Integrated Solutions Console Developer InfoCenter contains documentation to assist you in developing Integrated Solutions Console Console components. The Developer Information Center can be accessed by going to http://<your_server_name>:8430/help on the machine where you have installed the Integrated Solutions Console Toolkit.
Packaging an Integrated Solutions Console Component
An Integrated Solutions Console component must be packaged as a Web application archive (WAR) file for successful deployment into an Integrated Solutions Console instance. Perform the following steps to create the WAR file:
- Include the Integrated Solutions Console Java Archive (JAR) files. In order to successfully compile your component in WebSphere Studio Application Developer, the Integrated Solutions Console JAR files must be included in the Java programming build path if you are using Integrated Solutions Console-specific APIs within your component.
- Right-click on the project name in the Navigator window and select Project Properties > Java Build path > Libraries > Add External JARs as shown in Figure 1. In this example, the project is HelloWorldISCComponent.
Figure 1. Add external JAR files in WebSphere Studio Application Developer
- Browse, in the JAR selection window, to the isc_runtime_root_dir\PortalServer\shared\app directory and select the Integrated Solutions Console JAR files (isc.jar, iscapi.jar).
Depending on your component, you might need to repeat step 1 to add more JAR files to the Java build path.
- Rebuild the project by right-clicking on the project name and selecting Rebuild Project.
Figure 2. Rebuild project
- Export the WAR file by right-clicking on the project name in the navigation window and selecting Export.
- Select the WAR file destination type and click Next.
An export resources to a WAR file window appears as shown in Figure 3.
Figure 3. Export the Integrated Solutions Console component as a WAR file
- Select the project name in the What resources do you want to export? field and enter the destination of the exported WAR file in the Where do you want to export resources to? field of the Export Resources to a WAR File window. Click Finish.
Figure 4. Select the component and destination file
Deploying and verifying the Integrated Solutions Console component
After you create the WAR file for a component, you can deploy the component to a system where the run time for the Integrated Solutions Console is installed and then test that the component works correctly.
- Copy the Integrated Solutions Console component WAR file from the development machine to the server machine.
- Ensure that the console server is started. You do not need to log in to the console.
- Deploy the war file using the following command from a dos command window.
isc_root\PortalServer\bin\IscDeploy.bat war_file userid password url
where:
war_file is the relative or absolute path and file name of the component WAR file.
userid is a valid Integrated Solutions Console administrator user ID.
password is the password for the userid.
url is the fully-qualified URL for accessing the deployment servlet that is running on the Integrated Solutions Console installation. The URL must include the protocol, the port number for the Integrated Solutions Console, and the context URI for the deployment servlet, which is deploy/deploy.
An example of this command is:
IscDeploy.bat C:\ISCDevelopment\myComponent.war iscadmin iscpass http://myserver.com:8421/deploy/deploy
- Verify the deployment by opening a browser window and pointing to http://servername:port_number/ibm/console.
- Log in to the Integrated Solutions Console as an administrator.
Figure 5. Log in to the Integrated Solutions Console
- Verify that the Hello World Elements organizational node and the Hello World Integrated Solutions Console Page page are listed in the navigation tree as shown in Figure 6.
- Click on the Hello World Integrated Solutions Console Page, and verify that it renders 'This is HelloWorldISCComponent Operating in View mode'
as shown in Figure 6.
Figure 6. Verify the Component
 |
Debugging an Integrated Solutions Console Component
After you have developed and deployed your component, you can now perform remote debugging from within your WebSphere Studio Application Developer environment. There are some setup steps necessary both on the server as well as within WebSphere Studio Application Developer.
Setting up the Server
To set up the server:
- Generate the debugPortal.bat file. You must generate the bat file that is used to tell the WebSphere Application Server instance to listen on the debug port. Because you use the
-script option it does not actually start the server; it only creates the c:\debugPortal.bat file. Issue the following command to create the debugPortal.bat file:
c:\IBM\MgmtPortal\AppSever\bin\startServer ISC_Portal -username iscadmin -password iscpass -script c:\debugPortal.bat
A sample c:\debugPortal.bat file is shown in Figure 7:
Figure 7. Sample debutPortal.bat file
- Modify the debugPortal.bat file to ensure that setupCmdLine.bat is being referenced from the correct directory (highlighted in blue in Figure 7).
call "your_isc_runtime_root\AppServer\bin\setupCmdLine.bat"
- Uncomment the line that sets the
DEBUG environment variable and change the suspend=y to suspend=n.
The line should now look like:
set DEBUG=-Djava.compiler=NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777
- Start your server. If your server is currently running, stop it using
stopServer.bat.
- From a DOS prompt, use the debugPortal.bat script to actually start your server. The debugPortal.bat does not return. Because there is no feedback on the command line, check the C:\IBM\MgmtPortal\PortalServer\log\SystemOut.log to determine when the server is completely started.
After the server is completely started you see Server ISC_Portal open for e-business at the bottom of the SystemOut.log file as shown in Figure 8.
Figure 8. SystemOut.log file
Note: This solution lets you start the server in either normal mode or debug mode depending on which bat file you use.
Setting up WebSphere Studio Application Developer
To begin setting up WebSphere Studio Application Developer, start WebSphere Studio Application Developer and launch the debugger for your project.
- Open the Java perspective by selecting Window > Open Perspective > Java.
Figure 9. Open the Java perspective
- Open your console component source code to debug.
- Set break points in your project where you would like to start debugging.
Figure 10. Set breakpoints
- From the Run menu, select Debug....
Figure 11. Select Debug...
- Select WebSphere Application Server Debug from the Navigation tree on the left side of the Debug window. If you have not used this before, right-click WebSphere Application Server Debug and select New.
Figure 12. New WebSphere Application Server debug configuration
- Select a name for the new debug launch configuration.
- Select Browse, and browse to the project that you would like to debug.
Note: This project must also be deployed onto the Integrated Solutions Console run-time instance that is running on your remote server. See Deploying the Integrated Solutions Console component.
- Specify the Integrated Solutions Console server name in the Host name field.
- Make sure the JVM Debug Port field is the same value as the Port specified in the debugPortal.bat file. By default, a port value of 7777 is specified in both places.
Figure 13. Create a new configuration
- Select Apply.
- Select Debug.
Figure 14. Create, manage, and run configurations
- Invoke the application to debug it.
- Log in to the Integrated Solutions Console.
- Perform the appropriate function within your console component to hit the breakpoints that you set in your source code.
Figure 15. Invoke Hello World Integrated Solutions Console component
- End the debug session by right-clicking on the item in the Debug Perspective and selecting Disconnect.
Figure 16. Disconnect debug session
To disable the debug mode, submit a stopServer.bat command from a DOS prompt. When this complete the debugPortal.bat ends.
Conclusion
In this article I've covered how to set up your development environment to debug Integrated Solutions Console components remotely from within WebSphere Studio Application Developer. Using these steps, you can develop, deploy, and debug your Integrated Solutions Console components. After the steps are completed you can use all of the application debugging capabilities provided by the WebSphere Studio Application Developer environment.
Resources - Create an administrative suite (developerWorks, February 2004) is a tutorial that reviews the process for creating an Integrated Solutions Console component that performs administrative functions.
- In her article, Meet the experts: Kathryn Britton on Autonomic computing's Integrated Solutions Console (developerWorks, August 2004), Kathryn describes the ISC and how it works, how you can preview it, and how you can participate in the development and use of this key Autonomic technology.
- Enable a help system in the Integrated Solutions Console (developerWorks, May 2004) goes step by step through creating the help plug-in, creating help links for Integrated Solutions Console components, and packaging the plug-in in the console component WAR file. A downloadable sample makes it simple for you to follow along.
- Help in the Integrated Solutions Console (developerWorks, February 2004) takes you through the features of a common help framework for Web-based applications that are deployed to the IBM Integrated Solutions Console Version 5.0.1.
- The Autonomic Computing Toolkit provides more information on the Autonomic Computing Toolkit components such as the Integrated Solutions Console.
About the author | 
| | Marcy Howerter is a Software Engineer at IBM focusing on enablement and tooling development for the Integrated Solutions Console. She holds a bachelor's degree in Computer Science and Mathematics from Luther College in Decorah, IA. She can be reached at howerter@us.ibm.com. |
Rate this page
| |
