Difference between revisions of "Northwind Tutorial"

From RifidiWiki

Jump to: navigation, search
(→‎Running the Application)
 
(164 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
This document provides step-by-step instructions on how to get started on developing your first application that runs on the Rifidi Edge Server. The application we will develop will use Esper to collect tag reads from a reader and put them on a JMS queue to be consumed by a client application.  Many of the steps are applicable to many kinds of plugins for the edge server, including [[How to create a sensor plugin| creating a sensor plugin]].
+
= '''WARNING: This document is for SDK 1.1.  For 1.2, please refer to the Northwind instructions documented in the Developer's PDF in the SDK''' =
−
=Prerequisites =
+
−
For this tutorial, we will use Eclipse to develop the application. While it would be possible to develop the application in any IDE that you are familiar with, Eclipse provides great tooling around OSGi application development and deployment, and thus makes this process much easier.  If this is your first time developing with eclipse, there will be a learning curve.  However, the payoff is worth it.  <br>
+
  
−
To get started see [[Edge Server Development Environment|Setting up a Development Environment]].
+
[[Developer's Guide]]
  
−
==Creating the new project==
+
This document provides step-by-step instructions on how to get started on developing your first application that runs on the Rifidi Edge Server.  The application we will develop will use Esper to collect tag reads from a reader and put them on a JMS queue to be consumed by a client application.  Many of the steps are applicable to many kinds of plugins for the edge server, including [[How to create a sensor plugin| creating a sensor plugin]].
−
First thing you need to do is to create a new OSGi bundle (aka plug-in) project using the wizard provided by eclipse.
+
=The Scenario: Northwind Shipping=
−
# Go to File-> New -> Project.  Select "Plug-in Project" from the file chooser. Click "Next."<br> [[Image:Tutorial-newwizard1.png|thumb|400px|none]]
+
Congratulations! You are the proud new founder of Northwind Shipping Inc. -- "delivering packages faster than a caffeinated lightning bug"&trade;. One of your core business strategies is to out perform your competitor -- Pony Express Shipping Inc. -- by capitalizing on increased efficiencies gained by your innovative use of technology.  You have heard all the hype about RFID and want to employ in it your new, state-of-the-art distribution center. You have decided to use the Rifidi Edge Server to run the RFID applications you will need in your distribution center.  This tutorial is a step-by-step guide on how to develop an RFID application and web UI using the Rifidi Edge Server API and deploy the application on the Rifidi Edge Server.
−
# Assign the project a name (I called mine "com.mycompany.rfid.app").  Make sure the plugin is targeted to run with the standard OSGi framework.  This makes sure that your plugin is general enough to be deployed in any OSGi runtime (felix, knoplerfish, etc). Click next.<br>[[Image:tutorial-newwizard2.png|thumb|400px|none]].
+
−
#Assign the plugin an ID, which is used to identify the bundle in the OSGi environment. Give it a descriptive name as well as the the name of the entity (company, person, project) that will maintain the bundle.  For this bundle, we will keep the Activator, although most of the time when you use spring DM (as we are), it is not necessary to have the activator.  Click Finish.<br>[[Image:tutorial-newwizard3.png|thumb|400px|none]]
+
  
−
=First Things First: Injecting Esper=
+
The Northwind distribution center has many complex processes, which should be automated as much as possible.  Because you are new to RFID (and because too many processes would overwhelm this tutorial ;-) ) you have decided to start small and only implement a basic process with a few business rules. The first process you will automate using RFID is the receiving process (DC-Inbound). You have a dock door which will be receiving incoming shipments from trucks.  The packages must be checked in at the dock door so that your ERP system knows the packages have arrived.  Once this happens, the packages must be moved to a separate staging area where it needs to be weighed and prepared for further routing.
−
What you will learn:
+
−
* Declaring OSGi bundle dependencies in the manifest
+
−
* Dependency injection via spring
+
−
* Running an OSGi application in eclipse
+
−
* Redeploying bundles without restarting the server
+
−
==Stating Dependencies in the Manifest==
+
  
−
{| cellspacing="5" align="right" style="margin: 1em auto 1em auto;background-color:rgb(240, 247, 255); width=100px;border:1px dashed; margin-left:10px; margin-top:10px; margin-bottom:10px"
+
There are several goals for the application
−
| align="center" width="350px"| '''ClassNotFoundException'''
+
* Track the packages from the dock door (stage 1) to the weigh station (stage 2).
−
|-
+
* Send an alert if a package moves backwards (from stage 2 to stage 1).
−
| width="350px"|Sometimes when running a bundle, you will get a ClassNotFoundException even though there were no compile-time errors in your source code. Many times, this is easily solved by adding the package of the problematic class to the import-package statement in the Manifest of your bundle.
+
* Send an alert if a package arrives at the weigh station but was not seen at the dock door
−
|}
+
* Send an alert if a package departs the dock door and is not seen at the weigh station within five minutes
  
−
An OSGi bundle is simply a jar with some extra information in the manifest.  Part of that information is the dependencies of the bundle.  There are two ways to state dependency information: bundle-dependencies, and package-dependencies.  A bundle dependency means that the bundle you are creating can see all of the exported package of the bundle that is depended on.  A package dependency means that some bundle in the OSGi runtime must export that package, but it doesn't matter which bundle.  Bundle dependencies are often simpler to state if you will use a large number of packages from the same bundle.  However, package dependencies are more flexible since the dependency can be met from any bundle.  They make alot of sense for things like javax or apache commons packages since you generally don't know or care exactly which bundle you will use.
+
==The Architecture==
 +
The solution that we will build will consist of two parts: the application bundle which will implement all the business rules, and the web application which will display the items.  The two pieces will communicate using JMS.   
  
−
In order to get Esper running, we will need to make two bundle-dependencies in the Manifest.
+
[[Image:Northwind.jpeg]]
−
#Open up the Manifest.MF file in the META-INF folder
+
−
#Click on the dependencies tab at the bottom of the editor.
+
−
#Click "Add" in the Required Plug-ins section.
+
−
#Add org.rifidi.edge.core.services and org.rifidi.com.espertech.esper.
+
−
#Save the changes.
+
−
[[Image:tutorial-manifest.png|thumb|none|400px]]
+
  
−
==Creating the Application==
+
=Prerequisites =
−
Now it's time to actually create the source code for the application.   
+
For this tutorial, we will use Eclipse to develop the application.  While it would be possible to develop the application in any IDE that you are familiar with, Eclipse provides great tooling around OSGi application development and deployment, and thus makes this process much easier.  If this is your first time developing with eclipse, there will be a learning curve.  However, the payoff is worth it. <br>
−
#Right-click on the 'com.mycompany.rfid.app' package and select New->Class
+
−
#Give the class a name.  I chose MyApplication. Click finish.
+
−
#Add a private member of type <tt>EsperManagementService</tt>.  Also make it volatile since the Spring thread will inject the reference (actually a dynamic-proxy) to the object.  The volatile keyword will prevent us from experiencing the [http://jeremymanson.blogspot.com/2008/11/what-volatile-means-in-java.html visibility problem] in java.
+
−
#Add a public setter method. to set the service.  This is the method that spring will call when it creates our object.
+
−
#Add a constructor. Add a printline in the constructor so we know when the object was started.
+
−
<pre>
+
−
/**
+
−
*
+
−
*/
+
−
package com.mycompany.rfid.app;
+
  
−
import org.rifidi.edge.core.services.esper.EsperManagementService;
+
To get started see [[Edge Server Development Environment|Setting up a Development Environment]].
−
 
+
=Source=
−
/**
+
You can download the source for this project here: [[Image:Northwind_1.0.0.zip]]. Just unzip the project, open up eclipse and select import->existing projects into workspace.
−
* @author Kyle Neumeier - kyle@pramari.com
+
−
*
+
−
*/
+
−
public class MyApplication {
+
−
+
−
/**Esper service*/
+
−
private volatile EsperManagementService esperService;
+
−
 
+
−
/**
+
−
* Constructor
+
−
*/
+
−
public MyApplication() {
+
−
System.out.println("HELLO RFID WORLD!");
+
−
}
+
−
 
+
−
/**
+
−
* Called by spring
+
−
* @param esperService
+
−
*/
+
−
public void setEsperService(EsperManagementService esperService) {
+
−
this.esperService = esperService;
+
−
}
+
−
}
+
−
 
+
−
</pre>
+
−
 
+
−
==Creating the Spring Context XML==
+
−
Next we need to create the spring context XML file.  Spring is an application development framework for java; it relieves the amount of boiler-plate code that is normally required when writing applications.  In addition, through spring dynamic modules, spring is integrated with OSGi to help start up bundles and access the OSGi service registry among other things.
+
−
 
+
−
Rifidi Edge Server applications should use spring to create objectes, register them as services if need be, and look up services from the OSGi service registry and inject them into their objects.  To create a spring context xml:
+
−
#Create a folder called 'spring' in the META-INF folder.  Spring will read any xml files in this folder in and use it when starting up the bundle.
+
−
#Create an xml file. By convention, I call mine spring.xml
+
−
#Copy and paste the following xml into the file.
+
−
<pre>
+
−
<beans xmlns="http://www.springframework.org/schema/beans"
+
−
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+
−
xmlns:osgi="http://www.springframework.org/schema/osgi"
+
−
xsi:schemaLocation="http://www.springframework.org/schema/beans
+
−
http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
+
−
    http://www.springframework.org/schema/osgi
+
−
    http://www.springframework.org/schema/osgi/spring-osgi.xsd">
+
−
 
+
−
<!-- Get a reference to the Esper Management Service from the OSGi Service Registry -->
+
−
<osgi:reference id="esperManagementService"
+
−
interface="org.rifidi.edge.core.services.esper.EsperManagementService" />
+
−
 
+
−
        <!-- Create the  Application bean and inject dependencies-->
+
−
<bean id="rfidapp" class="com.mycompany.rfid.app.MyApplication">
+
−
<property name="esperService" ref="esperManagementService" />
+
−
</bean>
+
−
 
+
−
 
+
−
</beans>
+
−
</pre>
+
−
 
+
−
The first <tt>beans</tt> tag gives the xml processor the location of the xsds that define the namespace information.  This allows us to use things like <tt>bean</tt> and <tt>osgi</tt> in the xml tags.  This makes for cleaner, easier to read files.
+
−
 
+
−
The <tt>osgi:reference</tt> tag tells spring to look up a service in the OSGi service registry which implements the <tt>org.rifidi.edge.core.services.esper.EsperManagementService</tt> interface.  Assign the object to id 'esperManagementService'. 
+
−
 
+
−
The second <tt>bean</tt> tag tells spring to instantiate an object of type <tt>com.mycompany.rfid.app.MyApplication</tt>.  In addition, we need to inject a bean that is referenced by the ID 'esperManagementService' (which we looked up in the previous tag). To set the service, use a setter method called "setEsperService" (set+<nameProperty>) which exists in the bean.
+
−
 
+
−
==Running the Application==
+
−
Now we are ready to run the application.  To do this, we need to modify the run configuration slightly in eclipse.
+
−
# Go to Run-> Run Configurations...
+
−
# Select the "Edge Server" run configuration under 'OSGi Framework'
+
−
# Select the Bundles tab.  You will see a list of bundles.  Each bundle that has a check mark by it will be installed and started when you run the application.  The bundles that serve as the 'core' Rifidi Edge Server have already been selected.
+
−
# Under 'Workspace', check the 'com.mycompany.rfid.app' bundle.<br>[[Image:Tutorial-RunConfiguration.png|thumb|400px|none]]
+
−
# Click "Apply". Click "Run".
+
−
 
+
−
Now you should see "HELLO RFID WORLD!" appear in the console, along with other debug information.
+
  
−
==Modifying and redeploying the Application==
+
=Outline=
−
=Event Stream Processing=
+
#[[Northwind Creating the Application | Step 1: Create the Application]]
−
What you will learn:
+
#[[Northwind Using Emulator | Step 2: Using Emulator]]
−
* Using Rifidi Emulator to speed up RFID development
+
#[[Northwind Esper: Track Packages| Step 3: Esper: Track Packages]]
−
* Writing Esper queries and listeners
+
#[[Northwind Esper: Alerts| Step 4: Esper: Alerts]]
−
=Sending out events with JMS=
+
#[[Northwind JMS Send | Step 5: Send Notifications Over JMS]]
−
What you will learn:
+
#[[Northwind Creating the Web Application | Step 6: Create the Web Application]]
−
* Importing the JMS services provided by Rifidi Edge Server
+
#[[Northwind Hello World Servlet | Step 7: Write a Hello World Servlet]]
−
* Sending out events over JMS
+
#[[Northwind TagLocationService | Step 8: Write a Tag Location Service and JMS Listener]]
−
=Exposing events with web services=
+
#[[Northwind Display Events using JSP: Step 9: Display events in a JSP]]
−
What you will learn
+
−
* Exporting a service with Web Services
+
−
=Control With RMI=
+
−
What you will learn:
+
−
* Providing an RMI interface for control of your application
+
−
* Creating an API bundle
+
−
* Creating a client application for your application
+
−
=Exporting the application=
+
−
What you will learn:
+
−
* Exporting your application out of eclipse
+
−
* Running the application in a deployed instance of Rifidi Edge Server
+

Latest revision as of 20:49, 8 December 2010

WARNING: This document is for SDK 1.1. For 1.2, please refer to the Northwind instructions documented in the Developer's PDF in the SDK

Developer's Guide

This document provides step-by-step instructions on how to get started on developing your first application that runs on the Rifidi Edge Server. The application we will develop will use Esper to collect tag reads from a reader and put them on a JMS queue to be consumed by a client application. Many of the steps are applicable to many kinds of plugins for the edge server, including creating a sensor plugin.

The Scenario: Northwind Shipping

Congratulations! You are the proud new founder of Northwind Shipping Inc. -- "delivering packages faster than a caffeinated lightning bug"™. One of your core business strategies is to out perform your competitor -- Pony Express Shipping Inc. -- by capitalizing on increased efficiencies gained by your innovative use of technology. You have heard all the hype about RFID and want to employ in it your new, state-of-the-art distribution center. You have decided to use the Rifidi Edge Server to run the RFID applications you will need in your distribution center. This tutorial is a step-by-step guide on how to develop an RFID application and web UI using the Rifidi Edge Server API and deploy the application on the Rifidi Edge Server.

The Northwind distribution center has many complex processes, which should be automated as much as possible. Because you are new to RFID (and because too many processes would overwhelm this tutorial ;-) ) you have decided to start small and only implement a basic process with a few business rules. The first process you will automate using RFID is the receiving process (DC-Inbound). You have a dock door which will be receiving incoming shipments from trucks. The packages must be checked in at the dock door so that your ERP system knows the packages have arrived. Once this happens, the packages must be moved to a separate staging area where it needs to be weighed and prepared for further routing.

There are several goals for the application

  • Track the packages from the dock door (stage 1) to the weigh station (stage 2).
  • Send an alert if a package moves backwards (from stage 2 to stage 1).
  • Send an alert if a package arrives at the weigh station but was not seen at the dock door
  • Send an alert if a package departs the dock door and is not seen at the weigh station within five minutes

The Architecture

The solution that we will build will consist of two parts: the application bundle which will implement all the business rules, and the web application which will display the items. The two pieces will communicate using JMS.

Northwind.jpeg

Prerequisites

For this tutorial, we will use Eclipse to develop the application. While it would be possible to develop the application in any IDE that you are familiar with, Eclipse provides great tooling around OSGi application development and deployment, and thus makes this process much easier. If this is your first time developing with eclipse, there will be a learning curve. However, the payoff is worth it.

To get started see Setting up a Development Environment.

Source

You can download the source for this project here: File:Northwind 1.0.0.zip. Just unzip the project, open up eclipse and select import->existing projects into workspace.

Outline

  1. Step 1: Create the Application
  2. Step 2: Using Emulator
  3. Step 3: Esper: Track Packages
  4. Step 4: Esper: Alerts
  5. Step 5: Send Notifications Over JMS
  6. Step 6: Create the Web Application
  7. Step 7: Write a Hello World Servlet
  8. Step 8: Write a Tag Location Service and JMS Listener
  9. Northwind Display Events using JSP: Step 9: Display events in a JSP
Retrieved from "http://wiki.rifidi.net/index.php?title=Northwind_Tutorial&oldid=3176"
Personal tools