NOKIA M2M PLATFORM ACTIVE NAMINGCONTEXT PROGRAMMING GUIDE. Copyright 2002 Nokia. All rights reserved. Issue

Transcription

1 NOKIA M2M PLATFORM ACTIVE NAMINGCONTEXT PROGRAMMING GUIDE Copyright 2002 Nokia. All rights reserved. Issue

2 Contents ABBREVIATIONS INTRODUCTION ACTIVE NAMINGCONTEXT ANC AS PART OF NORMAL CORBA NAMING SERVICE NAMINGCONTEXT HANDLER STARTING ANC APPLICATION...7

3 Legal Notice Copyright 2002 Nokia. All rights reserved. Reproduction, transfer, distribution or storage of part or all of the contents in this document in any form without the prior written permission of Nokia is prohibited. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. Nokia operates a policy of continuous development. Nokia reserves the right to make changes and improvements to any of the products described in this document without prior notice. Under no circumstances shall Nokia be responsible for any loss of data or income or any special, incidental, consequential or indirect damages howsoever caused. The contents of this document are provided "as is". Except as required by applicable law, no warranties of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose, are made in relation to the accuracy, reliability or contents of this document. Nokia reserves the right to revise this document or withdraw it at any time without prior notice.

4 ABBREVIATIONS ANC CORBA IDL IIOP IOR M2M NS OMG ORB POA Active NamingContext Common ORB Architecture Interface Definition Language Internet Inter-ORB Protocol Interoperable Object Reference Machine-to-machine CORBA Naming Service Object Management Group Object Request Broker Portable Object Adapter 2/8

5 1. INTRODUCTION CORBA Naming Service (NS) is an interface specified by OMG. It describes the interface and semantics of the naming service that can be used to locate, bind and unbind CORBA objects by name. A typical M2M application has a large number of objects that implement the same interface, but are located in separate terminals. Furthermore, all the details of these terminals are stored in some application-specific data store. When the client application wishes to access objects located in remote terminals, it needs to get the object reference to that object. This causes two problems. The first is that in the Nokia M2M platform, the object references, or IORs, must contain an IIOP profile with TCP/IP address that points to the Nokia M2M Gateway. The real terminal addressing details must be stored in the object_key field of the IIOP profile. The second problem is how to publish IOR to client software. In CORBA applications, object references are typically published by binding IORs to NS. This approach has the problem that the information is stored in two places, in application specific data-store and in NS, introducing possible synchronisation problems. Also, the NS bindings tend to be rather static in nature. This means that the object reference cannot change dynamically, for example to reflect the preferred bearer for the time of load balancing purposes. All the problems described above could be solved by writing an applicationspecific implementation of the CORBA Naming Service. This NS application could use the application-specific data-store to retrieve terminals addressing details, thus eliminating the need to duplicate data. Also, NS implementation could construct IORs in a dynamic fashion. This would enable the NS to control how the application should use different bearers to access remote objects. The NS interface is specified in IDL and is designed to be simple and powerful to use. However, implementing the NS interface correctly is not so straightforward. This document explains how programmers can utilise the Nokia M2M Active NamingContext (ANC) framework to create application-specific naming applications that implement the CORBA Naming Service interface. 3/8

6 2. ACTIVE NAMINGCONTEXT The Nokia M2M Active NamingContext (ANC) is a programming framework. It is written in Java programming language. With ANC, developers can create applications which implement CORBA Naming Service interface with minimal effort. Instead of requiring application developers to implement all CORBA Naming Service interfaces, developers can implement just one simple interface defined by the Nokia M2M Active NamingContext framework. The ANC framework performs most of the work and only the simplified queries are delegated to the class implemented by the developer. 2.1 ANC AS PART OF NORMAL CORBA NAMING SERVICE The ANC instance can be bound to the existing normal CORBA Naming Service. This is typical of M2M applications. The use of ANC with normal NS enables developers to use the best of both approaches. Typical object references to server objects and other static objects are bound to normal NS as usual, and only the objects that are located in M2M terminals are resolved by ANC. This configuration is easy to accomplish and simple to use. The CORBA Naming Service is a federated service that can contain multiple contexts. Contexts can be bound to other contexts, thus generating a tree-like structure, with a similar structure as file system directories. The analogy with the file system is that objects are like files, and contexts are like directories. Both are identified with a name. In the CORBA Naming Service, contexts can be distributed in different processes throughout the network. From a client s point of view, there is just one tree of contexts without any boundaries. When the ANC is bound as a sub-context to some existing context in normal NS, it can be referenced with the name used in that bound operation. For example, if the M2M application creates an ANC instance and binds it with the name my_ns into the root context of a normal NS, all requests that reference objects with a name starting with my_ns/ are directed to ANC. The use of the normal naming service is not required. ANC can be the only naming service used by the M2M application. 2.2 NAMINGCONTEXT HANDLER All ANC classes and interfaces are defined to belong to the Java language package com.nokia.m2m.activenamingcontext. The ANC framework contains an abstract class NamingContextHandler. This abstract class contains the methods that the ANC framework will call when 4/8

