Main.Documentation ReaderCoreProxy en 0 Main.Documentation xwiki:XWiki.nektarios xwiki:XWiki.yluo xwiki:XWiki.yluo 1233251820000 1276006923000 1276006923000 1.13 Reader Core Proxy 1 Reader Core Proxy ---- #toc("" "" "true") ---- 1.1 Introduction This section provides information regarding the deployment of the Reader Core components available at the [AspireRFID SVN branches|http://svn.forge.objectweb.org/cgi-bin/viewcvs.cgi/aspire/trunk/bundles/]. Before getting on with the deployment of the components, you could check the developers section which describes how to build the software from the source. 1.1 Users Guide The developed bundles implement the role of a EPCglobal RFID Reader Protocol (RP) v.1.1 compliant reader. That means we may take a non-RP compliant reader and by implementing a Java interface into an OSGI bundle, we could make the reader AspireRFID enabled. You can download the bundled package that contains Apache Felix with the required configuration and the OSGI bundles from [here>http://forge.objectweb.org/project/shownotes.php?release_id=2987] or you may proceed to manual deployment using the following instructions. You can start Felix with the following command (while being in the root directory of the installation) and set the profile name as &quot;core&quot; when asked. ~~java -jar bin/felix.jar~~ 1.1.1 Manual deployment To deploy the bundles you need first to get the latest version of [Apache Felix|http://felix.apache.org] and unzip the archive in a directory in which you have read/write access. Before starting the server, you need to edit its configuration file located under the conf folder. You need to add the following line somewhere in the file: ~~mosgi.jmxconsole.rmiport.core=9995~~ Then you may start the server: ~~java -jar bin/felix.jar~~ You will then be asked to enter a profile name; you should type in the word &quot;core&quot; (without the quotes) and press enter. Then the server starts and you will be prompted with the felix shell (>). You may type help to get a list of the available commands. Now you need to deploy some required bundles, which can be found at [the forge SVN|http://websvn.ow2.org/listing.php?repname=aspire/&path=/sandbox/nektarios/Common+bundles/AITdev+required+bundles/]. These are the following (note the sequence): # OSGi R4 Compendium Bundle # MOSGi JMX-MX4J Agent Service # MOSGi JMX rmiregistry # MOSGi JMX-MX4J RMI Connector # Apache Jakarta log4j Plug-in # OW2 Bundles :: Externals :: Commons Collections # castor # antlr-osgi # commons-logging-osgi # commons-lang-osgi # commons-configuration-osgi To deploy a bundle you will need the following command: ~~start file:&quot;full_bundle_location&quot;~~ where ~~full_bundle_location~~ is the location of the bundle on your disk. To *skip the manual deployment process*, you can download the {attach:config.aspire.properties} file and replace the original felix configuration file. Assuming that the required bundles exist in the {felix.home}\bundle directory, when you start felix, the bundles will be auto-deployed. You may then proceed in deploying the RP bundles in the same way. The RP bundles are the following.(Please note the sequence which is essential in order to avoid any problems): # JaxBLib # TDT Implementation bundle # Reader Protocol bundle (API) # Reader Protocol implementation bundle # Simulator reader # Intermec IF5 reader proxy 1.1.1 Configuration You may configure Reader core proxy using JMX. We have developed a plug-in for AspireID, the [JMX plugin>Main.Documentation.AspireIDE.PhysicalReaderConfiguration], which makes the underlying mechanics of configuration transparent to the user. You may find documentation regarding the use of the plug-in at the link above. Another way of configuration through JMX is via the JMX console, the jconsole tool, which is provided by the Sun Java JDK. You may connect to the server with the following command (assuming that felix is run at the local machine): ~~jconsole service:jmx:rmi:///jndi/rmi://localhost:9995/core~~ A graphical user interface should be displayed providing means of using the exposed JMX functionality. You may see the available functionality under the menu rfid->service->RPreader. For details regarding the available functionality please refer to the developers guide. 1.1 Developers Guide As it is said in the introduction, this component is based on the OSGi framework. Thus, it is composed by a number of bundles, each implementing a different kind of functionality. The TDT bundle is covered in the [Tag Data Translation>Main.Documentation.TDT] section. 1.1.1 Acquiring the code You can get the source code of the bundles through [Aspire SVN>http://forge.objectweb.org/plugins/scmsvn/index.php?group_id=324]. You should get all the source code under the path aspire/trunk/bundles/. The projects under bundles are build with maven and they can be imported to eclipse. 1.1.1 Component analysis The Reader Protocol bundle defines the API that is used by the implementation bundle. The reason we followed this strategy is to allow for other developers to implement their own implementations if such an alternative is required. The operations defined through the API are also the ones that are exported as management operations through JMX. The reader protocol implementation bundle is based on the codebase of [Fosstrak>http://www.fosstrak.org] reader project. This bundle is responsible for creating the JMX MBean and exporting it through MOSGI. Moreover, it maintains the configuration which can be updated through JMX. The bundle's jar initially contains a ReaderProtocol.xml file with a basic configuration. Every update that is made to the configuration is saved on an external configuration file that is saved under the user's home directory with the name ReaderProtocol.xml. The initial configuration is loads the RFID reader simulator implementation. If there is not such a configuration file under the user's home directory for some reason (e.g. initial deployment or deleted file) the default configuration is loaded. In order for the component to be of any use, a HAL implementation is required. The HAL implementation is the actual reader with which the proxy module communicates. Within this module the standard RP calls are translated into proprietary calls. Anyone who is interested in creating a bundle implementing the HAL should implement the following Java interface, which is located in the Reader protocol implementation bundle ~~org.ow2.aspirerfid.reader.rp.impl.hal.HardwareAbstraction~~ Then the implementation bundle should be deployed in the OSGI container and the implementation class should be identified in the RP configuration through JMX. <h2 class="heading-1"><span id="HReaderCoreProxy">Reader Core Proxy</span></h2><p class="paragraph"/> <hr class="line"/> <ul> <li><a href="#HIntroduction">1 Introduction</a> <li><a href="#HUsersGuide">2 Users Guide</a> <ul> <li><a href="#HManualdeployment">2.1 Manual deployment</a> <li><a href="#HConfiguration">2.2 Configuration</a> </ul> <li><a href="#HDevelopersGuide">3 Developers Guide</a> <ul> <li><a href="#HAcquiringthecode">3.1 Acquiring the code</a> <li><a href="#HComponentanalysis">3.2 Component analysis</a> </ul></ul> <hr class="line"/> <h3 class="heading-1-1"><span id="HIntroduction">Introduction</span></h3><p class="paragraph"/> This section provides information regarding the deployment of the Reader Core components available at the <span class="wikiexternallink"><a href="http://svn.forge.objectweb.org/cgi-bin/viewcvs.cgi/aspire/trunk/bundles/">&#65;spireRFID SVN branches</a></span>. Before getting on with the deployment of the components, you could check the developers section which describes how to build the software from the source. <h3 class="heading-1-1"><span id="HUsersGuide">Users Guide</span></h3><p class="paragraph"/> The developed bundles implement the role of a EPCglobal RFID Reader Protocol (RP) v.1.1 compliant reader. That means we may take a non-RP compliant reader and by implementing a Java interface into an OSGI bundle, we could make the reader AspireRFID enabled.<p class="paragraph"/> You can download the bundled package that contains Apache Felix with the required configuration and the OSGI bundles from <span class="wikiexternallink"><a href="http://forge.objectweb.org/project/shownotes.php?release_id=2987">&#104;ere</a></span> or you may proceed to manual deployment using the following instructions.<p class="paragraph"/> You can start Felix with the following command (while being in the root directory of the installation) and set the profile name as &quot;core&quot; when asked. <i class="italic">java -jar bin/felix.jar</i> <h4 class="heading-1-1-1"><span id="HManualdeployment">Manual deployment</span></h4><p class="paragraph"/> To deploy the bundles you need first to get the latest version of <span class="wikiexternallink"><a href="http://felix.apache.org">&#65;pache Felix</a></span> and unzip the archive in a directory in which you have read/write access. Before starting the server, you need to edit its configuration file located under the conf folder. You need to add the following line somewhere in the file:<p class="paragraph"/> <i class="italic">mosgi.jmxconsole.rmiport.core=9995</i><p class="paragraph"/> Then you may start the server:<p class="paragraph"/> <i class="italic">java -jar bin/felix.jar</i><p class="paragraph"/> You will then be asked to enter a profile name; you should type in the word &quot;core&quot; (without the quotes) and press enter. Then the server starts and you will be prompted with the felix shell (>). You may type help to get a list of the available commands.<p class="paragraph"/> Now you need to deploy some required bundles, which can be found at <span class="wikiexternallink"><a href="http://websvn.ow2.org/listing.php?repname=aspire/&path=/sandbox/nektarios/Common+bundles/AITdev+required+bundles/">&#116;he forge SVN</a></span>.<p class="paragraph"/> These are the following (note the sequence): <ol><li>OSGi R4 Compendium Bundle</li> <li>MOSGi JMX-MX4J Agent Service</li> <li>MOSGi JMX rmiregistry</li> <li>MOSGi JMX-MX4J RMI Connector</li> <li>Apache Jakarta log4j Plug-in</li> <li>OW2 Bundles :: Externals :: Commons Collections</li> <li>castor</li> <li>antlr-osgi</li> <li>commons-logging-osgi</li> <li>commons-lang-osgi</li> <li>commons-configuration-osgi</li> </ol>To deploy a bundle you will need the following command:<p class="paragraph"/> <i class="italic">start file:&quot;full_bundle_location&quot;</i><p class="paragraph"/> where <i class="italic">full_bundle_location</i> is the location of the bundle on your disk.<p class="paragraph"/> To <strong class="strong">skip the manual deployment process</strong>, you can download the <a href="/xwiki/bin/download/Main.Documentation/ReaderCoreProxy/config.aspire.properties" />&#99;onfig.aspire.properties</a> file and replace the original felix configuration file. Assuming that the required bundles exist in the {felix.home}&#98;undle directory, when you start felix, the bundles will be auto-deployed.<p class="paragraph"/> You may then proceed in deploying the RP bundles in the same way. The RP bundles are the following.(Please note the sequence which is essential in order to avoid any problems): <ol><li>JaxBLib</li> <li>TDT Implementation bundle</li> <li>Reader Protocol bundle (API)</li> <li>Reader Protocol implementation bundle</li> <li>Simulator reader</li> <li>Intermec IF5 reader proxy</li> </ol><h4 class="heading-1-1-1"><span id="HConfiguration">Configuration</span></h4><p class="paragraph"/> You may configure Reader core proxy using JMX. We have developed a plug-in for AspireID, the <span class="wikilink"><a href="/xwiki/bin/view/Main.Documentation.AspireIDE/PhysicalReaderConfiguration">JMX plugin</a></span>, which makes the underlying mechanics of configuration transparent to the user. You may find documentation regarding the use of the plug-in at the link above. Another way of configuration through JMX is via the JMX console, the jconsole tool, which is provided by the Sun Java JDK. You may connect to the server with the following command (assuming that felix is run at the local machine):<p class="paragraph"/> <i class="italic">jconsole service:jmx:rmi:///jndi/rmi://localhost:9995/core</i><p class="paragraph"/> A graphical user interface should be displayed providing means of using the exposed JMX functionality. You may see the available functionality under the menu rfid->service->RPreader. For details regarding the available functionality please refer to the developers guide. <h3 class="heading-1-1"><span id="HDevelopersGuide">Developers Guide</span></h3><p class="paragraph"/> As it is said in the introduction, this component is based on the OSGi framework. Thus, it is composed by a number of bundles, each implementing a different kind of functionality. The TDT bundle is covered in the <span class="wikilink"><a href="/xwiki/bin/view/Main.Documentation/TDT">Tag Data Translation</a></span> section. <h4 class="heading-1-1-1"><span id="HAcquiringthecode">Acquiring the code</span></h4><p class="paragraph"/> You can get the source code of the bundles through <span class="wikiexternallink"><a href="http://forge.objectweb.org/plugins/scmsvn/index.php?group_id=324">&#65;spire SVN</a></span>. You should get all the source code under the path aspire/trunk/bundles/. The projects under bundles are build with maven and they can be imported to eclipse. <h4 class="heading-1-1-1"><span id="HComponentanalysis">Component analysis</span></h4><p class="paragraph"/> The Reader Protocol bundle defines the API that is used by the implementation bundle. The reason we followed this strategy is to allow for other developers to implement their own implementations if such an alternative is required. The operations defined through the API are also the ones that are exported as management operations through JMX.<p class="paragraph"/> The reader protocol implementation bundle is based on the codebase of <span class="wikiexternallink"><a href="http://www.fosstrak.org">&#70;osstrak</a></span> reader project. This bundle is responsible for creating the JMX MBean and exporting it through MOSGI. Moreover, it maintains the configuration which can be updated through JMX. The bundle's jar initially contains a ReaderProtocol.xml file with a basic configuration. Every update that is made to the configuration is saved on an external configuration file that is saved under the user's home directory with the name ReaderProtocol.xml. The initial configuration is loads the RFID reader simulator implementation. If there is not such a configuration file under the user's home directory for some reason (e.g. initial deployment or deleted file) the default configuration is loaded.<p class="paragraph"/> In order for the component to be of any use, a HAL implementation is required. The HAL implementation is the actual reader with which the proxy module communicates. Within this module the standard RP calls are translated into proprietary calls.<p class="paragraph"/> Anyone who is interested in creating a bundle implementing the HAL should implement the following Java interface, which is located in the Reader protocol implementation bundle<p class="paragraph"/> <i class="italic">org.ow2.aspirerfid.reader.rp.impl.hal.HardwareAbstraction</i><p class="paragraph"/> Then the implementation bundle should be deployed in the OSGI container and the implementation class should be identified in the RP configuration through JMX.