System iNetwork

Tutorials

April 15, 2007

Use WDSc 7 for Eclipse RCP Development!

WDSc 7.0 has been available for a month now and it lives up to the expectations. System i Network has articles on the new version and more are on the way.

WDSc 7.0 can be used for Rich Client Platform development! The prior version of WDSc (6.01) did not completely support RCP development because it was based on Eclipse 3.0 and RCP development really needs Eclipse 3.1. WDSc 7.0 is based on Eclipse 3.2.1 ... close enough!

The RCP introductory tutorials which used Eclipse 3.2.x can now be done with WDSc 7. The JT Open toolbox can be used as a plug in instead of an external jar file. That is very neat!

Try these tutorials from earlier in this blog with WDSc 7:
Hands on -- Getting started with Eclipse RCP.
How to modify the Eclipse RCP tutorial (part 1) to connect to a System i.
Continuing to modify Eclipse RC Tutorial (part 1) into a System i client

There are no changes in Ed's tutorial, the first one. In the second tutorial is simplified by using jt400.jar as a dependent plugin (read on). The third tutorial has no changes.

So now you can have it all for a while under WDSc 7. Well at least until Europa rises ... that databinding is something else....

In "How to modify the Eclipse RCP tutorial (part 1) to connect to a System i" jt400.jar was treated as an external jar and added through the classpath, see section "Add jt400.jar to the project classpath".

Instead of following those instructions, do this to add the JT Open Toolbox to the list of required plug-ins.

- open META-INF/MANIFEST.MF with PDE (double click on it)

- select "dependecies" tab, third from left (see tutorial)

- in "Select a plug-in" type
com.ibm.etools.iseries.toolbox
two plugin will be listed
-- com.ibm.etools.iseries.toolbox
-- com.ibm.etools.iseries.toolbox.doc
highlight the first one (not .doc) and press the Add button.

- save the XML document

Now the toolbox is in the list of required plug ins. When you run the tutorials in WDSc the JT Open jar will be found. If you build an application and deploy it the JT Open jar file will be a part of it, just like the other Eclipse plugins.

Continue with the tutorials. That is the only change to do these RCP examples in WDSc 7.

Note that this change was not necessary to make these examples work in WDSc 7, the original instructions would have worked fine. We are benefiting from JT Open being a part ot WDSc and available as a plug-in.

Posted by Bill Blalock on April 15, 2007 at 12:00 PM | Comments (0)

January 10, 2007

Continuing to modify Eclipse RC Tutorial (part 1) into a System i client

The last blog entry explained how to modify the application created in Rich Client Tutorial Part 1 , Hello RCP, to connect to a System i. To demonstrate that the application was connected the modification fudged output to the console -- a cheezy cluge. This was needed because users interact with an Eclipse RCP application through views and editors. Hello RPC has neither, the template generated an empty perspective.

This blog entry extends the RCP application created in the last blog entry into a System i rich client application by explaining how to
- add SampleView, a view generated by a PDE template, and
- modify this view to display information from a System i.

1. Add SampleView, a view using a template provided by Eclipse IDE

A view is added by contributing a view extension to the org.eclipse.ui.views extension point. Open the your_domain.eclipsercp.tutorial.mod1 project's plugin.xml and go to the Extensions page. Click Add... and create an extension of type org.eclipse.ui.views. Type "org.." into the extension point filter and select this extension point.

At the bottom of the dialog you will see "SampleView" under "Available templaces for views:". Select this and click "Next".

The next dialog is titled "Main View Settings". Accept all the defaults and click "Next".

The "View Features" dialog is displayed. These features are the common ways this kind of view, a list, can interact with the application and user. Accept all the defaults and click "Finish".

A new package is created, your_domain.eclipsercp.tutorial.mod1.views. This was one of the default values in the "Main View Settings" dialog.

2. Add a constant for the view id

Go back to the Extensions page. The extension "org.eclipse.ui.views" is now listed. Open it then open "Sample View (view)". On the right is "Extension Element Details". The first property is "id*". This value has to be added to SampleView.java as a constant.

Copy the value into the clipboard. On my project this value is "info.billblalock.eclipsercp.tutorial.mod1.views.SampleView". Your view id should substitute "your_domain" for "info.billblalock", whatever you used when you created the project.

