Configuring your development environment

Development environment

Development options and tools

A Geronimo Server Runtime in GEP associates a Geronimo 2.1 Server installation with a JRE to be used to run that server. A Geronimo Server in GEP associates a Geronimo Server Runtime with a profile consisting of Security settings, Publish Settings, Port Configuration, JVM settings to be used with that Geronimo Server Runtime.

Defining a Geronimo server runtime

In order to define a new Geronimo Server v2.2 Runtime, follow the steps below:

1. Click Window -> Preferences -> Server -> Runtime Environments.
   
   
   
   
2. Click Add to launch New Server Runtime Environment dialog.
3. Select Apache Geronimo v2.2, uncheck Create a new local server (we will discuss about the use of this option later) and click Next.
   
   
   
   
4. Select Workbench default JRE (Click Installed JREs to add any new JREs and return to this dialog once done). Note that you are recommended to run Geronimo 2.2 on Sun JDK 1.6. See Installing prerequisite software for more information about the JRE.
5. You must already have a Geronimo v2.2 installation that you want to use with GEP; enter the directory name or browse to <GERONIMO_HOME> and click Next.
   
6. Select the location of the archive containing Geronimo source. This is required only if you intend to debug into Geronimo source code.
7. Click Finish to return to Server Runtime Environments dialog.
   
   
   
   

Additional Server Runtimes to use a different Geronimo server installation or a different JRE can be added in a similar manner.

Defining a Geronimo server

Follow the steps below to define a new Geronimo v2.1 Server:

1. Launch the Define a New Server dialog using one of the following:
   • From the Servers view in the Java EE Perspective: Right-click, and New -> Server.
   • From any Perspective: Select File -> New -> Other -> Server.
     
     
     
     
2. Select Apache Geronimo v2.2 Server, specify the server name (by default Apache Geronimo v2.2 Server at localhost), and select an Apache Geronimo v2.2 from the Server runtime environment dropdown and click Next.
   
   
   
   

   Additional Server Runtimes can be installed by clicking on Configure runtime environments... button and return to this step once done to select the newly added server runtime. Or you can add another Geronimo 2.2 runtime environment by clicking "Add...".

3. Modify Hostname, Administrator Id, Administrator password, Web Connector port and RMI Naming port if necessary and click Finish. Normally you will not have to change the default values for these fields for a newly installed Geronimo 2.2 server.
   
   
   
   

This completes defining a new Geronimo 2.2 server. The newly added server will appear in the Servers view. The server can be started by selecting the server and clicking on the Start server button.

Administering the server

To view the server status in the Java EE perspective, open the Servers view. GEP monitors the server's status and sets the stopped, starting, and started indicators appropriately. This information is accurate even if you do not start or stop the server using Eclipse.

Starting the server

Use this procedure to start a server using the Eclipse framework.

1. In the Java EE perspective, open the Servers view.
2. On the Server panel, right click on the server to be started.
3. On the resulting context menu, click Start.

Stopping the server

Use this procedure to stop a server using the Eclipse framework.

1. In the Java EE perspective, open the Servers view.
2. On the Server panel, right click on the server to be stopped.
3. On the resulting context menu, click Stop.

Launching the administrative console

Use this procedure to launch the server's administrative console in Eclipse.

1. In the Java EE perspective, open the Servers view.
2. On the Server panel, right click on the server to be managed.
3. On the resulting context menu, click Launch WASCE Console.

Note: The server must be started for this option to be available and for it to work.

Launching the support

Use this procedure to launch the server's support page in Eclipse.

1. In the Java EE perspective, open the Servers view.
2. On the Server panel, right click on the server to be managed.
3. On the resulting context menu, click Launch WASCE Support.

Debugging the server

Use this procedure to start a server in debug mode using the Eclipse framework.

1. In the Java EE perspective, open the Servers view.
2. On the Server panel, right click on the server to be started.
3. On the resulting context menu, click Debug.

Creating custom server assemblies

Starting from Geronimo 2.2, you can customize server assemblies with GEP in Eclipse. See Assembling a server using GEP for more details about creating server assemblies using GEP.

