System iNetwork

These are the pre-requisites

You worked through the RCP tutorial by Ed Burnette on the Eclipse web site or had some other basic introduction to Eclipse RCP. This blog tutorial exercise modifies an example RCP application produced by Eclipse wizards. The different parts of the RCP produced by the wizards are explained in Ed's tutorial. This blog tutorial tells you what to modify but not why unless it is specific to data queues.

You built the System i demonstration model and view-controller. The RCP works with the demonstration model. By itself the RCP doesn't do anything. The demonstration view-controller on the System i will be used to provide input to the demonstration model. Without that there won't be anything for the model to read and display.

If you don't have access to a System i but you want to work through the Java parts of these exercises please write me. If there is need I will see what I can do to get you access to the demonstration model and view-controller on the system which I time share on. No promises except that I will try if there are requests.

You built the console data queue examples in the previous set blog entries (Java data queues 101-211), particularly the last one (Java data queues 211). The classes developed in Example3d, that is 211, will be used in this RCP application.

Where is the java source?

Links to html of each class referenced are not provided. If you want to see the modified source use the CVS web access to this project, info.billblalock.eclipsercp.dtaqdemo2_301 .

Eclipse RCP wizards will generate the code to be modified. The changes are simple and documented in this entry. The RCP Eclipse tutorial explains the code generated by the wizards.

You already have the dataqueue code from the Java data queues 211 blog entry.

Step 1 -- Use wizards to create a skeleton RCP to build upon

New > Project > Plug-in Project

Give it a name, my project name is

info.billblalock.eclipsercp.dtaqdemo2

Press Next

Change radio button to Yes for "Would you like to create a rich client application?" Press Next

Make sure "Create a plug-in using one of the templates" is checked. Choose "RCP application with a view." Press Next. This creates a view with a JFace table, the table data provider is a String[] statically loaded with the values shown.

Change "Application widow title:" from "RCP Application" to "RCP DtaQ Demo" or whatever you like. Press Finish

You should now have a skeleton RCP application. Try it and make sure it runs. For now run it from within Eclipse so output to stdout with System.out.println is shown in the console at the bottom of the IDE.

Step 2 -- Add JT Open archive to your project

Create a folder within your project named "lib". To do this right click your project,

New > Folder.

Import jt400.jar into lib. Right click the lib folder,

Import > General > File System and press Next.

Find the folder with jt400.jar on your system, check jt400.jar and press Finish.

If PDE is not open double click MANIFEST.MF in the META-INF folder to open it. Choose Runtime tab at the bottom. Press Add to the right of the Classpath box. You will see a list of folders in the project. Expand lib and select jt400.jar. Press Finish.

In the Java and Plug-in Development perspectives you will see that jt400.jar now appears in the root of the project, not in the lib folder.

How to add the JT Open archive to a project was explained in more detail earlier in the blog. If you need a more complete explanation see the modified RCP Tutorial blog entries.

An optional touch is to add javadocs to jt400.jar so the javadocs will be available from the Java editor. Right click jt400.jar,

Properties > Javadoc location

and put in the folder with the JT Open javadocs.

Try the application to make sure nothing was broken. Fix any errors before proceeding to the next step.

Step 3 -- Add or enable standard Eclipse RCP features

3a. Modify ApplicationActionBarAdvisor class to add About top level action to File menu. About will provide access to the log file. See the "Branding" section in Part 3 of the Eclipse RCP Tutorial for more information about the About feature.

Make a copy of

private IWorkbenchAction exitAction;

and change the copied statement to

private IWorkbenchAction aboutAction;


Make a copy of

exitAction = ActionFactory.QUIT.create(window);
register(exitAction);

and change the copied statement to

aboutAction = ActionFactory.ABOUT.create(window);
register(aboutAction);


Make a copy of

fileMenu.add(exitAction);

and change the copied statement to

fileMenu.add(aboutAction);


Try the application to make sure nothing was broken. Fix any errors before proceeding to the next step.

3b. Modify ApplicationWorkbenchWindowAdvisor to show status line.

A standard RCP feature not mentioned in the tutorial is the status line, at the bottom of the main window. In this application the status line will show the message received from the demo model. Later it will also show the user errors and alerts.

Change the line of code

configurer.setShowStatusLine(false);

to

configurer.setShowStatusLine(true);


