EdgeBuilder SDK
Getting Started

03 August 2006

After you install the EdgeBuilder SDK, use this document to setup your system for EdgeClick application development, and deploy the sample EdgeClick applications included with the SDK.

It is assumed that the reader has at least a basic knowledge of Java development, and the components used in mobile services. For a reference of links to Java Programming topics, including Java SE and Java ME programming, see the Learning Java Resources web page. A functional overview of the components of EdgeClick is contained in the Development Overview.

Installing Additional Development Tools

Before you can begin service and mobile client development, you'll need to download and install additional software development tools not included in the EdgeBuilder SDK (due to licensing restrictions or size considerations):

For EdgeClick Service development, the Eclipse IDE is recommended.
The choice of software for mobile client development depends on the development environment you choose for the mobile devices you'll be using in your EdgeClick application.
If your EdgeClick solution includes agents, then you'll likely also use the development environments already in place on the systems that contain the data and applications that need to communicate with the mobile clients.

Service Development -- Eclipse

The popular Eclipse Integrated Development Environment (IDE) is used for EdgeClick service development and deployment. For a tutorial on installing and using it, see Appendix A.

Java ME Client Development -- NetBeans

The Sun NetBeans 5.0 Integrated Development Environment (IDE) plus the NetBeans 5.0 Mobility Pack is the basic environment for developing Java ME programs. NetBeans provides a Java SE implementation, a Java source editor, a build environment, a packaging environment, a phone simulator, and a network monitor. The mobility pack adds the Java ME implementation. See the section Build the Java ME Hello Client, below, for a tutorial on using the NetBeans IDE to build a sample client.

.NET 2.0 Client Development -- Visual Studio

Microsoft Visual Studio (Standard Edition or higher) and the Windows Mobile 5.0 Pocket PC SDK are required to develop applications for Windows Mobile phones. See the section Building and Testing the .NET Hello Client, below, for a tutorial on installing and using Visual Studio to build and test a sample client.

Optional Tools

The Cygwin environment is useful for those who are used to a UNIX bash shell environment, with familiar UNIX utilities. It's available from http://www.cygwin.com.

Starting and Stopping the EdgeClick Processor

The EdgeClick Processor (ECP) is what runs the services that will be requested from EdgeClick Mobile clients. The ECP must be running in order to deploy and test the sample EdgeClick Processor Services and Clients included with the SDK.

After installing the SDK, you can start the ECP using the Windows Start menu at Start-»All Programs-»EdgeBuilder. To start the ECP, select:

Start-»All Programs-»EdgeBuilder-»EdgeClick Processor Start

This starts the EdgeBuilder Apache, MySQL and JBoss services in the proper order. A Command Window entitled EdgeClick Processor Start displays the server log messages. A successful startup is indicated by a line like the following:

13:15:24,390 INFO  [Server] JBoss (MX MicroKernel) [4.0.4.GA (build:
 CVSTag=JBoss_4_0_4_GA date=200603311500)] Started in 32s:78ms

The EdgeClick window is designed to remain open while the ECP is running and displays the server log messages. Do not close this window or the ECP will stop. Once the ECP is up, services can be managed (deployed, redeployed, removed) without restarting the ECP. You can now, for example, use the HelloService to test it, as shown in the section Sample Services - HelloService, below.

Once you are finished with EdgeClick development, stop the ECP by selecting:

Start-»All Programs-»EdgeBuilder-»EdgeClick Processor Stop

An EdgeClick Processor Stop window opens to display shutdown messages as each compoent of EdgeClick is stopped. The EdgeClick Processor Start window also displays log messages as the ECP is shutdown. Once shutdown is complete, both windows display the prompt: Press any key to continue...; the windows close when you press a key.

Sample Solutions Overview

The following sample services and clients are provided with the EdgeBuilder SDK:

Service	Description	Java ME Client	.NET 2.0 Client
HelloService	Send email/SMS to subscriber's client	Yes	Yes
MIGs	Define and report progress on goals	No	Yes
Meter	Remote meter reading data collection	Yes	No

Note that the HelloService and MIGs solutions are buildable and deployable on the development EdgeClick Processor provided with the EdgeBuilder SDK. The Meter solution is an example of a solution that uses an agent, and so cannot be deployed entirely on the development machine. See the subsections that follow for these services.

Sample Solutions -- Hello Service and Clients

The HelloService is a simple sample service with two purposes: it lets you confirm that installation of EdgeBuilder and its enclosed EdgeClick Processor has been successful, and it serves as a basic example of how to code EdgeClick mobile clients and services.

In the instructions below, %EC_HOME% refers to the directory under which you installed EdgeBuilder (by default, C:\EdgeBuilder); the %EC_HOME% environment variable was set during installation.

Building and Deploying HelloService

The ECP must be running in order to deploy the HelloService on it. See the section Starting and Stopping the EdgeClick Processor.

The HelloService source code is installed under %EC_HOME%\sdk\service\samples\HelloService. The quickest way to build and deploy the sample HelloService is to use Ant from the command line:

Open the Windows Command utility (or a UNIX bash shell if you have a Cygwin environment installed).
cd %EC_HOME%\sdk\service\samples\HelloService

ant clean

Buildfile: build.xml

clean:

BUILD SUCCESSFUL
Total time: 1 second

ant deploy

Buildfile: build.xml

init:
    [mkdir] Created dir: C:\Edgebuilder\sdk\service\samples\HelloService\bin
    [mkdir] Created dir: C:\Edgebuilder\sdk\service\samples\HelloService\dist

all:
    [javac] Compiling 1 source file to C:\Edgebuilder\sdk\service\samples\HelloS
ervice\bin

jar:
      [jar] Building jar: C:\Edgebuilder\sdk\service\samples\HelloService\dist\e
dgeclick-service-hello.jar

ear:
      [ear] Building ear: C:\Edgebuilder\sdk\service\samples\HelloService\dist\e
dgeclick-service-hello.ear