Open SampleView.java. Add a constant for the view id at the top of the class.

// view id constant

public static final String ID = 

	"info.billblalock.eclipsercp.tutorial.mod1.views.SampleView";	

private TableViewer viewer;	// original code generated by template

Remember, the value of ID must be the view id of the extension you created for your project. You can't cut and paste this snippet from the blog entry unless your project has the same name that mine does.

3. Add SampleView to the Perspective

Open Perspective.java. The overriden method createInitialLayout() is empty. Add two method calls to the IPageLayout which is passed to this method.

public void createInitialLayout(IPageLayout layout) {

	layout.setEditorAreaVisible(false);

	layout.addStandaloneView(SampleView.ID, false, IPageLayout.LEFT, 

			1.0f, layout.getEditorArea());

}

This code causes the SampleView to be executed when the Perspective, application window, is initally layed out by starting the RCP application. The view id (SampleView.ID) tells the plugin manager how the find the view to execute. The view id was added in step 2 and is used in this step.

4. Test the application

Run the application in the Eclipse IDE as you did previously. You will be prompted for the System i connection information and see the console output. This time you should have a table with rows "One" "Three" "Two". Right clicking any show two actions to select from, a demonstartion of actions. The table is sorted alphabetically.

5. Remove preStartup() and preShutdown() methods from ApplicationWorkbenchAdvisor.java

These methods were overriden simply to get the RCP Application to do something to prove it was connected to the System i. Remove the methods so the application doesn't required a console, so it can be run outside the Eclipse IDE.

6. Replace the String[] displayed in the table with an array of Strings from the System i

The SampleView.getElements() method returns an Object[] for the Jface table viewer to display. In the generated view, SampleView, this list of objects is a String[], {"One" "Two" "Three"}.

Modify the method getElements() of SampleView.java to return a String array from the System i. Many classes in the as400.access package of jt400 return String[] or Object[]. You can choose one that interests you! I chose to get a list of files from a folder of the IFS. To do this modify SampleView.getElements() this way:

public Object[] getElements(Object parent) {

	// return new String[] { "One", "Two", "Three" }; -- comment out 

	// IFS path to get list of files and folders

	String path = "/home";

	try {

		// use IFSFile class of jt400 to get list of files in path

		String[] fileList = new IFSFile(Activator.getAs400(), path).list();

		// null returned if the path does not exits, give user some output

		if( fileList == null )

			return new String[] {"Unable to list path: " + path};

		return fileList;

	}

	catch(IOException ioe) {

		// give user information about error returned

		return new String[] {"IOException from IFSFile.list() for " + path,

				ioe.getMessage() };

	}

	catch(Exception e) {

		// give user information about error returned

		return new String[] {"Unexpected Exception from IFSFILE.list() for " +

				path, e.getMessage() };

	}

}

Comment out the original String[] returned by the method.

Set the IFS path to list in "path". To list the root set "path" to "/".

Use the IFSFile.list() method to get a String[] of the files in the path of the IFS. See how the AS400 object created in the Activator is used?

IFSFile.list() returns null if the path is invalid or empty. If a null is returned then have getElements() return a String[] with something informative in it.

IFSFile can throw an IOException or an Exception. If this happens then have getElements() return something informative.

7. Test the application

The rich System i client you are developing should now display files and folders in the IFS "/home" folder of the System i. If there is no "/home" folder, or it is empty, the table will have two rows explaining the error. If there is a problem getting the folder, perhaps the ID does not have security rights, then two rows explaining the error will be displayed in the table.

8. Make a product and run the rich client System i client outside Eclipse

So far this modified version of the part 1 tutorial has been run from the Eclipse IDE. We stopped following the tutorial after "Taking it for a Spin", that is testing it from the IDE. See http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html This was necessary because the output which showed the System i connection was sent to the console.

The console output has been removed. Now follow the remaining steps of making this RCP application into a product and running it outside of Eclipse. This gives you a stand alone a rich client for a System i.

Comments

This demo project can easily be modied to display a list of anything that a class in ibm.com.as400.access returns as a String[] or Object[]. It is not much use but fun. This project demostrates using Eclipse RCP to build a rich System i client application.

Source code

The source code is on the CVSDude repository under the project "info.billblalock.eclipsercp.tutorial.mod1ver2". You may view it as web pages or check it out through Eclipse.