Local deployment

Use this procedure to deploy Java EE assets to a local server.

1. In the Java EE perspective, select the Project view and right click the Java EE project you want to deploy. Select Run As, Run on server
2. On the Run on server panel, if you have an existing server, keep the Choose an existing server option and select the server. If you don't have a WASCE server defined, select the Manually define a new server option and select the WASCE server.
3. Click Finish. The WTP server adapter will deploy the Java EE assets shortly. If the server is not started, the WTP server adapter will start the server and deploy the Java EE asset when the server has initialized.

Removing an asset that has been published to the server

Once an asset has been published to the server, you must use the tool's Add/Remove project option if you want to remove it from the server. If you simply remove the asset without removing its project, the asset will remain deployed on the server.

1. In the Java EE perspective, the select the Server view.
2. On the Server panel, right click on the server where the asset was deployed.
3. On the resulting context menu, click Add/Remove Projects.
4. On the selection panel, click on the asset to undeploy and click the <Remove button to move it from the right to the left list. Click Finish.

Remote deployment

You can use the same steps discussed above to deploy a Java EE asset to a remote server, but there are additional considerations.

• To define a remote server, you must first define a local server and then change the value of its hostname attribute to the name of the remote server's host. This is required because the Eclipse framework must use the class libraries from the local server.
• You cannot use Eclipse to start, stop, or restart the remote server. You cannot use Eclipse to start the remote server in debug mode. Often, this limitation makes it more convenient to develop and debug your Java EE assets using a local server and then switch to a remote server when you need a common server to integrate your assets with assets from other developers.
• If there is a firewall between your system and the target server, it must be configured to permit both HTTP and RMI requests to flow between your system and the server's host. When the server is installed, the initial HTTP port is 8080 and the initial RMI port is 1099. If the target server has been configured to use different ports, the firewall must be configured to use those ports instead.
• Make sure the target system can be contacted by ping command.
• The remote server must be running when you invoke the deploy command. When you deploy or refresh your Java EE asset, the files will be copied across the network, saved as temporary files, and then deployed.

Debugging a remote application on an already running server

Before debugging the remote application on a running server, you have to start the server under jdpa debugger using geronimo.sh/bat:

geronimo jpda run

or

geronimo jpda start

Use this procedure to attach a remote application (a WAR file in this example) to an already running server started in debug mode.

1. On the Eclipse menu bar, click File and Import. On the Import panel, expand Web, select WAR file and click Next.
2. Specify the WAR file directory, and the target runtime. Click Next.
3. Import Web libraries if needed. Click Finish.
4. Left-click the down arrow following the debug icon on the main tool bar, and select Debug Configurations....
5. Select Remote Java Application, and click the 'New' button to create a new debug configuration.
6. Fill in the information about the server:
   • Name: as desired
   • Project: the WAR file you want to bebug on the server
   • Host: the server's hostname
   • Port: 5005 (or the appropriate value if the server's debug port has been changed.)
7. Click Debug.

Creating a new project

Once Geronimo Server Runtimes are defined, Eclipse provides these runtime for selecting as a target runtime while creating an EJB, Web and Java EE projects. Notice the Target Runtime field in the Dynamic Web Project dialog shown in the figure below.



Upon adding the Geronimo 2.2 server runtime as the target runtime, the Geronimo server libraries and Java EE specification libraries get automatically added to the build path of the project. GEP will also create Geronimo specific deployment plans.

In order to run an application on Geronimo, follow the steps below:

1. Right click on the project and click Run As -> Run on Server.
2. Click Choose and existing server, select Apache Geronimo v2.2 Server at localhost and click Finish.

The application can also be run on Geronimo by adding the project to the Geronimo server explicitly as given below:

1. In the Servers view, right click on Apache Geronimo v2.2 Server at localhost and select Add and Remove Projects.
2. In the Add and Remove Projects dialog, select the project under Available projects and click on Add button. The project will now be listed under Configured projects.
3. Click Finish.
4. If the server status is shown as Republish, right click on the server and select Publish.