3c. Modify ApplicationWorkbenchAdvisor to save window size and location. Override the WorkbenchAdvisor.initialize() method by adding this method:

	@Override

	public void initialize(IWorkbenchConfigurer configurer) {

		configurer.setSaveAndRestore(true);

	}

3d Modify Perspective class to show an editor area for future use.

The editor area is to be displayed so comment out

layout.setEditorAreaVisible(false);


Change the line of code

layout.addStandaloneView(View.ID, false, IPageLayout.LEFT, 1.0f, editorArea);

to

layout.addStandaloneView(View.ID, false, IPageLayout.TOP, 0.50f, editorArea);


this puts the view on the top half of the window and saves the bottom half for the future editor.

Try the application to make sure nothing was broken. Fix any errors before proceeding to the next step.

3e View class needs a means for other classes to reference it.

Do this the same way that the Activator class provides a means for other classes to reference Activator through the getDefault() method.

Add a static View object

	// The shared instance

	private static View plugin; 

	/**

	 * The constructor.

	 */

	public View() {

		plugin = this;

	}

	/**

	 * Returns the shared instance

	 *

	 * @return the shared instance

	 */

	public static View getDefault() {

		return plugin;

	}

Step 4 -- Create a dataqueue package and import classes created in DtaQExample3d

4a Create the package. The package is the same root name of the package which contains the source generated by the wizard plug ".dataqueue". For example the package created for my project is

info.billblalock.eclipsercp.dtaqdemo2

The dataqueue package I will create will be named

info.billblalock.eclipsercp.dtaqdemo2.dataqueue

Your package name is based on the project name you choose.

Right click the project,

New > Package.

Put in the name of the package.

4b Import classes from the Java data queue examples into the new package. My project name, and the name in the CVS is:

info.billblalock.mvcintro.java_apps

Import all the classes in the common package into the new package.

Import only these classes from the dataqueue package into the new package.
- DtaQExample3dListener.java
- ModelInputDataQueue.java
- ModelOutputDataQueue.java

Right click the package,

Import > File system press Next

Find the common package, select all the classes and import them

Right click the package,

Import > File system press Next

Find the dataqueue package, select the three classes named above and import them

4c Fix the errors now in the imported classes.

All the imported packages will indicate errors. The first step to fixing these errors is to change the package from
package common;
or
package dataqueue;

to (for my case)
package info.billblalock.eclipsercp.dtaqdemo2.dataqueue;

Use the package name you specified in step 4a.

The only error remaining should be in DtaQExample3dListener. Edit this class. The remaining error should be this import statement

import common.MDLOFMFormat;

Remove or comment it out. The common package doesn't exist in this project and the MDLOFMFormat class is now in the same package so it doesn't need an import statement.

The dataqueue package should now have no errors. If there still errors you are on your own to track them down and fix them. Some classes in this package will have to be tweaked to work with the RCP GUI instead of the console (stdout) but most of the work is done and tested. How about that, reuse of classes!

Try the application to make sure nothing was broken. If there are still errors in the new dataqueue package you will get a warning that errors exist in the project. Since these classes aren't referenced yet the project will still run so press Proceed. Fix any errors before proceeding to the next step.

4d Use DtaQExample3dListener as the property change listener for this project.

Refactor > rename

DtaQExample3dListener.java

to

ModelDemoOutputDqListener.java


4e Add a method to the renamed listener class to update the status line of the RCP window. This is one means the listener will communicate what happens when a model output data queue entry is read, or attempted to be read.

    /**

     * Set status line of RCP with this message.

     * @param message String to be placed on status line.

     */

    private void setStatusline(final String message) {

    	Activator.getDefault().getWorkbench().getDisplay().syncExec(new Runnable() {

			public void run() {

				View.getDefault().getViewSite().getActionBars()

				.getStatusLineManager().setMessage(message);

			}

		});

	}

The listener is running of in its own thread, totally disconnected from the thread in which the RCP is running. This is going to grab a reference to the thread in with the RCP UI is running and call the UI method to write the status line.

4f The listener now writes the data received from the data queue to the console. Also send the message received from the data queue to the status line.

Find this code:

	// Get two values out of the record and display them.

	String mdloInstruction = (String) mdloData.getField("OINSTRTN");

	String mdloMessage = (String) mdloData.getField("OMESSAGE");

	System.out.println("     *   The model received instruction: "

		+ mdloInstruction.trim()

		+ "\n     *                and returned data: "

		+ mdloMessage.trim());

	System.out.println("     *********************************************");

	setStatusline( mdloMessage.trim());	