In this entry explain how to modify the application developed in the prior entry, the project which you created following the previous blog entry. So as not to overwrite the source for the previous blog I copied that project, changed the plug in id, and continued the development for this blog entry.

My e-mail address is b_blalock@comcast.net.

How to add a CVS repository to Eclipse for Exploring Eclipse RCP blog

1. First open up the CVS perspective. Click on "Window" -> "Open perspective" -> "Other" -> "CVS Repository Explorer"
2. Create a new Repository Location. Right click on the left window -> "New" -> "Repository Location".
3. Fill out the form

• Host: cvsdude.org


• Repository path: /cvs/billblalock


• User: systeminetworkblog


• Password: eclipsercp


• Connection type: pserver


• Select "Use default port" radio button


• Check "Save password"

4. Open the repository
5. Open HEAD
6. The projects will be listed. They can be explored through the CVS perspective or checked out.

Web access

The link for web access to the CVS repository for Exploring Eclipse RCP blog is http://cvsdude.com/vcvs/billblalock

• User: systeminetworkblog


• Password: eclipsercp

Eclipse projects will have a "src" folder. That is where the Java source will be found.

Thanks to CVSDude for hosting the materials for this blog at CVSDude : CVS, Subversion, Trac source control and project management hosting

Posted by Bill Blalock on January 10, 2007 at 5:08 PM | Comments (0)

January 3, 2007

How to modify the Eclipse RCP tutorial (part 1) to connect to a System i.

Previously I made a case for

1. Considering rich applications as one alternative to extend selected functionality of the System i to the desktop, and

2. using Eclipse RCP to create rich clients.

The last entry introduced Ed Burnette's Rich Client Tutorial to give hands on experience with Eclipse RCP. Part 1 of the tutorial walked you through creating a do-nothing basic Eclipse RCP application using the wizards. Part 2 of the tutorial explained the classes created by the wizard.

This entry adds a System i connection to to the rich application created in part 1 of the tutorial. The same basic Eclipse RCP application as part 1 of the tutorial will be created and then modified to connect to a System i using JTOpen or the System i java toolkit.

Creating a test project is very simple with the Eclipse RCP templates, probably faster than trying to unzip an archived starting point and get it into Eclipse. Repeat steps in Part 1 to create "Hello RCP" with these changes:

- name the project .eclipsercp.tutorial.mod1 instead of "org.eclipse.ui.tutorial.rcp.part1"
- change Application window title from "Hello RCP" to "Tutorial Mod 1"

otherwise take the defaults and follow the part 1 instructions. Stop after the step "Taking it for a spin".

The explanations of the classes in Part 2 of the tutorial apply for the most part to the new project just created by the wizard. There is one exception,the wizard creates "Activator.java" as the default (optional) activator class. In Part 2 of the tutorial this class is explained at the end under the heading "Plugin class", named "Part2Plugin.java". The wizard named this class "Activator.java".

Add jt400.jar to the project classpath

The Java toolkit which comes with the System i, or the open source JTOpen, is the java class library to provide java programs access to System i functions. jt400.jar is the primary archive.

To use jt400.jar in a java application you would add it to the classpath when compiling and executing the application. You also need to do this for Eclipse because JtOpen is not part of Eclipse.

1. Create a folder in the new project (right click the project > New > Folder) and call it "lib"

2. Import jt400.jar into the lib folder. Right click the folder > Import > File System

3. Add jt400.jar to the project classpath with these steps:
- open META-INF/MANIFEST.MF with PDE (double click on it)
- select "runtime" tab, third from left (see tutorial)
- in "Classpath" group press "Add" button. This opens a dialog titled "JAR Selection". The "lib" folder should be present. Open it and select jt400.jar.

4. Optionally attach the javadoc to the jt400.jar. You would want to do this so Eclipse can give you hover help and Shift F2 javadocs for JTOpen classes and methods.
- Right click jt400.jar which now in the project, probably immediately below the src folder
- Select properties
- Select javadoc location
- put in the location of the JTOpen javadocs. See the help dialog, question mark at bottom left, for more information.

Modify the Workbench Activator class