deploy:
     [copy] Copying 1 file to C:\EdgeBuilder\ecp\components\jboss-4.0.4.GA\serv
er\default\deploy

BUILD SUCCESSFUL
Total time: 6 seconds

The Ant binary should be in your PATH after EdgeBuilder installation. If not, you can type %EC_HOME%\sdk\devtools\apache-ant-1.6.5\bin\ant. The deploy task will copy over the built EAR file into the JBoss deploy directory to register it with the EdgeClick Processor. You can verify the HelloService is deployed by watching the EdgeClick Processor Start command console window that was created when you started the ECP.

During development of a service, building and deploying a service is usually done from within Eclipse. For a tutorial that shows you how to build, deploy, edit, and redeploy a service using Eclipse, see Appendix A.

.NET 2.0 Client Development Requirements

EdgeClick .NET 2.0 client applications are developed using Microsoft Visual Studio 2005, and are supported on phones that run either Windows Mobile 5.0 for Pocket PC, or Windows Mobile for Pocket PC 2003. Phones running two other Windows Mobile variants, Windows Mobile 5.0 Smartphone and Windows CE 5.0, do not support EdgeClick client applications.

Use the Start-»Control Panel-»Add or Remove Programs command to see if any of the components below are already installed.

Install Microsoft Visual Studio 2005, with (at least) the C# language enabled. This software is available from Microsoft; please see: http://msdn.microsoft.com/vstudio/default.aspx. You can install any version except the free Express version, which does not support Windows Mobile development.
Install ActiveSync 4.2 from http://www.microsoft.com/windowsmobile/downloads/activesync42.mspx
Install the Windows Mobile 5.0 Pocket PC SDK from http://www.microsoft.com/downloads/details.aspx?familyid=83A52AF2-F524-4EC5-9155-717CBE5D25ED.
Install the Virtual Machine Network Driver from http://www.microsoft.com/downloads/details.aspx?FamilyID=dc8332d6-565f-4a57-be8c-1d4718d3af65. (Note: this driver is required to test .NET clients using a mobile client emulator over a network connection. If you are testing on emulators using only ActiveSync connections over DMA, as described below in the client tutorials, then you do not need this driver.)
Install the .NET Compact Framework 2.0 Redistributable from http://www.microsoft.com/downloads/details.aspx?FamilyID=9655156b-356b-4a2c-857c-e62f50ae9a55.

For additional information on Windows Mobile development, see Microsoft's Mobile Developer Center.

Building the .NET Hello Client

Copy the folder named HelloServiceClient located in %EC_HOME%\sdk\client\DotNetCF2\Samples folder into a work folder, for example, into My Documents\Visual Studio 2005\Projects.

Run Visual Studio and build the application as follows:

From the Visual Studio main menu, select File-»Open-»Project/Solution....
Select the HelloServiceClient folder previously copied under My Documents\Visual Studio 2005\Projects.
Select the HelloServiceClient.sln file which is a Microsoft Visual Studio Solution file.
The first time the solution is opened, you need to add a reference to the common libraries. This step does not need to be performed on subsequent opens of the client.
1. Open the Solution Explorer tab (if not already open) by selecting View-»Solution Explorer
2. In the Solution Explorer tab, right-click on References and select Add Reference...
3. In the Add Reference window, select the Browse tab and select all the DLLs located in the %EC_HOME%\sdk\client\DotNetCF2\DotNetCF2 folder and press the OK button
Select the View-»Output menu command, so that you can see the build progress.
Select the Build-»Build Solution command from the Visual Studio menu. The build should complete without any error or warning, and "Build succeeded" should be displayed in the Status bar, as in this example:

Testing the .NET Hello Client

Now you can test the built client using the emulators available in Visual Studio. The emulator state and the account information you enter below are saved by default so that successive test runs do not require you to reconfigure the emulator or enter the account information again.

Choose an emulator:
1. From the Visual Studio main menu, select Tools-»Connect to Device...
2. In the Connect to Device dialog box, select the emulator of your choice and click the Connect button. We recommend the Windows Mobile 5.0 Pocket PC SDK emulators.
3. A Connecting... window opens, and then the selected emulator opens in another window.
  
  Wait until the Connecting... window displays Connection succeeded. Select Close.
Configure the emulator.
Note:If you previously entered this information and saved the emulator state when exiting the emulator (File-»Save State and Exit), then you do not need to perform this step again. The following instructions assume you are beginning with the default settings of the emulator. If you are not sure, you can reset the emulator by selecting File-»Reset-»Hard from the emulator window's main menu.

On the emulator screen within the emulator window:
1. Select Start-»Settings.
2. Select the Connections tab.
3. Double-click on the Connections icon.
4. Select the Advanced tab.
5. Press the Select Networks button.
6. Set both networks drop-list boxes to My Work Network
7. Do the following for both of the networks:
  1. Press the Edit... button.
  2. Select the Proxy Settings tab.
  3. Check the This network connects to the Internet box.
  4. Press the ok button in the top right corner.
8. Select ok to close the Network Management screen.
9. Select ok to close the Connections screen.
10. Select the Network Cards icon.
11. Make sure the My network card connects to: drop-down box is set to Work.
12. Press the ok button in the top right corner.
13. Close the Settings page by pressing X in the top right corner.
Establish the emulator's ActiveSync connection with Visual Studio. This step must be done each time the emulator is opened to test a client via a network connection.
1. Make sure that ActiveSync is running. Select Start-»All Programs-»Microsoft ActiveSync.
2. From the Microsoft ActiveSync main menu, select, File-»Connection Settings...
3. Check Allow connections to one of the following and select DMA from the drop down list. Select OK. Do not close the ActiveSync window; this window must remain open to make a connection with the emulator.
4. From the Visual Studio menu, select Tools-»Device Emulator Manager.
5. The emulator you selected above will have a green "play" icon next to it.
  
  Right-click on that emulator and select Cradle
  (If the emulator does not have the green "play" icon next to it, select Uncradle, then Cradle to reset the connection.)