Try the application to make sure nothing was broken. You will get a warning that errors exist in the project. Since these classes aren't referenced yet the project will still run so press Proceed. Fix any errors before proceeding to the next step.

The next step makes RCP DtaQ Demo a partner with your System i so it needs to be working at this point. This is the last chance you have to test the RCP without needing to be connected to a System i and have the demonstration model running.

Step 5 -- Connect RCP DtaQ Demo to the AS400 through the Activator class.

Now the project is ready to connect to the AS400.

The pseudo code logic of Java data queues 201 Example3d, the main() method, is:
i. set up the System i connection
ii. instantiated the Runnable, attached the listener, created the Thread that listens to the model output data queue and started the Thread.
iii. instantiated the object to write to the model input data queue
iv. looped accepting input to send to the model input data queue
v. looked for the end signal, *STOPITNOW, to break the loop
vi. closed down the Thread and disconnected from the System i.

Activator will be modified to do steps i, ii, iii and vi. The UI nature of the RCP replaces the need to loop waiting for input (iv). The exit action in the File menu or upper right X takes the place of the end signal (v).

5a. Add these class global variables to Activator

	private static AS400 as400;

	private static Thread mdloDqThread;

	private static ModelOutputDataQueue mdloDq;

5b Instantiate the AS400 object in the constructor

	as400 = new AS400();

5c Add this code from DtaQExample3d (see previous blog entries) to the start() method
after the call to the base start() method:

	super.start(context);		// base start() method


	// added code

	try {

		as400.connectService(AS400.CENTRAL);

		// create instance of Runnable for Thread which reads data queue

		mdloDq = new ModelOutputDataQueue(as400, Me.getMDLO_DTAQ(), 

				IpDtaQKey.getDqKey() );

		// execute the run() method of the thread

		mdloDqThread = new Thread(mdloDq);

		// register a separate class as the listener for

		// property change events

		mdloDq.addPropertyChangeListener(new ModelDemoOutputDqListener() );

		// execute the run() method of the thread

		mdloDqThread.start();

		if ( !as400.isConnected() ) {

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

			System.exit(0);

		}

	} catch(AS400SecurityException se) {

		System.out.println("... signon cancelled");

		System.exit(0);

	} catch(Exception e) {

		e.printStackTrace();

		throw e;

	}

5d. Modify the stop() method to shut down the Thread which reads the model's output data queue. After the call to the base stopt() method add this code:

		super.stop(context);		// base stop method


		// added code

		mdloDq.stopReadingDq();

		try {

			mdloDqThread.join(5000);

		} catch (InterruptedException e) {

			// do nothing

		}

		as400.disconnectAllServices();

		as400 = null;

The stop() method now implements part vi of Example 3d. The stop() method is called when the UI shuts down.

Interlude --

At this point RCP DtaQ Demo can read the demonstration model's output data queue and display the message in the status line. You have to run it within Eclispe so that you can see the console output (System.out.println … we haven't eliminated it yet). This is a good place to take a break.

Here is how to test it.

1. Start the demonstration model on the System i. Use the demonstration CL view-controller on the System i to make sure it is running properly.

2. Start RCP DtaQ Demo in Eclipse so the stdout output goes to the console window.

3. You will be prompted for the AS400 connection information. After the connection is established the key that is generated from the IP address is displayed in the console.

4. Note the key generated -- in my case it is A80008. See the image at the introduction of this entry.

5. Use the demonstration view-client CL program on the System i to cause the model to write a data queue entry to the model's output data queue.

Use the key that the RCP is listening for. Use the CL option for the view-controller to only write the model output data queue (last parameter is *YES), we want RCP Dtaq Demo to read it … not to have the CL view-controller read it first.

6. Shortly after the Enter is pressed the message from the demonstration model will show up in the status line and the console will show the stdout output. showing message in status line and console.jpg

The source is in the CVS. The project is info.billblalock.eclipsercp.dtaqdemo2_301. I renamed the project so that this version would remain as it is, at version _301, and futher development would be posted under other versions.

RCP DtaQ Demo will later be enhanced to
- remove the console output, use the UI and log errors
- display the data queue messages in the view
- accept demonstration model input from the user.
I'll try to go a little more slowly, make the entries smaller and have more explanation since the new materials aren't covered by the RCP Tutorial (Ed Burnette) and Java data queues 101-211. This one turned out rather long because this is what it took to go from nothing to an RCP application which did something.