Eclipse Plug-In: DEPRECATED

This topic explains how to set up and use the Eclipse plug-in.

About the Eclipse Plug-In

The Eclipse Plug-In creates a bridge between the IBM Eclipse development environment and the platform. It gives you:

• A good, syntax-highlighting editor with “go to definition” capabilities and other features.
• The ability to compile your classes, to make sure they’re syntactically correct before putting them on the platform.
• The ability to keep your workspace synchronized with the platform.
• The ability to swap in a “hot fix” without restarting the platform.

Using the plug-in, you can create and edit these elements:

• A page which is a standard JSP (JavaServer Page) page with custom user interface elements or an independent tab
• A standard Java class that you write to create business logic that is not provided by the basic building blocks of the platform

Platform Requirements

The Eclipse plug-in has been tested with:

• Windows XP and Mac OS X operating systems
• Java version 1.6.0_02 and above
• Java SE Runtime Environment (build 1.6.0_02-b06)
• Java HotSpot Client VM (build 1.6.0_02-b06, mixed mode, sharing)
• Eclipse Helios for Java Developers, version 3.6.x

Set Up the Plug-In

1. Download the eclipse_plugin.zip, which contains the Eclipse plug-in JAR files.
2. View the JAR files in the ZIP archive.
3. Remove any earlier versions of those JAR files from the Eclipse plugins/ directory: {eclipse_IDE_installation}/plugins
4. Extract the three JAR files into {eclipse_IDE_installation}/plugins
5. (Re)start Eclipse.

Setting Up the Eclipse Plugin behind a Proxy Server

Some organizations have a proxy server that stands between you and the internet. (If in doubt, ask your network admin.) If so, you need to to take a few additional steps to connect to the platform through the proxy server.

To configure the proxy server settings:

1. Open the Eclipse IDE
2. Click Windows > Preferences > Network Connections > Manual Configurations
3. Add proxy server hostname
4. Optionally, add username and password
5. Save

Considerations

• If the proxy setting is enabled then Eclipse Plug-in expects the proxy settings as configured in Network Connections of Eclipse
• Eclipse Plug-in currently supports HTTP , HTTPS proxy types
• If both [HTTP, HTTPS] are specified then HTTPS proxy is given first preference

To enable the proxy settings:

1. From a project in the Eclipse IDE, right-click on any LongJump project
2. Click Properties > LongJump Authentication
3. Click the checkbox next to Enable proxy settings

After the proxy settings are enabled, the Eclipse Plug-in will pick up the proxy values from Network Connections and make the connection to the platform.

A Success message is displayed in the console window on successful connection.

Set up a Project

With the Eclipse plugin jars installed, the next step is to establish a project.

Create a New Project

To create a new project in Eclipse:

1. Temporary: Select the parent folder for the project.
   (Currently, you cannot select that folder when creating a new project.)
   • File > Switch Workspace > Other
   • Select the containing folder for the project directory that will be created.
2. Right click in Package Explorer
3. Click New > Project > LongJump > LongJump Project
4. Click [Next]
5. Enter project settings:
   • Project Name
   • Platform URL

   • http://localhost
   • https://{domain}

   • User Name: {platform login username}
   • Password: {platform login password}
6. Click [Finish]

   • The project is created, with folders for platform elements (classes and pages).
   • Any elements that are defined in the platform are automatically downloaded. (In essence, the platform acts as a shared repository.)
   • JARs containing global classes and API stubs for the platform are downloaded to the lib/ folder, and automatically added to the Eclipse environment.

7. Open the LongJump perspective:

   Window > Open Perspective > Other > LongJump

Manage Projects

To change the server URL, the login user name, or password:

1. Click Project > Properties
2. Click LongJump Authentication

To change the location where new projects are created by default:

1. Use File > Switch Workspace > Other
2. Select a new workspace folder.

To change the location of a project (visible using Project > Properties):
__TBD: This feature is not currently supported. If you move or rename a project, you get an error when trying to sync files with the platform server.__

1. Create a new directory to move project files into.
2. In Eclipse, right click on the project, and select Refactor > Move
3. Navigate to the new directory.
   If you created new_dir, the src/ folder is moved to new_dir/src, etc.

Migrating Classes for Use in the Plugin

There are three changes you need to make existing platform classes compile in Eclipse:

1. Add package statements
2. Add import statements
3. Qualify function references

Add Package Declarations

Package declarations are automatically supplied in platform classes. For your class to work in Eclipse, you need to add the package declaration:

package com.platform.{yourNamespace}.{yourPackageName};

Add Import Statements

In the platform, import statements are automatically added to your code. To get the same results in Eclipse, add these import statements:

import com.platform.api.*;     // For all classes
import com.platform.beans.*;   // For classes that use Java Beans