6. ActiveSync will detect the emulator and a Synchronization Setup Wizard will appear. Press the Cancel button to establish a Guest partnership with the emulator. On subsequent uses, the Wizard is skipped.) Once Visual Studio and the emulator are configured, a connection icon appears next to the emulator's name in the Device Emulation Manager, as in this example:
To test the emulator's network connectivity:
1. In the emulator, select Start-»Internet Explorer.
2. Open any page, for example: http://www.google.com. The emulator should display the page. (If your network or system has a firewall, make sure that the firewall is configured to let the emulator access the network.)
To test that the connection to the ECP is working:
1. The ECP must be running, and the HelloService must be deployed on it. See the section Building and Deploying the HelloService.
2. Open the EdgeBuilder home page by typing the ECP's name; for example http://light.
3. Open the JBoss home page by typing http://light:8080.
4. Close Internet Explorer by selecting X in the top right corner.
To run and test the Hello client on the emulator:
1. In Visual Studio's main menu, select Debug-»Start Debugging.
2. Select the emulator you have been working with to deploy the application.
3. Select Deploy. The .NET assemblies will be deployed on the emulator. A progress indicator appears in the Visual Studio Status bar while the deployment progresses. Note that the process can take several minutes, depending upon the memory available. The Status bar displays "Deploy succeeded" when the assemblies are fully deployed on the emulator.
4. After the assemblies are deployed, it will take another few seconds for the Account Edit form to be displayed on the emulator screen. Fill the form as follows:
  1. In the Community field, type the name of the ECP machine e.g., light.
  2. In Domain, type :8080
  3. Enter EdgeClickAdmin for the User Name.
  4. Select Password is not Set to display the password form.
  5. Enter the password on the Password form.
  6. Select OK on the bottom right to get back to the Account form.
  7. Select Save to authenticate the account.
5. Upon successful authentication, a Success window is displayed by the emulator:
  
  Select OK and the HelloService Main form is launched.
6. Select via SMS or e-mail and then Send. An SMS alert will be sent to the cell phone number specified in the account database; if there is no carrier defined for the User name you used, then a blank email with the Subject "Hello!" is sent to the email address defined for that User. A Sending SMS box appears, followed by this screen:
7. Now, go back to the Visual Studio window and examine the Hello Client source. Using the Debug-»Windows command to view the different components of the running application, as in this example:
On subsequent runs, the Accounts manager will remember your settings and take you directly to the application, and you will have fewer steps than shown here.
Once you are done testing the client, select Debug-»Stop debugging to stop the hello client. You can now close the emulator and the Device Emulator Manager.
To browse the source code for the client, use the Package Explorer to open the .cs files in the source, by right-clicking on the .cs file and selecting Open. For source files that define forms, a graphic designer tool is provided. To see the source code for the form, select View-»Code. Additional windows can be opened from the View menu. In this example screen, the file MainForm.cs is being edited; which defines the HelloService Main form for the client. When the cursor is placed in a function in the file, the Code Definition Window shows the function definition.

As you examine the source code, note that the main purpose of the client code is to display a form on the mobile client and exchange messages with the ECP. All other processing is performed on the ECP, including: accessing the Accounts database, authorizing access, constructing and sending the SMS or email.
As an example of how easy it is to update the sample source files using Visual Studio, follow these steps to add a logo to the hello client main form:
1. In the Solution Explorer window, right-click on MainForm.cs and select Open. A graphical editing interface displays the form defined in MainForm.cs.
2. Select View-»Properties Window from the menu to open the Properties window.
3. Click on the Toolbox at the left of Visual Studio, and select the Picture Box tool. Click on the emulator screen to draw a box with a size of 126,71 (as shown in the Properties window).
4. In the Properties window, click on Image. Click on the ... button that appears at right to select the file %EC_HOME%\www\eb.bmp; select Open. The EdgeBuilder logo should appear in the Picture Box.
5. Rearrange the elements on the screen so they look like the following screen:
6. Right click on the MainForm.cs tab and select Save MainForm.cs.
7. Select the Build-»Build Solution command from the Visual Studio menu. The build should complete without any error or warning, and "Build succeeded" should be displayed in the Status bar.
8. In Visual Studio's main menu, select Debug-»Start Debugging.
9. Highlight the emulator you have been working with to deploy the application. Select Deploy.
10. Since you already authenticated when testing the original client, you don't need to authenticate again. The Hello client main form should be displayed with the new icon:
11. Once you are done testing the client, select Debug-»Stop debugging to stop the hello client. You can now close the emulator and the Device Emulator Manager. Select File-»Exit to close Visual Studio.

For a look at the HelloService code that runs on the ECP, see Appendix A.

See the Visual Studio Help menu for more information on using Visual Studio.

Deploying the .NET Hello Client

For a tutorial on using Visual Studio to package the client and deploy it on a smart phone, see Deploying an EdgeClick .NET Client Application.

Starting a New .NET Client Using the EdgeClick VS Template

EdgeBuilder provides a Visual Studio C# template in the file %EC_HOME%\sdk\client\DotNetCF2\EdgeClickClient.zip. This template automates preparation of a new project, including adding references to the proper assemblies and defining a basic user interface form for the client.

To use the template:

Copy the file %EC_HOME%\sdk\client\DotNetCF2\EdgeClickClient.zip to the \Visual Studio 2005\Templates\Project Templates\Visual C# directory using Windows Explorer. Do not unzip the file.
Open Visual Studio and select the File-»New-»Project... command from the menu. The EdgeClick template can be found under Visual C#, as shown in the following screen:
Enter approrpiate names and locations at the bottom of the screen and select OK. The project is loaded into Visual Studio.
Select Build-»Build Solution to build the template. The following shows what the screen should look like after a successful build.
The following screen shows the basic form included in the template displayed when you edit the frmMain.cs file in Visual Studio.