Part 2 of the tutorial explains the "Plugin class" which the wizard created as Activator.java. This class is optional,it does some setup before executing the application class and tear down when the application class completes. If not present the Application class is executed.

1. Import AS400 class from jt400.jar

	import com.ibm.as400.access.*;

The IDE gives the mesage that the import cannot be resolved when it cannot find jt400.jar. If you get this message look in the previous part for the problem. jt400.jar is listed in the first level of the project when it is loaded. In PDE it is listed on the "Runtime" tab, in the classpath section as described previously. If you look at the project properties, in "Java Build Path", jt400.jar will be on the Library and "Order and Export" tabs.

2. Declare global variable for AS400

	pivate static Activator plugin; // original code

	private static AS400 as400;

3. In the constructor create an instance of the AS400 class.

	public Activator() {

		plugin = this;  // original code

		as400 = new AS400();

	}

4. In the start() method connect to the System i, forcing the user to log on.

	public void start(BundleContext context) throws Exception {

		try {

			as400.connectService(AS400.CENTRAL);

			if ( !as400.isConnected() ) {

				System.out.println("unable to connect to System i");

				System.exit(0);

			}

		} catch(AS400SecurityException se) {

			System.out.println("signon cancelled or security failure");

			System.exit(0);

		} catch(Exception e) {

			e.printStackTrace();

			throw e;

		}


		super.start(context);  // original code

	}

5. In the stop() method disconnect from the System i.

	public void stop(BundleContext context) throws Exception {

		plugin = null;  // original code

		super.stop(context); // original code

		as400.disconnectAllServices();

		as400 = null;

	}

6. Add a method to get the AS400 object which was instantiated by the constructor and connected in the start() method. Make a copy of method getDefault() with cut and paste and change it,

	/**

	 * Returns the shared AS400 object

	 *

	 * @return the shared AS400 object

	 */

	public static AS400 getAs400() {

		return as400;

	}

 

When the RCP application is started the Activator constructor creates a session instance of an AS400 object.

Before starting the Application class the start() method will try to connect to the central services of the System i, forcing the uesr to enter the name of the system, a user id and password. Then it will test the connection, failing and ending if it cannot connect.

Before ending the Application class the stop() method will disconnect for the System i.

Modify the Workbench Advisor class

In the interest of keeping it simple and getting something to happen quickly lets override two methods of the Workbench Advisor explained in Part 2 to do something with the AS400 object, just to prove the RCP application is connected to the System i

	public void preStartup() {

		super.preStartup();

		System.out.println("Workbench Advisor preStartup() -- connected to System i: " + 

				Activator.getAs400().getSystemName());

	}

	

	public boolean preShutdown() {

		if ( Activator.getAs400().isConnected() )

			System.out.println("Workbench Advisor preShutdown() -- connected to System i!" );

		else

			System.out.println("Workbench Advisor preShutdown() -- not connected to System i!" );

		return super.preShutdown();

	}

Yes, cheezy but simple.

Try it! Run the project from within Eclipse. See Part 1 of the tutorial, "Taking it for a spin".

If the signon fails or is cancelled a message appears in the console.

If something truely bazzar happens when trying to connect to the System i a stack trace sent to the console.

After the connection is made the preStartup() method writes the name of the System i to the console, that is before the RCP application window appears.

The RCP application window appears, ta da.

When the RCP application is ended the connection is the preShutdown() method tests the connection and tells you if it is still connected to your System i.

Finaly the Activator disconnects all services and terminates the connection as part of the final clean up.

Discussion

The AS400 object was instantiated by the Activator class.

It could be instantiated in the Application class in either the preStartup() or postStartup() methods. You might want to do this so you can use the RCP Application facilities to communicate with the user, say the status line.

The RCP application preferences are availalbe at this point as are the system properties set by config.ini, so you could use these when creating the AS400 object. For example you could set a system property for the AS400 server name in config.ini then use it in the RCP application with System.getProperty().

The connection to the AS400 could be created in a view or editor when it was openned. It does not have to be "global" to the application. It depends on how you would use it.

Source code

Eclipse projects described in the blog, and other materials, will be posted in a CVS (Concurrent Versions System) version control system. Readers have access to the CVS. Eclipse has a built in CVS client which can view or check out these projects. A web based project browser is also available.

How to add a CVS repository to Eclipse for Exploring Eclipse RCP blog

