sensorweaver:developer-guide
Differences
This shows you the differences between two versions of the page.
| Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
| sensorweaver:developer-guide [2014-12-22 13:14] – [SensorWeaver Developer Guide] luigi.fortunati | sensorweaver:developer-guide [2015-11-10 16:46] (current) – [Testing your app] luigi.fortunati | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ===== SensorWeaver Developer Guide ===== | ===== SensorWeaver Developer Guide ===== | ||
| - | SensorWeaver is Java software. Middleware components are available as OSGi bundles available publicly in Maven repositories. | + | SensorWeaver is Java software. Middleware components are available as OSGi bundles, available publicly in Maven repositories. |
| + | This guide shows how to use SensorWeaver Middleware in your software projects. | ||
| General requirements: | General requirements: | ||
| * Knowledge of Java, OSGi, Maven. | * Knowledge of Java, OSGi, Maven. | ||
| - | * Java Development Kit 7 | + | * Java Development Kit 8 |
| - | * An IDE with Maven support | + | * An IDE, preferably |
| - | * For testing | + | * For testing/deployment |
| * An OSGi container for testing. [[http:// | * An OSGi container for testing. [[http:// | ||
| * A [[http:// | * A [[http:// | ||
| - | A project containing most of the examples shown in this guide can be downloaded at this [[http:// | + | A project containing most of the examples shown in this guide can be downloaded at this [[http:// |
| - | ==== Project and development | + | ==== Development |
| - | You'll need Java 7 JDK to compile and run your project. [[http:// | + | You'll need Java 8 JDK to compile and run your project. [[http:// |
| SensorWeaver components are distributed using Maven [[http:// | SensorWeaver components are distributed using Maven [[http:// | ||
| + | |||
| In order to access released and development JARs you need to configure your development environment. | In order to access released and development JARs you need to configure your development environment. | ||
| + | |||
| The best way to achieve this is to add third-party repos to your global maven // | The best way to achieve this is to add third-party repos to your global maven // | ||
| Line 24: | Line 27: | ||
| < | < | ||
| < | < | ||
| - | <id>default</id> | + | <id>wnlab</id> |
| < | < | ||
| < | < | ||
| Line 58: | Line 61: | ||
| </ | </ | ||
| </ | </ | ||
| + | < | ||
| + | < | ||
| + | </ | ||
| </ | </ | ||
| - | As an alternative, | + | As an alternative, |
| Maven repositories include documentation and source code artifacts. | Maven repositories include documentation and source code artifacts. | ||
| + | |||
| Source code can be accessed in read-only in [[http:// | Source code can be accessed in read-only in [[http:// | ||
| - | === Project setup === | + | ==== Project setup ==== |
| Create a Maven project using the IDE of choice. | Create a Maven project using the IDE of choice. | ||
| The project must generate an OSGi bundle, so: | The project must generate an OSGi bundle, so: | ||
| *Set packaging type to //bundle// | *Set packaging type to //bundle// | ||
| - | *Set Java 7 compiler with [[http:// | + | *Set Java compiler with [[http:// |
| *Include the [[http:// | *Include the [[http:// | ||
| Line 85: | Line 92: | ||
| < | < | ||
| < | < | ||
| - | < | + | < |
| - | < | + | < |
| </ | </ | ||
| </ | </ | ||
| Line 110: | Line 117: | ||
| **Tip**: You can find a list of manifest headers on the [[http:// | **Tip**: You can find a list of manifest headers on the [[http:// | ||
| - | Add the // | + | Then add the // |
| <file xml pom.xml> | <file xml pom.xml> | ||
| < | < | ||
| Line 116: | Line 123: | ||
| < | < | ||
| < | < | ||
| - | < | + | < |
| </ | </ | ||
| </ | </ | ||
| </ | </ | ||
| - | Tip: Check the latest // | + | Tip: Check the latest // |
| ==== Getting an instance of the Middleware service ==== | ==== Getting an instance of the Middleware service ==== | ||
| Inside of the OSGi runtime environment, | Inside of the OSGi runtime environment, | ||
| Line 127: | Line 134: | ||
| There are several ways to achieve this. Here we list two solutions: | There are several ways to achieve this. Here we list two solutions: | ||
| * Querying the service registry programmatically using // | * Querying the service registry programmatically using // | ||
| - | * Blueprint | + | * Blueprint |
| - | === Bundle Activator === | ||
| - | |||
| - | You'll need OSGi dependencies in your pom: | ||
| - | <file xml pom.xml> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | </ | ||
| - | |||
| - | Then create a java class for your bundle activator: | ||
| - | <file java MySensorPublisherActivator.java> | ||
| - | package it.cnr.isti.sample; | ||
| - | |||
| - | import it.cnr.isti.sensorweaver.middleware.api.Middleware; | ||
| - | |||
| - | import org.osgi.framework.BundleActivator; | ||
| - | import org.osgi.framework.BundleContext; | ||
| - | import org.osgi.framework.ServiceReference; | ||
| - | |||
| - | public class MySensorPublisherActivator implements BundleActivator { | ||
| - | |||
| - | private ServiceReference< | ||
| - | private MySensorPublisher publisher; | ||
| - | |||
| - | public void start(BundleContext context) throws Exception { | ||
| - | middlewareReference = context.getServiceReference(Middleware.class); | ||
| - | Middleware middleware = context.getService(middlewareReference); | ||
| - | // | ||
| - | publisher = new MySensorPublisher(middleware); | ||
| - | publisher.start(); | ||
| - | } | ||
| - | |||
| - | public void stop(BundleContext context) throws Exception { | ||
| - | publisher.stop(); | ||
| - | context.ungetService(middlewareReference); | ||
| - | } | ||
| - | |||
| - | } | ||
| - | </ | ||
| - | |||
| - | Declare your bundle activator in your Manifest by configuring the //maven bundle plugin//: | ||
| - | <file xml pom.xml> | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | < | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| - | </ | ||
| === Blueprint === | === Blueprint === | ||
| Line 220: | Line 170: | ||
| </ | </ | ||
| - | Assuming that you're following Maven conventions on project structure, create | + | Assuming that you're following Maven conventions on project structure, create |
| Create a '' | Create a '' | ||
| Line 230: | Line 180: | ||
| xsi: | xsi: | ||
| http:// | http:// | ||
| - | http:// | + | http:// |
| - | default-activation=" | + | |
| < | < | ||
| Line 243: | Line 192: | ||
| </ | </ | ||
| This configuration basically tells the blueprint runtime to | This configuration basically tells the blueprint runtime to | ||
| - | * create an instance of '' | + | * create an instance of '' |
| - | * call the method '' | + | * call the method '' |
| * call the method '' | * call the method '' | ||
| Line 250: | Line 199: | ||
| ==== API and usage ==== | ==== API and usage ==== | ||
| - | Middleware service methods executes asynchronous tasks when called. Whenever a method is called a '' | + | Middleware service methods executes asynchronous tasks when called. Whenever a method, is called a '' |
| This solution removes the need to implement callbacks for every method call, improving code readability. | This solution removes the need to implement callbacks for every method call, improving code readability. | ||
| The client can synchronize with the end of the middleware task by calling the '' | The client can synchronize with the end of the middleware task by calling the '' | ||
| Line 271: | Line 220: | ||
| * '' | * '' | ||
| - | * '' | + | * '' |
| * '' | * '' | ||
| Line 285: | Line 234: | ||
| import it.cnr.isti.sensorweaver.middleware.api.datafeed.descriptor.DataFeedDescriptor; | import it.cnr.isti.sensorweaver.middleware.api.datafeed.descriptor.DataFeedDescriptor; | ||
| import it.cnr.isti.sensorweaver.middleware.api.datafeed.descriptor.DataFeedBuilder; | import it.cnr.isti.sensorweaver.middleware.api.datafeed.descriptor.DataFeedBuilder; | ||
| + | import it.cnr.isti.sensorweaver.middleware.api.common.descriptor.Property; | ||
| /** ... **/ | /** ... **/ | ||
| Line 293: | Line 243: | ||
| builder.property(" | builder.property(" | ||
| builder.parameter(" | builder.parameter(" | ||
| - | builder.parameter(" | + | return |
| - | DataFeedDescriptor descriptor = builder.build(); | + | |
| - | return descriptor; | + | |
| } | } | ||
| </ | </ | ||
| Line 321: | Line 269: | ||
| MessageBuilder messageBuilder = dataFeedClient.buildMessage(); | MessageBuilder messageBuilder = dataFeedClient.buildMessage(); | ||
| messageBuilder.entry(" | messageBuilder.entry(" | ||
| - | messageBuilder.entry(" | + | messageBuilder.timestamp(Calendar.getInstance().getTimeInMillis()); |
| messageBuilder.send(); | messageBuilder.send(); | ||
| } | } | ||
| </ | </ | ||
| + | |||
| + | In order to publish a message for a given //data feed// you must produce values for all of the message elements defined previously in the //data feed descriptor// | ||
| + | |||
| + | The datafeed client includes a method // | ||
| === Unregistering a Data Feed === | === Unregistering a Data Feed === | ||
| Line 338: | Line 290: | ||
| === Discover Data Feeds === | === Discover Data Feeds === | ||
| In order to discover new //data feeds// you need to define a '' | In order to discover new //data feeds// you need to define a '' | ||
| - | |||
| <code java> | <code java> | ||
| Line 362: | Line 313: | ||
| </ | </ | ||
| The discoverer provides a filter which tells the Middleware about which data feeds the discoverer has to be notified on data feed lifecycle events. | The discoverer provides a filter which tells the Middleware about which data feeds the discoverer has to be notified on data feed lifecycle events. | ||
| + | The filter matches with announced data feed descriptors that have the same property values. | ||
| To activate a discoverer you must register it on the Middleware; | To activate a discoverer you must register it on the Middleware; | ||
| Line 376: | Line 328: | ||
| In order to start listening for a //data feed// the middleware client must provide a '' | In order to start listening for a //data feed// the middleware client must provide a '' | ||
| - | Each listener will listen to messages sent by a //data feed// | + | |
| + | Each listener will listen to messages sent by a specific | ||
| <code java> | <code java> | ||
| + | RegistrationToken registrationToken; | ||
| + | | ||
| + | /** ... **/ | ||
| + | | ||
| private void startListening(DataFeedDescriptor descriptor) throws InterruptedException, | private void startListening(DataFeedDescriptor descriptor) throws InterruptedException, | ||
| - | RegistrationToken registrationToken; | + | |
| - | registrationToken = middleware.registerListener(new LoggingListener(descriptor)).get(); | + | |
| - | listenerTokens.put(descriptor, | + | |
| } | } | ||
| - | private void stopListening(DataFeedDescriptor descriptor) throws InterruptedException, | + | private void stopListening() throws InterruptedException, |
| - | | + | registrationToken.unregister().get(); |
| - | if (registrationToken != null) registrationToken.unregister().get(); | + | |
| } | } | ||
| </ | </ | ||
| + | The same unregistration mechanisms of '' | ||
| + | |||
| + | ==== Testing your app ==== | ||
| + | |||
| + | Applications can be easily tested in the [[http:// | ||
| - | ==== Integration testing ==== | + | You can download your preferred Apache Karaf release (latest version is strongly recommended) and install the '' |
| - | Applications can be directly tested in Karaf OSGi environment using the middleware-dev | + | Deafult |
| + | Please refer to the [[sensorweaver: | ||
sensorweaver/developer-guide.1419254067.txt.gz · Last modified: 2014-12-22 13:14 by luigi.fortunati