You can experiment with changing the form, rebuilding, and then testing out your client on an emulator, as shown above for the .NET Hello client.

Building and Testing the Java ME Hello Client

To build the Java ME HelloService client requires the following software:

Java Development Kit (JDK) 5.0 Update 7
NetBeans 5.0 Integrated Development Environment (IDE)
NetBeans Mobility Pack 5.0

Note: The EdgeBuilder distribution includes NetBeans Version 5.5 Beta 2, which can be installed instead of the NetBeans Version 5.0 listed here.

An installer containing the JDK and NetBeans 5.0 is available on the Java SE Downloads website:

http://java.sun.com/javase/downloads/index.jsp

or they can be installed separately; see links on the above website.

The NetBeans Mobility Pack 5.0 is available from:

http://developers.sun.com/prodtech/javatools/mobility/downloads/index.jsp

If you install NetBeans 5.5 Beta 2, then you'll need to install the 5.5 version of the Mobility Pack instead of the 5.0 version. The 5.5 version is available from

http://www.netbeans.info/downloads/download.php?type=5.5b2:

You only need to download the NetBeans Mobility Pack from the above URL. Be sure to read the installation and release notes available from both of the download websites.

Note that while the Netbeans examples in this section use NetBeans 5.0, the same examples work on NetBeans 5.5 as well.

Building the Java ME Hello Client

To build the Java ME HelloService client:

