Plug-in for Java and Groovy

Eclipse is an open development platform developed by an open community. It includes extensible frameworks, tools and runtimes for building, deploying and managing software across the life cycle.

Prerequisites

If you choose to develop with Eclipse, the following prerequisites are required:

• Windows, Linux, or Mac operating system
• Java SE Development Kit (JDK) 5.0 or 6.0
  • Note: IBM employees should download the Java SDK from the IBM internal site.
• Eclipse IDE for Java Developers
  Note: Eclipse must be started with version 5.0 (or later) of the JDK or download errors will occur.

Installation

Update site

Detailed instructions

To use this platform, follow these installation steps:

1. If you do not already have Eclipse 3.2 (or later) installed go to http://www.eclipse.org to download and install it. Note: 3.4M6 and earlier milestones of 3.4 do not install the update correctly due to a bug in the eclipse update manager. If you want to use 3.4, you need to get a nightly build (N20080417-2000 or later) or use M7 or later when it becomes available.
2. WebSphere sMash plug-in also requires a version 1.5/5.0 (or later) JDK. The bin directory of the 1.5 JDK must be referenced in your PATH environment variable (appearing before any other Java installation). If you do not want to include the 1.5 JDK in your path, then you can start eclipse with a VM argument as shown in the following example:

   eclipse -vm <path_to_your_JDK>\bin\javaw
   

   Note: Use / for UNIX-based file systems.
3. To verify that the correct version of Java is in your PATH, type java -version .
4. Start Eclipse and click Window > Open Perspective > Java to change to the Java perspective.
5. To configure the update sites in Eclipse do the following:
   1. Click Help > Software Updates > Find and Install ...
   2. Select Search for new features to install and click Next >.
   3. Click New Remote Site ....
   4. Enter a name like WebSphere sMash Update Site and enter the following URL: https://www.projectzero.org/zero/silverstone/M1/update/zero.eclipse
   5. Click OK and then Finish.
6. To install the Eclipse plug-in, do the following:
   1. Select the checkbox next to the name of the update site you added (WebSphere sMash Update Site or the name you gave it) and click Next >. This will select all available features.
   2. Read and accept the license agreements and click Next >.
   3. Click Finish.
7. Choose Install All and then click Yes when asked to restart Eclipse.

Creating and running an application

To create and then run a WebSphere sMash application, use the following steps:

1. Click File > New > Project ....
2. Expand WebSphere sMash category folder near the bottom and click the WebSphere sMash Application project type.
3. Click Next >.
4. Enter a name for your new application and click Finish to create it. Your new project is shown with a distinctive icon beside it.
5. To run your new application, right-click the project and click Run As > WebSphere sMash Application. A message will be displayed in the console indicating that the application was started on port 8080.
   Note: All applications use port 8080 by default. If you have another application started, it cannot use the same port. The port is configured in the application's config/zero.config file.
6. In a browser go to http://localhost:8080/ to see the default page of your application. It should look something like this:
   
   
   
7. Stop your application.

Congratulations! You have created and run your first WebSphere sMash application. Read on to find out how you can add additional dependencies to enhance your application. You can also look at the Employee Demo or Suggest Demo for coding examples.

Adding dependencies

WebSphere sMash uses a dependency management utility called Ivy to ensure that your application is using the right versions of the libraries you declare as dependencies. In Ivy, these libraries are called modules, and they are located through a process called dependency resolution. See the documentation on Dependency Management for more information.

Under your project there are three containers, a JRE container and two WebSphere sMash library containers. WebSphere sMash library containers are:

Local Libraries

Adds all of the JAR and ZIP files from the /lib directory to your classpath .

Resolved Libraries

Resolves libraries from configured repositories and adds them to your classpath . This container uses an ivy.xml file located in the config directory to resolve dependencies from repositories and adds the resolved JAR and ZIP files to your classpath .

You can add JAR files to the project classpath by copying them into the lib directory of the project, or by adding dependencies from repositories. When a project is first created, it has one dependency: zero.core.

A library can be pulled from a repository. The following steps show how this is done by editing the dependency configuration to add the zero.data library to the project:

1. Stop your application if it is currently running. Applications should be stopped before modifying their configuration.
2. Double-click the config/ivy.xml file in your project to open Dependencies Editor as shown below:
   
   
3. Click the Add... button in the Dependencies section of the editor. The Dependency Selection dialog that displays allows you to select a dependency from the local repository which was installed with the Eclipse plug-in as shown below:
   
   
4. If your local repository does not already contain the dependency that you need, as is the case here, click the Manage Repository button to find the dependency in a remote repository. This opens a new dialog like the following example:
   
   
5. Enter zero.data in the Module field and click Search to find the zero.data library. After finding it, select it and click Download to add the zero.data library to your local repository and click Close to exit the Manage Repository dialog.
6. Now, from the Dependency Selection dialog select zero:zero.data(1.0+) from the list and click OK. The dependency has been added to the list.
7. Click Ctrl-S or File > Save to save the modified package information.
8. To see the zero.data library added to your classpath as shown below, expand the Resolved Libraries container under your project.
   
   
9. If the library is not currently located in a repository, then you can add a library to the Local Libraries container. To do this, drag and drop a JAR file into the /lib directory of your project. This triggers the Local Libraries container to refresh and add the library to your classpath . You can expand the Local Libraries container to see the JAR file.

Debugging

Start debugging your application by right-clicking your application folder and selecting Debug as > WebSphere sMash Application. After you see a message in the console indicating that your application is started, you can use your browser to fire a request.

In the example below a breakpoint was set in the target script, so the state of the GlobalContext during the request processing can be inspected. The structure of the GlobalContext can be difficult to inspect in the default Variables view. So, the WebSphere sMash plug-in provides a specialized debug view for the GlobalContext that presents the content as a tree.

This view is usually shown by default when debugging Groovy or Java source files. If it is not, then you can click Window > Show View > Other > Debug > GlobalContext.

Note: This debug view is limited when using the latest stable version of zero.core. It will not display the /app and /config zones. You will need to use the latest version of zero.core from the experimental repository to see these zones. Also, this view is limited to one thread. If multiple threads are suspended, e.g. multiple HTTP requests are suspended, then there are no guarantees as to which thread will be presented.

Using WebSphere sMash examples

If you installed all of the plug-ins (including the samples plug-in) from WebSphere sMash site, you can create example WebSphere sMash projects in your workspace.

1. Click File->New->Example....
2. If you have multiple Example types, expand WebSphere sMash Examples.
3. Select WebSphere sMash Example Projects and click Next >.
4. Choose one or more examples to create as projects in your Workspace and click Finish.

See the Employee Demo and Suggest Demo documentation for more example code.

Exporting applications

To export your application, use the following steps:

1. Right-click the project and click Export....
2. Expand the WebSphere sMash category.
3. Select WebSphere sMash Export Wizard and click Next.
4. Click Browse... to select a directory and store the exported zip file.
5. Check Include Source to include the source project.
6. Click Finish to export the project.

Note: you must include source if you plan to import the project back into Eclipse.

Importing applications

To import a WebSphere sMash application that has the source included (see above), use the following steps:

1. Click File > Import > General > Existing Projects into Workspace.
2. Click Next.
3. Select the Select Archive File radio button.
4. Select Browse... to locate your exported WebSphere sMash zip file (for a project that is not already in your workspace) and click OK.
5. Click Finish to import the checked project.