7 application-specific object references are requested. While client applications see and use the standard CORBA Naming Service interfaces, ANC developers only need to understand and implement the NamingContextHandler class. The following sample code demonstrates simple use of NamingContextHandler: import com.nokia.m2m.activenamingcontext.*; public class MyNameService extends NamingContextHandler { // This method is called by ANC framework. public org.omg.corba.object resolveobject( ActiveContext context, String name) { // Construct reference to object name and return // that reference. If name is unknown, return null. return objectreference; } } If the resolveobject method returns null, indicating that the requested object is unknown, ANC generates a proper exception as described in the CORBA Naming Service specification. This means that the application developer using ANC does not need to understand the details of the CORBA Naming Service specification. In addition to exception handling, ANC can process complex queries with subcontexts, create and manage binding iterators, convert name representation formats and much more. All these features make the M2M application developers work much more simple. While there are nine methods in the NamingContextHandler class, the simplest implementation requires just one method, the resolveobject method. For a complete reference of each method, see the JavaDoc documentation of the NamingContextHandler class. In the example shown above, the exact details of how the information is obtained from data-store are omitted for simplicity. Additionally, the code to construct object references is not shown. Developers can use Nokia M2M CORBA library to create IORs. The following example shows how the Nokia M2M CORBA library could be used inside the resolveobject method. In this simple example, all target details are hardcoded. In a real-life application, these details would probably come from an application data-store. The following information is used to create an object reference: Name: Value: Explanation: terminal-id Terminal ID. terminal ORB port 10 Port number the ORB is listening to in the terminal 5/8

8 object key [ 1, 2, 3, 4 ] Object key for target object gateway address M2M Gateway s IP address gateway IIOP port 6777 Port number the gateway is listening to for IIOP traffic target type-id IDL:SomeInterface:1.0 CORBA type-id for target object The example uses the WIOP SMS profile, so the Nokia M2M gateway will use the GSM SMS service as a bearer when this object reference is used: import com.nokia.m2m.activenamingcontext.*; import com.nokia.m2m.corba.ior.*; //... public class MyNameService extends NamingContextHandler { //... static final String terminalid = ; static final int terminalport = 10; static final byte[] objectkey = new byte[] { 1, 2, 3, 4 }; static final String gatewayaddress = ; static final int gatewayport = 6777; static final String typeid = IDL:SomeInterface:1.0 ; public org.omg.corba.object resolveobject( ActiveContext context, String name) { // Only object SomeObject is known. if (name.equals( SomeObject ) == false) { return null; } // Create SMS component with terminal information. TaggedComponent component = new TaggedComponentSMS( terminalid, terminalport); // Create WIOP profile with SMS component. TaggedProfile profile = new TaggedProfileWIOP( Version.version10, new TaggedComponent[] { component }, objectkey); // Create IIOP profile that contains WIOP profile // created in previous step. TaggedProfile gatewayprofile = profile.addgatewayiiopaddress( Version.version10, gatewayaddress, gatewayport, null); // Create IOR with the IIOP profile created in // previous step. Ior ior = new com.nokia.m2m.corba.ior.ior( typeid, new TaggedProfile[] { gatewayprofile } ); // Convert IOR to object reference and return it. return ior.toreference(orb); 6/8

9 } // STARTING ANC APPLICATION Developers can start an ANC application with their implementation of the NamingContextHandler class. The short example below shows how to start an ANC application. First the CORBA ORB is initialised and the root POA is resolved. Next, an ANC is created with the root POA and our implementation of the NamingContextHandler. ANC is bound to an existing naming service with the name my_ns (see the chapter entitled ANC as part of normal CORBA Naming Service ). The code for method resolveobject is omitted from this example. import org.omg.corba.*; import org.omg.cosnaming.*; import org.omg.portableserver.*; import com.nokia.m2m.activenamingcontext.*; import com.nokia.m2m.corba.ior.*; public class MyNameService extends NamingContextHandler { public static void main(string[] args) { // Initialize ORB. ORB orb = ORB.init(args, null); // Get hold of the root POA, and activate POA. POA poa = POAHelper.narrow( orb.resolve_initial_references("rootpoa")); poa.the_poamanager().activate(); // Create ANC. Use log as log instance name root POA, // our handler and bind ANC to real NS under context my_ns. ActiveNamingContextImpl anc = new ActiveNamingContextImpl( log, poa, new MyNameService(), my_ns ); } } // Let ORB process requests. orb.run(); Since the ANC is bound to NS, clients can use it like this: // Initialize ORB. ORB orb = ORB.init(args, null); // Get CORBA Name Service. org.omg.corba.object nsobj = orb.resolve_initial_references("nameservice"); NamingContextExt ns = NamingContextExtHelper.narrow(nsObj); // Use NS to resolve objects. 7/8

10 org.omg.corba.object someobject = ns.resolve_str( my_ns/someobject ); In this case, the client uses normal NS to resolve the object with the name my_ns/someobject. NS sees that the context my_ns references the ANC implementation of the NamingContext interface we bind in our example. NS delegates the request to ANC, which in turn calls the resolveobject method on our MyNameService class. In the call to the resolveobject method, the argument name would contain the value someobject. 8/8