Create a directory for your netbeans projects, such as C:\netbeans-apps.
Copy the directory %EC_HOME%\sdk\client\JavaME\samples\hello_ec. to the directory you created in Step 1.
Copy %EC_HOME%\sdk\client\JavaME\lib\edgeclick.jar. into C:\netbeans-apps\hello_ec\lib (overwrite any previous version there).
Copy %EC_HOME%\ecp\conf\ecp.properties into C:\netbeans-apps\hello_ec\res.
Open NetBeans:
Start-»All Programs-»NetBeans 5.0-»NetBeans IDE
From the NetBeans menu, select File-»New Project. Highlight Mobile and Import Wireless Tooklit Project. (If you don't see these selections, then you did not install the NetBeans Mobility Pack. See Building and Testing the Java ME Hello Client, above.)

Select the Next button.
Specify the WTK Location using the Browse button; in our example, we use C:\netbeans-apps\hello_ec.

Select Next.
Specify C:\dev as the Project Location and accept the defaults for the other fields. Make sure the Set as Main Project check box is enabled.

Select Finish. The NetBeans screen should now look like this:
From the NetBeans menu, select Build-»Build Main Project. An Output window should appear, with messages indicating a successful build, as in this example:

Testing the Java ME Hello Client

After completing the previous two sections successfully, do the following to run the Java ME Hello client:

From the NetBeans menu, select Run-»Run Main Project. A phone emulator window is displayed, labelled Default Color Phone. The application choice hello_ec should appear at the top of the emulator screen.
In order to test the client, the ECP must now be started or already running, with the HelloService deployed. See Building and Deploying the HelloService.
In the emulator, click the right-side button under Launch. The following screen should be displayed.
Click the button under Login at the bottom of the screen. The emulator sceen should now display the following:
The cursor should now be in the Community field, which should display the development system name (light in this example).
1. Use the down arrow key or Enter on the keyboard to move the cursor to Username. Enter the username you selected at install time (default: EdgeClickAdmin).
2. To set the password, use the down arrow then right arrow to highlight the Edit control, then click the Select button beneath the emulator screen. Type in the password (default: scoTest), then click under Back. The password should now show as set. Use the default values presented for everything else.
3. Click the button under Menu at the lower right of the emulator screen, highlight Save and Activate, and click the Select button.
The first time you do this, you will get a window asking if it is OK to use airtime. Click under Yes.
You should now get a screen saying that login is successful.
Click the left-side button under Back.
There are two types of hello greetings you can get, one via SMS to your real phone (which does not have to have EdgeClick installed on it, just the ability to receive SMS from an EdgeClick-known carrier; if it cannot, e-mail will be sent to you), one via a message displayed on this phone simulator.
Try one of the greetings out, by using the up and down arrows, then clicking the Select button beneath the emulator screen. This will bring you to a screen that confirms which type of greeting you want.
Click the button under Menu at the lower right of the emulator screen, highlight Send Request for Hello, and click the Select button.
For the SMS choice, you should get back a simple OK to this screen, and an SMS will be sent to your real phone (it may take a minute or two to arrive), and a screen indicating success is displayed. For the screen choice, you should get back the greeting addressed to you. If both of these choices work, EdgeBuilder is working properly.
Messages like the following should be displayed in the NetBeans Output window when the message is successfully sent:

Select the button under Back on the bottom left of the screen to return to the Main client screen.
When you are done testing the client, select Build»Stop Build/Run from the NetBeans menu to stop the application and close the emulator.

On subsequent runnings of the client, the Accounts manager will remember your settings and take you directly to the application, and you will have fewer steps than shown here.

Sample Solutions -- MIGs Service and Client

Like the HelloService, and unlike the Meter service, the MIGs sample service uses a Windows Mobile .NET C# client. MIGs (Most Important Goals) represents a sample .NET client application that uses the EdgeClick .NET assemblies and EdgeClick MIGs server running on the ECP to create, review, update, and view the goals established for and by a user.

Building and Deploying the MIGs Service

Create and initialize the MIGs database as follows:
1. If it is not started already, start the EdgeClick Processor on your development system using Start-»All Programs-»EdgeBuilder-»EdgeClick Processor Start. A window is opened titled EdgeClick Processor Start. If the ECP is already running, this window is already open on your desktop.
2. Open a Command window and enter the following commands:
  1. cd %EC_HOME%\sdk\service\samples\migs-service
  2. .\migs_init.bat
```
Initializing MIGs database.

c:\EdgeBuilder\sdk\service\samples\migs-service>C:\EdgeBuilder\ecp\components\mysql-5.0.22-win32\bin\mysql -u root  0<src\conf\db\mig_ddl.sql
```

Deploy the MIGs service on the ECP by entering the following commands:

ant deploy

Buildfile: build.xml

migs.init:
    [mkdir] Created dir: C:\EdgeBuilder\sdk\service\samples\migs-service\bin
    [mkdir] Created dir: C:\EdgeBuilder\sdk\service\samples\migs-service\dist

migs.compile:
    [javac] Compiling 3 source files to C:\EdgeBuilder\sdk\service\samples\migs-service\bin
    [javac] Note: C:\EdgeBuilder\sdk\service\samples\migs-service\src\java\com\sco\phoenix\services\migs\MigProcessor.java uses or overrides a deprecated API.
    [javac] Note: Recompile with -Xlint:deprecation for details.

migs.jar:
     [copy] Copying 1 file to C:\EdgeBuilder\sdk\service\samples\migs-service\bin\META-INF
     [copy] Copying 1 file to C:\EdgeBuilder\sdk\service\samples\migs-service\bin
      [jar] Building jar: C:\EdgeBuilder\sdk\service\samples\migs-service\dist\edgeclick-migs.jar

migs.ear:
      [ear] Building ear: C:\EdgeBuilder\sdk\service\samples\migs-service\dist\edgeclick-migs.ear

migs.deploy:
     [copy] Copying 1 file to C:\EdgeBuilder\ecp\components\jboss-4.0.4.GA\server\default\deploy

deploy:

BUILD SUCCESSFUL
Total time: 10 seconds

You can now test the deployed service via a web interface to confirm that it is working.
1. cd test
2. ant deploy
```
Buildfile: build.xml

MIGs.deploy:
     [copy] Copying 14 files to C:\EdgeBuilder\www\migs

deploy:

BUILD SUCCESSFUL
Total time: 2 seconds
```
You should now see the MIGs web interface (in any browser) at http://hostname/migs. This confirms that the service is working.

Overview of the MIGs Client

The .NET MIGs 1.0 is a sample EdgeClick client application. It demonstrates the classes and methods that allow a Windows Mobile application to authenticate and communicate with the EdgeClick processor, accessing the EdgeClick services. It utilizes a set of Microsoft .NET Compact Framework 2.0 assemblies that are deployed on Windows Mobile phones.

It consists of four Visual Studio projects:

MIGs - includes the C# files representing the forms and other Visual Studio file that make up the .NET MIGs client
MIGsSmartCAB - includes the files that represent the packaging of the MIGs client into a Cabinet (CAB) file.
CustomInstaller - includes the files for a MIGs custom installer to install the MIGs client on a Windows Mobile device.
Setup - includes the files to package the CAB file, custom installer and a setup.ini file into a setup.msi file, which is installed on the Windows Mobile phone by the Windows installer.

MIGs Client Build and Deploy Requirements

See the section .NET 2.0 Client Development Requirements, above, for the software you need to install to build and deploy the MIGs client.

Building the MIGs Client

Copy the folder named MIGs located in %EC_HOME%\sdk\client\DotNetCF2\Samples into a work folder, for example, into C:\Visual Studio 2005\Projects. Open Visual Studio, and build the MIGs application as follows:

File-»Open-»Project/Solution.
Select the MIGs project copied under C:\Visual Studio 2005\Projects.
Select MIGs.sln.

After the MIGs solution is open, in Solution Explorer:

Select the MIGs project and expand it.
Expand References and confirm that the EdgeClick assemblies are available. If they are marked as unavailable, then:
1. Remove the assembles by right-clicking on "References" and selecting Remove.
2. Right-click on References and select Add. Browse to select the assemblies located in %EC_HOME%\sdk\client\DotNetCF2\DotNetCF2. Select OK.
Select Build-»Build MIGs. The build should complete without any error or warning. Use the View-»Output comand to see the build output. The screen should look like this:

Testing the Application in Emulator Mode

To test the application using one of the phone emulators, you must first configure the emulator. Follow Steps 1 through 5 of the section Testing the .NET Hello Client.
In the Visual Studio top menu toolbar select: Debug-»Start Debugging
When the Device Emulator Manager appears, choose the emulator and select Deploy.

The .NET assemblies will be deployed on the emulator. A "wait wheel" appears on the emulator screen while the deployment progresses. Note that the process is a bit slow, depending upon the memory available.

On first running the application, an authentication form will be presented. (On subsequent runs, the form is not displayed, since the user is already authenticated.) Fill the form as follows:

In Community field, type the name of ECP machine e.g., light.
In Domain, type its domain followed by :8080; if there is no domain, then only type in :8080.
In App URL, type eps-1.0/epsmob.
Enter the valid User Name of a subscriber defined on the EdgeClick Processor. At least one subscriber was entered on installation, the default being EdgeClickAdmin.
Select Password is not Set to get to the password form.
Enter the subscriber password on the Password form; the default password for the default EdgeClickAdmin subscriber is scoTest.
Select OK on the bottom right to get back to the Account form.
Select Save to authenticate the account.

Upon successful authentication, the following screen is displayed:

select OK and the MIGs Main form will be launched.

Packaging the MIGs Client Application - MIGsSmartCAB Project

There are several good pages describing the Visual Studio 2005 application deployment procedure. For example: Create Setup Files for your Windows Mobile Applications Using Visual Studio 2005

To deploy MIGs to a device, a Cabinet (CAB) file needs to be created. The CAB file is expanded and installed on the device. The CAB file contains the application and all its dependencies and other files that need to be deployed with an application.

Building the MIGsSmartCAB Project

Open the MIGs solution in Visual Studio.
Select the MIGsSmartCAB project.
Select Detected Dependencies and refresh the dependencies, if needed.
Right-click and select Build.

A successful build of MIGsSmartCAB project creates the .CAB file in MIGsSmartCAB\Release.

Building the MIGs CustomInstaller Project

Open the MIGs solution in Visual Studio.
Select the CustomInstaller project.
Right-click and select Build.

A successful build of CustomInstaller project creates a CustomIntaller.dll file in CustomInstaller\bin\Release.

Building the MIGs Setup Project

Open the MIGs solution in Visual Studio.
Select the Setup project.
Right-click and select Build.

A successful build of Setup project creates a Setup.msi file in Setup\Release.

Testing MIGs on a Windows Mobile Phone

To test the program, make sure the system running the MIGs service is accessible from the Internet. Then, do the following:

Connect a Windows Mobile Phone to your system via ActiveSync.
Right-click on the Setup project in the Solution Explorer.
Select Install.

A Windows setup program will be initiated that will:

Install the .cab and .ini files on the desktop in %EC_HOME%\Program Files\EdgeClick\NetCF2MIGs.
Connect the phone to the desktop via the USB cable.
Launch ActiveSync to install the EdgeClick MIGs application on the phone.

Uninstalling the MIGs Application

To remove the MIGs application from your development machine, use the Windows Add/Remove Programs Manager from the Control Panel.

To remove the MIGs application from the mobile phone:

Connect the phone to the desktop via the USB cable.
Open ActiveSync and use the Tools-»Add/Remove Programs command to uninstall the client.

Sample Solutions - Meter Service, Client, and Agent

The Meter demo application is also included as a sample, including client, service, and agent components. A web admin component does not yet exist.

The Meter sample application is different from the other samples in the EdgeBuilder SDK because it contains an agent. The agent is NOT set up to run under EdgeBuilder. Thus, unlike the HelloService, this entire sample cannot be used for installation verification or for quick execution. Instead, this example is meant as an example for study, for developers writing their own EdgeClick applications that need agents. When you do start the process of building Meter, or an application like it, it should be built in "backwards" order: agent, then service, then client. The following sections describe this.

Building MeterAgent

The directory %EC_HOME%/sdk/agent/samples/MeterAgent/ contains an example agent for the Meter application. By their nature, agents are all different, as they integrate existing applications with the EdgeClick architecture. An agent may be written in any language to run on any operating system; the only requirement is that it use SOAP/XML-based web services to communicate with the EdgeClick Processor.

This sample MeterAgent is a very simple agent, that just takes incoming meter reading records from the Meter service and writes them out to a flat file on the agent's host system filesystem. Presumably an existing application would periodically read this flat file and process the records. The purpose of including this agent in the samples is to give a concrete example of what an agent might look like.

The MeterAgent is written in Java, to run under the Apache Tomcat application server and Apache Axis web services implementation. The agent's Java code is written to run under a UNIX operating system, and the make-agent build script is written to install the agent on a SCO UnixWare 7 or OpenServer 6 system. Both aspects can be adapted to other environments.

Building MeterService

The directory %EC_HOME%/sdk/service/samples/MeterService/ contains the service implementation for the Meter sample application.

Before the service can be built, some source code stub routines to handle the agent's web services must be generated. This is done by going to the src/java directory and editing the do-wsdl2java.bat script. Change the URL on the final command to wherever you deployed the agent. Then run the script by executing do-wsdl2java in a Windows command window. This will populate some source code in src/java/com/sco/agent.

Next, MeterService should be built and deployed in the EdgeClick Processor. Go back up to the MeterService directory, and execute "ant deploy" (or "ant redeploy" for iterative development) to build and deploy the service. Do not do "ant clean" first, as that will remove the stubs generated in the previous step.

Another difference between MeterService and HelloService, is that MeterService makes use of a local database on the EdgeClick Processor, whereas HelloService did not. This database needs to be created and initialized, which is done by going to the src/conf/db directory and running the load_meter.bat script.

MeterService is now fully deployed on the ECP.

Note that currently no web administration pages exist for maintaining the MeterService's two database tables. Thus, to add Billing Centers or Meter Readers, you must do manual database changes, by adding or modifying data in the Metertestdata.sql file in the above directory, and then rerunning the load_meter.bat script. As a consequence of this, you need to know the account number and subscriber number of the subscribers you are adding as Meter Readers. These can be determined by using the MySQL Query Browser and inspecting the tables meinc_hosted.account and meinc_hosted.subscriber.

Building the Meter Client

The directory %EC_HOME%/sdk/client/JavaME/samples/meter/ contains the Java ME client for the Meter sample application.

To use it, follow the same directions as for the hello_ec client for the sample HelloService, only in a meter project rather than the hello_ec project. See Build the Hello client.

Testing the Meter Application

Final testing of a fully built Meter sample, or applications like it, would be done from the WTK phone simulator. However, before getting to that point, it is useful to have some vehicles to do intermediate testing of internal interfaces. These are ONLY for the use of actual developers doing development work, not for regular users. Accordingly, in the MeterService/test directory, there are two such additional test vehicles.

The first, make-demo.bat with MeterAgentDemo.java, provides a standalone test of the Meter Agent from the EdgeBuilder system, without the complexities of running inside the EdgeClick Processor environment. All Agents should be tested in this manner, before attempting to contact them from the actual service.

The second, test_meter.html, is a so-called HTML Test Client. This is not a web browser-based UI for the Meter service (such a client would be constructed with AJAX technology), but rather a unit test vehicle for MeterService's functionality. Using this, you can simulate input to each different "command" in the service, and check the XML that is returned. It is often productive to test services in this manner, before attempting to contact them from the actual client, whether running on a phone simulator or an actual phone.

The EdgeClick Admin Site

After the ECP has fully started, the EdgeClick/MeInc web administration site can be opened by selecting:

Start-»All Programs-»EdgeBuilder-»EdgeClick Admin Site

This will bring up the admin site and allow you to login as the administrator and add subscribers and do other functions.

Updating the ECP Administrator Profile

The EdgeClick Administration Web Pages allow you to maintain the valid list of subscribers for your development ECP. The development ECP included with EdgeBuilder is limited to one account and 10 subscribers. (Note that while account creation in the web admin pages does work, attempts to log in to a newly created account via the web admin page or clients will always fail.)

At least one subscriber, the administrator, is defined at installation time. The installer prompts for an administrator login and password; if not provided, the defaults of EdgeClickAdmin and scoTest are used.

From the EdgeClick Admin Pages you can update the Administrator's profile, and define other subscribers and groups as test data for your application and service development.

To update the subscriber information for the ECP Adminstrator:

Select:
Start-»All Programs-»EdgeBuilder-»EdgeClick Admin Site
The EdgeClick Administration site opens in your default browser.
Select Account Login. The Login screen appears. Enter the user name and password you entered during installation of EdgeBuilder, or the default of EdgeClickAdmin and scoTest. Select OK.
Select the following links on successive screens: SuperUsersAccount-»Manage My Profile-»Update Subscriber Information
Update the information as needed. Note that for the HelloService, either an email address or a cell phone number and carrier must be provided. Click OK when you are done.
Click Log Out.

Appendix A: Using Eclipse to Build and Deploy a Service

Eclipse is the Integrated Development Environment (IDE) that you use to create, edit, build, and deploy EdgeClick Services. When performing the tasks in this section, the EdgeBuilder SDK should have already been installed.

Installing Eclipse 3.1.2 plus the JBoss IDE 1.6 Plug-in

You can either install Eclipse and the JBOSS plug-in separately, or install both at the same time.

To install both Eclipse and an already integrated JBOSS plug-in:

Open the following location in your browser:
http://www.jboss.com/products/jbosside/downloads
Download the archive.
Extract the archive into an appropriate directory (e.g., C:\download.
Open the downloaded .zip archive, and extract it to the C:\ directory; Eclipse will be installed under C:\eclipse.
Start Eclipse using the Eclipse Icon in C:\eclipse. The first time you start Eclipse, it will ask you to set your default workspace. Use the default location, or specify another; but, do NOT specify a directory under the EdgeBuilder installation directory. Once you set your workspace, the Welcome screen is displayed; close the Welcome screen to continue.
Select Run>>Debug to create a JBOSS deployment target.
Highlight JBoss 4.0.x and select New.
Call it JBoss 4.0.4GA and use the Browse button to set the Home Directory to %EC_HOME%\ecp\components\jboss-4.0.4.GA.
Select the default server configuration and Apply.
Select Close.
Go to the Eclipse Configuration Notes to finish configuring Eclipse.

To install only Eclipse on your development system:

Eclipse can be installed from the EdgeBuilder installer, or following the instructions below.

Open the following location in your browser:
http://www.eclipse.org/downloads/
Download the archive.
Extract the archive into an appropriate directory (e.g., C:\eclipse.
Go to the next procedure to install the JBOSS plugin.

To install the JBOSS plug-in into an already installed Eclipse:

Start Eclipse using the Eclipse Icon in C:\eclipse.
If not already done, set your default workspace; use the default location or specify another. Do NOT specify a directory under the EdgeBuilder installation directory. Then, close the Welcome Screen.
Select Help>>Software Updates>>Find and Install... from the Eclipse menu.
Select Search for new features to install, and then Next.
Select New Remote Site. Type in JBoss IDE Plugin for Name and http://download.jboss.org/jbosside/updates/stable for URL. Select OK.
Select Finish and you should now see under Click the features to install, the JBoss IDE Plugin with an open square.
Select the square and then Next.
Accept the License agreement and then select Next.
Make sure the JBoss Plugin is highlighted in the Features to install, and select Finish. Eclipse will now start downloading the JBoss IDE Plugin .jar files.
When the download is finished, select Install All to begin the installation.
After the installation completes, Eclipse will need to restart the workspace. Select OK.
When the workspace restarts, select Run>>Debug to create a JBOSS deployment target.
Highlight JBoss 4.0.x and select New.
Call it JBoss 4.0.4GA and use the Browse button to set the Home Directory to %EC_HOME%\ecp\components\jboss-4.0.4.GA.
Select the default server configuration and Apply.
Select Close.

Eclipse Configuration

Regardless of how you obtain Eclipse, make sure that the compiler compliance level is set properly and Ant is configured, as follows:

Start Eclipse using the Eclipse Icon in C:\eclipse.
If not already done, set your default workspace; use the default location or specify another. Do NOT specify a directory under the EdgeBuilder installation directory. Then, close the Welcome Screen.
Select Window>>Preferences from the Eclipse menu.
Open the Java folder, and then the Compiler folder.
Set Compiler compliance level to 5.0.
Select Apply. Select Yes when prompted for a
From the Preferences Window, select Window>>Preferences>>Ant>>Runtime>>Global Entries>>Add External Jars.
Use the Browse window to select the file C:\EdgeClick\sdk\devtools\apache-ant-1.6.5\lib\ant-contrib.jar.
Select Apply and then OK.
Select OK to close the Preferences window.
Select Window>>Show View>>Ant to display the Ant build window. This is where the build targets from the service's build.xml file are displayed.

Eclipse Tutorial

In this tutorial, you'll learn how to import one of the sample EdgeClick services included with the EdgeBuilder SDK, make a trivial change to the source code, build it, and deploy it within the running EdgeClick Processor on your development system.

Start Eclipse using the Eclipse Icon in C:\eclipse.
Select File>>Import....
Highlight Existing Projects into Workspace. Select Next.
Use the Browse button to select the root directory %EC_HOME%\sdk\samples\service\HelloService.

Select Finish to load the project.
Eclipse loads the project (HelloService) from the root directory, and it appears in the Eclipse Package Explorer window. Select the plus sign next to HelloService; Eclipse should now look like this:
In the Ant window, select the Add buildfiles button; expand the HelloService, highlight the build.xml file, and select OK. (Or, drag and drop the file build.xml from the Package Explorer window at the left, onto the Ant window at right.) This displays the build targets for the project, as shown in the following example. The list below is expanded to show all the targets:
The ear [default] target is the default target. Select the Run the Default Target of the Selected Buildfile button in the Ant window. The following messages should be displayed in the Console window at the bottom of Eclipse:

The Problems window at the bottom of Eclipse should show no errors. (If there are errors complaining about a compiler level mismatch, make sure you followed the notes in the section Eclipse configuration.)
To deploy the service we just built, first make sure the EdgeClick processor is running. If it is, there will be an EdgeClick Processor Start window open on your desktop. If it is not running, select Start>>All Programs>>EdgeBuilder>>EdgeClick Processor Start.
Highlight the deploy target and select Run the selected target. Eclipse will deploy the HelloService to the JBOSS deployment target JBoss 4.0.4GA created when the JBoss plugin was installed. The Eclipse Console should now look like this:

In the EdgeClick Processor Start window on your Desktop, the following messages indicate a succesful deployment:
```
15:55:46,609 INFO  [EARDeployer] Init J2EE application:
file:/C:/EdgeBuilder/ecp/components/jboss-4.0.4.GA/server/default/deploy/edgeclick-service-hello.ear
15:55:46,640 INFO  [EARDeployer] Started J2EE application: file:/C:/EdgeBuilder/ecp/components/jboss-4.0.4.GA/server/default/deploy/edgeclick-service-hello.ear
```
Now, we'll make a small change in the java code for the service, rebuild, and redeploy.
1. In the Package Explorer window, open the Java source file src/java>>com.sco.edgeclick.HelloService>>HelloProcessor.java. The source code for the file should now be dispayed in the editor window, as shown in the following example (the Ant and Console windows have been minimized in this example to show more of the source file):
2. Use the Edit>>Find/Replace comand to search for the string "Welcome to EdgeBuilder".
3. Add another line to the message, so that the file now looks like the screen below:
4. Close the file.
5. Restore the Ant and Console windows. In the Ant window, run the clean target; the screen should now look like this:
6. Now run the redeploy target to replace the previously deployed HelloService with the new one; the screen should now look like this:
  
  The EdgeClick Processor Start window should display messages indicated that the service was successfully deployed.
Select File>>Exit to close Eclipse. Your workspace is saved, and will be opened the next time you open Eclipse.

For each EdgeClick service you create, you'll probably want to define a top-level project within Eclipse, as in the procedure above. You can copy one of the sample services and alter the contents of the directories for your application.

At the top level of your Eclipse project, you will have a build.xml file that is in Ant format. You can model yours after the build.xml file in the sample application and do a global replace of your project name for the sample project name. Then, import the edited service as shown in the procedure above.

New source files can be created from within Eclipse, or using any method, and then imported into the project.

See the Eclipse documentation under the Help menu for complete instructions on using Eclipse. Also see the Eclipse web site at http://www.eclipse.org.

Appendix B: Building and Running the Java ME Client with the WTK

The source code for the Java ME client can be built with either NetBeans or the Java Wireless Toolkit (upon which NetBeans is based). The WTK is available at http://java.sun.com/products/sjwtoolkit/. Download the latest stable version (Sun developer program registration may be required). These instructions assume it was installed into C:\WTK22.

Build the WTK Hello Client

To build the HelloService client:

In Windows Explorer, open the directory %EC_HOME%\sdk\client\JavaME\samples\hello_ec. This is the source code for the HelloService client.
Copy the hello_ec directory (which is laid out for WTK) into C:\WTK22\apps, which is where WTK keeps its applications (known as "projects").
Find %EC_HOME%\sdk\client\JavaME\lib\edgeclick.jar. This is the EdgeClick client SDK library.
Copy edgeclick.jar into C:\WTK22\apps\hello_ec\lib (overwrite any previous version there).
Find \ecp\conf\ecp.properties. This is a properties file that is specific to your system and is created during EdgeBuilder install.
Copy that file into C:\WTK22\apps\hello_ec\res.
Start the WTK KToolbar environment:
Start-»All Programs-»J2ME Wireless Toolkit 2.2-»KToolbar
Within the WTK window, select Open Project. Select hello_ec and click the Open Project button. A message appears saying that the project has been loaded.
Press the Build button. You should get a "Build complete" message without any errors.

Run the WTK Hello Client

After completing the previous section successfully, do the following to run the HelloService:

Still in the WTK KToolbar environment, press the Run button. A phone simulator window is displayed, labelled Default Color Phone. The application choice hello_ec should appear at the top.
Click (the right-side button) under Launch. It should say that the Hello EC application requires activation.
Click under Login. You will get another screen back.
The cursor should now be under Community. Press Enter on the keyboard to move the cursor to Username.
Enter the username and password you selected at install time. To set the password, click the down arrow, the right arrow, and then on the Select button beneath the emulator screen. Type in the password, then click under Back. The password should now show as set under the prior screen. Use the default values presented for everything else.
Click the button under Menu at the lower right of the emulator screen, highlight Save and Activate, and click the Select button.
The first time you do this, you will get a window asking if you want to use airtime. Click under Yes.
You should now get a screen saying that login is successful.
Click (the left-side button) under Back.
There are two types of hello greetings you can get, one via SMS to your real phone (which does not have to have EdgeClick installed on it, just the ability to receive SMS from an EdgeClick-known carrier; if it cannot, e-mail will be sent to you), one via a message displayed on this phone simulator.
Try both types of greetings out, by using the up or down arrows, then Select. This will bring you to a screen that confirms which type of greeting you want.
Click under Menu, then Select Send Request for Hello.
For the SMS choice, you should get back a simple OK to this screen, and an SMS will be sent to your real phone (it may take a minute or two to arrive). For the screen choice, you should get back the greeting addressed to you.

If both of these choices work, EdgeBuilder is working properly.

On subsequent runs of the HelloService, the Accounts manager will remember your settings and take you directly to the application, and you will have fewer steps than shown here.