1. First open up the CVS perspective. Click on "Window" -> "Open perspective" -> "Other" -> "CVS Repository Explorer"
2. Create a new Repository Location. Right click on the left window -> "New" -> "Repository Location".
3. Fill out the form

• Host: cvsdude.org


• Repository path: /cvs/billblalock


• User: systeminetworkblog


• Password: eclipsercp


• Connection type: pserver


• Select "Use default port" radio button


• Check "Save password"

4. Open the repository
5. Open HEAD
6. The projects will be listed. They can be explored through the CVS perspective or checked out.

Web access

The link for web access to the CVS repository for Exploring Eclipse RCP blog is http://cvsdude.com/vcvs/billblalock

• User: systeminetworkblog


• Password: eclipsercp

Eclipse projects will have a "src" folder. That is where the Java source will be found.

Thanks to CVSDude for hosting the materials for this blog at CVSDude : CVS, Subversion, Trac source control and project management hosting

Posted by Bill Blalock on January 3, 2007 at 4:41 PM | Comments (0)

December 18, 2006

Hands on -- Getting started with Eclipse RCP.

Now it is time to try Eclipse RCP by working through a tutorial to create and package an example Eclipse RCP application.

The pre-requisites are that you have some Java experience and are somewhat familiar with either Eclipse IDE or WDSc. The example applications in this tutorial will later be modified to use System i resources.

We will use Ed Burnette's "Rich Client Tutorial" as a common ground to discuss development of Eclipse RCP applications for the System i. The tutorial starts here:

http://www.eclipse.org/articles/Article-RCP-1/tutorial1.html

In later blog entries I will work through modifications connecting the rich client developed in the tutorial, or a variation of it, to a System i. Mr. Burnette's work is not being "jacked". I am simply not re-inventing the wheel here (re-use and all that ) and I could not do as well as Ed if I did write a tutorial for this blog.

If you want to try Eclipse RCP work, through this tutorial, at least parts 1 and 2. If you have problems, please check the newsgroups and other resources at eclipse.org and eclipsezone.org. We can also help each other on this blog. As time permits I'll answer the questions I can and hope other readers pitch in.

The "Getting Started" section of the tutorial assumes you are familiar with Eclipse. If you are familiar with WDSc but do not have Eclipse, this is what you need to do.

1. You will need Java 1.4.2 or 1.5.0. If you use WDSc 6.01 only the most recent upgraded IBM JVM meets this requirement. If yours does then use that, otherwise get the Java SDK from Sun.

If an older version of Java is installed on your desktop (or no version of Java at all!) but you want to try this, you are not out in the cold! WDSc is installed with its own private JVM. You can set up Eclipse this way as well. If you need help e-mail me b_blalock@comcast.net and I’ll send my notes on this.

2. Download the Eclipse SDK from http://www.eclipse.org/downloads. The SDK is what you need, not the Eclipse Distro. The current release is 3.2.1. WDSc is not appropriate for Eclipse RCP because the latest release is based on Eclipse 3.0.

3. Decide how you want to install Eclipse on your desktop. If the package is unzipped to C:\ then Eclipse will be installed in C:\eclipse\*. Consider unzipping it to something like C:\eclipse_ide, you end up with C:\eclipse_ide\eclipse\. Afterwards rename the folder to C:\eclipse_ide\eclipse_321\.

4. Run eclipse.exe. It will ask you where to create the workspace and suggest a folder in the home directory, C:\Documents and Setting\yada\workspace. Consider changing that to something like C:\eclipse_workspaces\learnRCP. Any path will work, I like to be able to easily find the workspace easily.

You will be happy to know that Eclipse won't "install" itself into Windows or your desktop. You will control where it goes. Uninstall Eclipse by deleting the installation folder -- that is it. No changes were made to the registry, nothing added or changed in the desktop OS. If you have ever done a manual uninstall of WDSc you will really appreciate this.

Now you are ready to work through the tutorial.

Future blog entries will create client / System i rich applications based on, or as variations of, this tutorial. The example "projects" will be available on a CVS (concurrent versioning system), you can "checkout" the projects.

Version control and software project management provided by CVSDude. See http://www.cvsdude.org

Posted by Bill Blalock on December 18, 2006 at 8:32 PM | Comments (0)