System iNetwork

January 2007

January 30, 2007 5:55 PM

Ways in which a System i rich client application "talks" to its "server".

I believe that a System i rich client application should not be a GUI implementation of monolithic 5250 programs which we inherited from RPG III. In general the MVC (model-viewer-control) design pattern is an effective paradigm for System i rich clients. Programs running on the System i provide the business model or domain specific representation of the information which is acted upon. The rich client provides the view of the data / information and controls the user interaction with the model.

Given that you accept this premise, what are the ways in which the viewer-controller (rich client) "talks" to the business mode (System i programs)?

Initially SQL and the JT Open Java Toolbox relational / direct access data classes come to mind. Remember, the premise that rich clients are simple replacements for 5250 programs. The obvious approach to an old dog like me was to read and write files like I'd been doing for so many years. Avoid this trap!

There is plenty of information about the use of SQL in Java (JDBC) so I won't repeat it. The System i Information Center and all the "Java for RPG programmers" books cover the JTOpen relational (direct access) data classes. The JTOpen Java Toolbox also provides program calls (like the OPM model), data queue support and access to several System i APIs. These same knowledge sources cover these topics. In future entries I will show some rich client implementation of these tools.

Here are three other techniques for Java rich clients (and applications) to interact with System i resources that aren't as well document, which you may find useful. I am going to describe them in detail in future blog entries. I hope some of you will comment. Perhaps help make them better. Perhaps challenge them. They are:

- Remote method invocation (RMI) of Java classes on the System i by a Java rich client (or application)
- Remote method invocation (RMI) of Java classes which wrap RPG service programs (JNI).
- Create objects on the System i that represent parts of the business model and serialize them in the IFS. The Java rich client (or application) deserializes the objects and uses them.

Do you use other techniques? Have you other techniques to get data or information back and forth between traditional System i applications and Java programs (rich clients, System i applications or remote applications)? If so please feel free to add your comments.

Posted by Bill Blalock on January 30, 2007 at 5:55 PM | Comments (1)

January 21, 2007 1:36 PM

Resources to learn about Eclipse RCP

I hope that some of the readers of this blog see potential for System i rich clients in their shop and that Eclipse is a good choice for building rich clients. Here are some suggestions for books I have found useful.

A side note first. A web article I read last week is good reading for those interested in arguments for the viability of rich clients. The article is on a Linux website, www.linux.sys-con.com. The title is "Eclipse: A Solid Desktop, Rich-Client, or Embedded Application Framework -- a general purpose platform".

I prefer a printed book to web sites, simply as a personal preference. Ed Burnette's tutorials provides several on line references for Eclipse RCP. These references are important as they cover very specific topics generally not covered in printed books (at least those I have reviewed).

My background and computer education is similar to many System i professionals, coming to Java from a procedural language background. My education was in Fortran and COBOL. First professionally programming in COBOL, I picked up who knows how many dialects of BASIC, Pascal and C along the way. Then I moved to the System 36 and in 1988 to the AS400 and found my professional home. Getting object oriented design concepts and programming into my head took a lot of effort. I hope my experience in learning to develop applications with Eclipse will save you some time and money.

Three books which I have found helpful for Eclipse RCP development are:

"Eclipse: Rich Client Platform" by Jeff McAffer and Jean-Michel Lemieux
"Eclipse: Building Commercial-Quality Plug-ins" by Eric Clayberg and Dan Rubel
"The Definitive Guide to SWT and JFace" by Rob Warner with Robert Harris

"Eclipse: Rich Client Platform" assumes you are somewhat familiar with the Eclipse IDE. It walks you through the development of a chat client in the first part (half of the book or so). The remaining parts cover RCP specific details of plugin development and reference materials.

"Eclipse: Building Commercial-Quality Plug-ins" introduces you to the Eclipse IDE then teaches how to build plug-ins to extend the Eclipse IDE. It introduces SWT and JFace and covers every part of plugin development.

I needed both books. RCP teaches how to write RCP but not plugins. Plug-ins teachs how to write plug-ins, from which RCPs are built, but doesn't got into RCP development.

My advice for someone who wants to quickly learn Eclipse RCP beyond Ed Burnette's tutorial is
- If you are starting with Eclipse then begin with "Eclipse: Building Commercial-Quality Plugins" and work through chapter 1. Continue with "Eclipse: Rich Client Platform" and work through part 1.
- If you are comfortable with Eclipse then start with "Eclipse: Rich Client Platform" and work through part 1, the hands on tutorial.
- Work through chapter 2 of "Eclipse: Building Commercial-Quality Plugins" which is a simple plug-in example. This goes much more quickly (a single chapter).
- Chapter 3 of "Eclipse: Building Commercial-Quality Plugins" explains the infrastructure of Eclipse, a different view of what was presented in "Eclipse: Rich Client Platform".
- Chapters 4 and 5 of "Eclipse: Building Commercial-Quality Plugins", introduce the Eclipse UI toolkit, SWT and JFace.

At this point you have the knowledge to start developing your own rich clients for the System i. This seems like a lot of preperatory work but it isn't. If you know the Eclipse IDE the tutorials move quickly. If you don't know Eclipse IDE you will learn a lot about it doing the tutorials.

Had I followed this advice instead of simply diving in after working through an Eclipse introduction tutorial I would have saved myself much time. The rest of these two books can be used as reference.

The third book, "The Definitive Guide to SWT and JFace", is where to go if you need more help with Eclipse user interface classes than the JavaDocs and Eclipse help. SWT and JFace are too rich to really cover in anything but a book dedicated to the subject.

If you already know AWT and Swing you probably won't need "The Definitive Guide to SWT and JFace".

Posted by Bill Blalock on January 21, 2007 at 1:36 PM | Comments (1)

January 10, 2007 5:08 PM

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 4:41 PM

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)