Qualify Function References

All platform methods are defined in the Functions class (more than 80 methods, in all). In the platform, a class could invoke those methods directly. But in Eclipse, those references need to be explicitly qualified. There are two ways to do it:

1. The right way (Use this for new code. Use it for old code if you have time.)
2. The fast way (Use this for old code, when you're in a hurry.)

Here's the right way:

• Add the Functions. qualifier to access methods defined in the Functions class.
• For example:
  • Functions.debug()
  • Functions.getParametersInstance().
  • etc. (The IDE will show you where changes are needed.)

Here's the fast way:

• Add a global import to make existing code work, without change:

import static com.platform.api.Functions.*;

It's preferable to use the Functions. qualifier, so anyone reading the code can see where the method is defined. But you can use the static import for a fast conversion.

Synchronize Files with the Platform

When you first create a project, the files for the classes, components, pages, and functions are copied from the platform to the project folder in your Eclipse workspace directory. You can then edit the files and save them locally.

To commit changes in a file, folder, or project to the platform:

1. Right click to display synchronization options.
2. Click [Save on server]
   (An error occurs if someone changed the file in the platform after you downloaded it.)

To restore an edited file, folder, or project:

1. Right click to display synchronization options.
2. Click [Refresh from server] to update the file from the platform
   You are prompted to make a backup copy of the local file in your project workspace.

Warning: Rename classes and packages in the platform. If you rename them in Eclipse, the platform won't know about the changed names.

Refactoring Operations

Refactoring operations need to be considered carefully. Methods defined in a class can be invoked by data policies, by external REST requests, and in many other ways. As much as possible, then, try to get things right at the outside, so that you don't have to change the names and locations of packages and classes later on.

Renaming Classes and JSP Pages

The Eclipse platform provides sophisticated refactoring operations. But when those operations are used to rename classes or JSP page, the Eclipse Plugin isn't aware of it. Platform-sync operations fail, as a result.

To rename classes and JSP most easily, use the platform GUI. There, a variety of checks occur to make sure that references to the class continue to work.

Moving a Class to Another Package

The plugin is unaware of local refactoring, so you can't do the move in Eclipse.

You can do the move in the platform by editing the package statement in the class, but in this version, the plugin doesn't know about that change, either. (It copies the class to the old location, but with the new package statement. The package statement then no longer matches the folder, so Eclipse reports an error.)

The solution then, is to:

1. Copy the class to the new package folder
2. Fix the package statement
3. Save the class to the server
4. Remove the old class

Renaming a Package

The plugin is similarly unaware of package renames. Since the platform doesn't have package-rename capability, the best course of action is to:

1. Make a new package folder in the file system and copy the class files to it.
2. Fix the package statements in the new files.
3. Save the new package to the server.
4. Remove the old package

It is then best to delete the old package on the platform. (An error occurs when attempting to deleted classes with referenced methods, which helps to ensure that all references remain valid.)

Create an Element

To create a new class or page:

1. Right click in Package Explorer and select New
2. Select the type of element. (You may need to use the long path the first time. After that, your choice will be readily available on the initial list.)
   • Other > Class
   • Other > Web > JSP File (Page)
3. Enter information about the element:
   • For a class, enter the Name.
   • For a page, select the parent folder (pages) and specify the File name.
4. Click [Finish]

Note: There are many other kinds of things you could create, but they won't be uploaded to the platform.

Use the LongJump Perspective

The LongJump Perspective adds menu items to Package Explorer and adds a Console view that displays status messages.

To open the LongJump perspective:

• Click Window > Open Perspective > Other > LongJump

Package Explorer Context Menu

The context menu in Package Explorer has a LongJump Server menu item with these subitems:

Save on Server

Saves locally modified elements to the server.

Refresh from Server

Gets new and modified elements from the server. When you replace a single file, you are prompted to make a backup if you made changes to the local file.

Delete from Server

After a confirmation dialog, removes the selected item from the server and deletes the local copy.

Refresh Library

Gets the latest version of LongJump libraries from the server. (Use this operation after upgrading the platform.)

LongJump Toolbar

The LongJump toolbar has icons for these operations (hover the cursor over the icons to see the names):

• Save on Server
• Refresh from Server

Troubleshooting

Sync and Refresh Operations return "Bad Request"

Early versions of the plug-in lack refined error messaging. To see the cause of the error, inspect the Eclipse error log:

• Window > Show View > Error Log

After identifying the cause of the problem, take the appropriate action. (One common cause is an invalid username or password.

Sync and Refresh Operations fail due to Invalid Password

The situation tends to arise when a developer has changed their password on the platform--for example, when the "password protection" security policies defined for the tenancy require it.

To reset username or password:

1. Right click in the project pane
2. Properties > LongJump Authentication