Start Programming with iPush

On-the-fly "Hello world" with Eclipse (printing-friendly)

Step-by-Step develop an iPush client with Eclipse

July 4, 2006, by Tony Hsiao, Technical Consultant of ICE Technology Corp.

Level: Beginning

API: Java Package

Background

This article shows the developer how to use the Java development tool - Eclipse to write a simple iPush client in 10 minutes. This illustrates the simplicity of iPush programming for developing real-time messaging applications.

Requirements

Before you start to exercise this programming example, make sure your environment got:

1. J2SDK 1.3 or above installed. (get J2SDK from http://java.sun.com)
2. Eclipse 3.0 or above installed. (get Eclipse from http://www.eclipse.org)
3. iPush V2 Java Package API (Java.zip) and extract it to a folder. (get iPush V2 Java Package API from http://www.icetechnology.com/developer/download.jsp, need you to be a member of ICE Developer Center first)

Start it up

Follow the instruction in each step to build your iPush Java application with Eclipse.

Step 1 - Create a new Project

Open the Eclipse, and select [File] / [New] / [Project].

Figure 1. open a new project

Step 2 - Select a wizard

(a) In [New Project] dialog , select Java Project to launch the wizard.

(b) Click the [Next] button.

Figure 2. select Java Project wizard

Step 3 - Set properties of the project

(a) In [New Java Project] dialog, type iPushDemo in the Project name field.

(b) In Project layout pane, we recommend you select Create separate source and output folders.

(c) Click [Next] button to continue.

Figure 3. give a project name

Step 4 - Add iPush Java API to the project

(a) Click <Libraries> tab, and click [Add External JARs] button.

Figure 4. switch to <Libraries> tab

(b) In the pop-up [JAR Selection] dialog, select the iPush V2 Java Package library file - iceipush2.jar which you've downloaded.

Figure 5. add iceipush2.jar as external package

Note: actually, we recommend you select iceipush2_jvm1.5.jar instead of iceipush2.jar to get faster connection to iPush Server when you are using J2SDK 1.5 or JRE 1.5.

(c) Now you can see the iceipush2.jar shown in dialog. Click [Finish] button to generate this new project.

Figure 6. finish and generate this iPushDemo project

Step 5 - Check project components

Back to Eclipse workbench, in Package Explorer, you'll see the project iPushDemo just created and the JARs included.

Figure 7. check project components of iPushDemo

Step 6 - Create a new class iPushDemo

We are going to create a new class of iPushDemo and set its properties.

(a) Move your cursor on folder of iPushDemo project src , right-click then select [New] / [Class].

Figure 8. create a new class

(b) In [New Java Class] dialog, type iPushDemo in the Name field.

(c) In Which method stubs would you like to create? block, check all three items to make Eclipse generates some methods automatically.

(d) Click [Add] button.

Figure 9. set properties for class iPushDemo

(e) Type iPush in Choose interfaces field (case-sensitive), you'll see iPush2MsgListener shown in the Matching types list.

(f) Select iPush2MsgListener and click [Add] button to add it in Interfaces list.

Figure 10. select implemented interface iPush2MsgListener

(g) Click [OK] button to return [New Java Class] dialog.

(h) You can see com.icetech.ipush2.iPush2MsgListener shown in the Interfaces pane of [New Java Class] dialog.

(i) Click [Finish] button to generate the new class iPushDemo.

Figure 11. finish and generate the new class iPushDemo

Step 7 - Check the new class iPushDemo

You can see the function structure of the class iPushDemo in the Java editor now.

Figure 12. the function structure of the class iPushDemo

Step 8 - New an instance of class iPush2Link - ip1

It's time to new an instance of iPush2Link, the main object for communicating with iPush Server.

If you have never developed any iPush application, you may ask: how do I know the exact class name of iPush API?

Don't worry, you can find class name easily with Code Assist of Eclipse.

(a) Type private com.icetech.ipush2. (the package name) at the first line of the class iPushDemo implements iPush2MsgListener, like Figure 13 shown.

(b) Code Assist will show you all classes and interfaces matched.

(c) Choose iPush2Link.

Figure 13. use Code Assist to help programming

(d) Code Assist will automatically fill the name of the chosen class (iPush2Link here).

Figure 14. Code Assist will automatically fill the name of the chosen class

(e) Declare ipl is an instance of class iPush2Link and create it.

private iPush2Link ip1 = new iPush2Link();

Figure 15. declare ip1 is an instance of class iPush2Link

Step 9 - Declare an integer to store connection ID

Each client will get an unique connection ID after it connects to iPush Server successfully.

We declare an integer variable named connId to store the connection ID. The connection ID is very important because you need it to present the client in many invoked methods after the client got connected.

Figure 16. variable connId will be used to store the connection ID

Step 10 - Connect to iPush Server

We are going to connect to iPush Server in the constructor iPushDemo().

(a) Make ipl invoke ipushTCPConnect() to connect to iPush Server and assign the return value to connId.

connId = ip1.ipushTCPConnect();

Figure 17. Type connId = ip1.ipushT to trigger the Code Assist for auto-completing.

Step 11 - See the arguments needed

Code Assist will show the 9 arguments (arg0~8) needed. They are:

1. iPush2MsgListener
2. iPush Server IP
3. iPush Server Port
4. Proxy IP
5. Proxy Port
6. Group
7. Product
8. Username
9. Password

Figure 18. 9 arguments needed for connecting to iPush Server

Step 12 - Give the value of arguments

For proceeding this example, we had created a demo service and account in ICE Technology's public iPush Server.

1. iPush2MsgListener: this
2. iPush Server IP: "www.icetechnology.com"
3. iPush Server Port: 8000
4. Proxy IP: "" (depend on your network environment. Empty string means no proxy used here.)
5. Proxy Port: 0 (depend on your network environment. 0 means no proxy used here.)
6. Group: "ICE"
7. Product: "iPush"
8. Username: "eclipse"
9. Password: "eclipse"

ip1.ipushTCPConnect(this,"www.icetechnology.com",8000,"",0,"ICE","iPush","eclipse","eclipse");

Figure 19. give the value of arguments with demo account or your own

To avoid receiving unexpected messages (from others use this demo account too), we encourage you to use your own iPush account. ICE Technology provides two ways of getting free iPush accounts:

• Apply Quick Start service of ICE Technology
• Download and get a free trial license to install your own iPush Server

Both need you to be a member of ICE Developer Center first.

Step 13 - Subscribe demo subject demo.eclipse.[your_name]

After call ipushTCPConnect(), you need to check the return value (value of connId). If connection built successfully, connId will be greater than zero. Otherwise, connId will be less than zero.

In this example, the client will show message "Connect OK!" in the console view when connId is greater than zero and then subscribe a demo subject immediately by calling ipushSubSubject() method. Arguments needed:

1. Connection ID: Connection ID of this client; connId used here.
2. Subject Name: Subject name to be subscribed; demo.eclipse.[your_name] used here.

[your_name] represents your name or any string you assigned without any space.

Why you need to use your name to in a subscribed subject? It can avoid collision of subject using. Since other developers who see this article may try this example too, so attach your own name to the subject root demo.eclipse will reduce the opportunity of receiving messages sent by others. In this example, tonyhsiao is the name used by author.

if (connId > 0) {      System.out.println("Connect OK!");      ip1.ipushSubSubject(connId,"demo.eclipse.tonyhsiao"); }

Figure 20. subscribe a subject with your name for receiving messages

Step 14 - Quick Fix helps to add the try/catch codes

A red line shown beneath the method ipushSubSubject() indicates something wrong there. Click the icon of quick fixable error on the left and select [Surround with try/catch], Eclipse will help to add the try/catch codes.

Figure 21. the icon of quick fixable error on the left indicates there is an error in the line

try {      ip1.ipushSubSubject(connId,"demo.eclipse.tonyhsiao"); } catch (iPush2Exception e) {      e.printStackTrace(); }

Figure 22. Quick Fix helps to add the try/catch codes

Step 15 - Show an error message if connects to iPush Server failed

If the value of connId is less than zero, we want the client to show an error message for knowing the failure of connecting to iPush Server.

Please refer to the status code pages in iPush V2 Java API Programming Guide (file name: iPushV2_PG_Java_v2.x.x.pdf) to learn the meaning of each return code.

else {         System.out.println("Connect Fail!! " + connId); }

Figure 23. show an error message if connects to iPush Server failed

Step 16 - show the message received from iPush Server

When a message is received, the callback method onSubjectMessage() will be invoked. Use System.out.println() to show the subject name and content of the message in the console view.

The arguments of the onSubjectMessage() used here:

• arg1: Subject name of the received message.
• arg3: Content of the received message, it is stored in a byte array.
• arg4: Length of the received message (in byte).

So String(arg3, 0, arg4) will return the text string of the message content.

System.out.println("Subject = " + arg1 + ", Data = " + new String(arg3, 0, arg4));

Figure 24. show the subject name and content of the received message in onSubjectMessage()

Step 17 - Create an instance of class iPushDemo in main()

Finally, create an instance of class iPushDemo in main() to complete this iPush client example.

new iPushDemo();

Figure 25. new an instance of class iPushDemo

Run-time Experience 1 - Run As a Java Application

Does it really work? Just run to try it.

Select [Run] / [Run As] / [Java Application] to run this example.

It will show Connect OK! in the Console view if connected to iPush Server successfully. Otherwise you have to check your network status or information provided in Step 12 to find out why connection failure.

Figure 26. Run the example as a Java Application

Figure 27. in Console view, Connect OK! will be shown if connected to iPush Server successfully

Now the client has subscribed subject demo.eclipse.[your_name] and is ready for receiving messages pushed from iPush Server.

Run-time Experience 2 - Run iPush2JavaSubjectSample As Message Sender

We are going to use the sample program - iPush2JavaSubjectSample (which is shipped with the iPush V2 client Java Package) to send messages into iPush Server.

The Java source code is located in the subfolder Samples\iPush2JavaSubjectSample of iPush V2 Java Package API, please compile and run it with your J2SDK environment.

Note: you may modify the related file paths in make.bat and run.bat (in the same subfolder) for compiling and running iPush2JavaSubjectSample correctly.

Once iPush2JavaSubjectSample runs, fill in information for connecting to iPush Server:

1. Server: www.icetechnology.com
2. Port: 8000
3. Company: ICE
4. Product: iPush
5. Username: eclipse
6. Password: eclipse

Figure 28. run iPush2JavaSubjectSample as message sender

Click [Connect TCP] button.

After connected, the status text Connect to server [www.icetechnology.com] with Connection ID [x] will be shown.

Let's send a message via subject named demo.eclipse.[your_name].

(a) Type demo.eclipse.[your_name] in the Subject field. It must be the same subject name subscribed in Step 13.

(b) Type Hello, world! in the Message field.

(c) Click [Send subject msg] button to send the message to iPush Server.

Figure 29. send Hello, world! to iPush Server with subject demo.eclipse.[your_name]

The status text Sent: Hello world! will be shown.

Run-time Experience 3 - Check the Received Message in Eclipse

Check the Console view of Eclipse, it should show Subject = demo.eclipse.[your_name], Data = Hello world!.

Yes, your example does work.

Figure 30. Subject = demo.eclipse.[your_name], Data = Hello world! shown in the Console view of Eclipse

This example client is ready to receive more messages from iPush Server. You may improve it by yourself. Click [Terminate] tool button on Console view of Eclipse to stop the program.

Figure 31. terminate the running of example client

Improvement Edition - Auto-reply Robot

Let's go back to Java editor of Eclipse, in the method OnSubjectMessage(), has ipl send a (non-persistent) message Hello world, too! back via subject demo.eclipse.[your_name]_reply on receiving messages.

Here we use the method ipushSendNPSubjectData() to send the replied message to iPush Server, arguments used:

• arg0: Connection ID.
• arg1: Subject to send to; "demo.eclipse.[your_name]_reply" used here.
• arg2: Content of the message to be sent; "Hello world, too!" used here.
• arg3: Priority of the message; 5 used here.
• arg4: QoS level of the message; 0 used here.

ip1.ipushSendNPSubjectData(connId, "demo.eclipse.tonyhsiao_reply", "Hello world, too!", (byte)5, (byte)0);

Figure 32. add the auto-reply robot

Again, a quick fixable error occurs on the left of the method ipushSendNPSubjectData(), click the icon and select [Surround with try/catch] to fix it.

Figure 33. click the quick fixable error icon

try {      ip1.ipushSendNPSubjectData(connId, "demo.eclipse.tonyhsiao_reply", "Hello world, too!", (byte)5, (byte)0); } catch (iPush2Exception e) {      e.printStackTrace(); }

Figure 34. Quick Fix helps to add the try/catch codes

Run-time Experience 4 - Bi-directional communication

Let's  run to try it again.

(a) In Eclipse, select [Run] / [Run As] / [Java Application]. Connect OK! should show in the Console view.

(b) Switch to iPush2JavaSubjectSample window if it still opened.

(c) Type demo.eclipse.[your_name]_reply in Subject field. It must be the same subject name subscribed in section Improvement Edition - Auto-reply Robot.

(d) Click [Subscribe subject] button to subscribe the subject.

You'll see the status text shown:

Subject subscribed [demo.eclipse.[your_name]_reply]
iPush[1]:Subject Command OK (700-demo.eclipse.[your_name]_reply)

Figure 35. subscribe subject demo.eclipse.[your_name]_reply in iPush2JavaSubjectSample

(e) Type demo.eclipse.[your_name] in Subject field of iPush2JavaSubjectSample window. It must be the same subject name subscribed in Step 13.

(f) Click [Send subject msg] button to send the message Hello world!.

Figure 36. send the message Hello world! again

(g) You'll see Hello world! in Console view of Eclipse and Hello world, too! in the iPush2JavaSubjectSample window. Your example client now can receive and reply messages via iPush Server. This illustrates the bi-directional communication capability of iPush application.

Figure 37. bi-directional communication capability of iPush application

Conclusion - Easy to develop iPush application with Eclipse

From this example, we have shown you how simple and quick iPush application development is. You can create a real-time Java application or applet with Eclipse and iPush V2 Java Package API in minutes too.