1 József Bíró Senior Research Engineer, Nokia Siemens Networks 16 October, 2008 SA Forum Java APIs in OpenSAF

2 Content Integrating Java and AIS Java APIs for AIS JNI-based implementation of AIS Java APIs Java AIS APIs in OpenSAF How to write a simple AMF Component? (Demo)

3 Content  Integrating Java and AIS Java APIs for AIS JNI-based implementation of AIS Java APIs Java AIS APIs in OpenSAF How to write a simple AMF Component? (Demo)

4 Integrating Java and AIS The Java perspective: Enable Java in carrier grade systems One requirement of this is HA support The most obvious way to ensure HA support is to add Java APIs that provide HA functionality Of course there should be an underlying platform that provides the HA functions SA Forum AIS middleware is one candidate for such a platform SA Forum Objectives: Enable the integration of Java platforms (APIs, frameworks, application servers) and SA Forum AIS platforms. Enable the usage of Java in applications written directly for AIS

5 Integrating Java and AIS Problems: Architecture integration: –Q:How to map Java VM into the AIS architecture? –A:Container Component, specified in AMF B (mid-2007) Matching the services: –Q:How to map AIS services to Java APIs? –A:Define a layered architecture and specify the missing pieces

6 Integrating Java and AIS Architecture integration: AIS: Defines a Cluster of Nodes, Applications are implemented as sets of Components on Nodes. Components are isolated from each other (like OS processes) Java: Defines a JVM, typically executed in a single OS process, Applications are implemented within the JVM In Java SE, a JVM executes a single application In Java EE and other frameworks, the JVM may execute multiple applications. The notion of ”application” is determined by the framework. Applications are (usually) not isolated from each other How to match these two worlds?

7 Integrating Java and AIS Architecture integration: Option 1: Execute a each AIS Components in a dedicated JVM

8 Integrating Java and AIS Architecture integration: Option 1: Execute a each AIS Components in a dedicated JVM Rationale: Separate JVM ensures Component separation as expected in AIS Drawbacks: Footprint (potentially huge number of Java VMs on a single node) Performance (for the same reason) The bottom line: This option can work in some cases (e.g. if the number of Java Components is small and/or if the platform has sufficient resources for many JVMs) BUT: there will be use cases when the “JVM instance bloat” is not acceptable We need to find another option!

9 Integrating Java and AIS Architecture integration: Option 2: Introduce a new AIS Component type that “contains” other AIS Components

10 Integrating Java and AIS Architecture integration: Option 2: Introduce a new AIS Component type that “contains” other AIS Components Rationale: “The concept of container and contained components allows … to integrate components that are not executed directly by the operating system, but rather in a controlled environment running on top of the operating system.” New AMF Specification: The proposed new feature was elaborated by the Application Interface Specification Subgroup and it is now included in AMF B (R5) Note that pre-B.03 AMF platforms have to go with Option 1!

11 Integrating Java and AIS AIS Service (native code) AIS adaptation layer (e.g JNI based) Java integration layer Container integration layer Java EE Application Java EE API Java SE API AIS Service Java API AIS Service C API AIS Service (native code) AIS adaptation layer (e.g JNI based) Java integration layer Java SE Application AIS Service (native code) AIS adaptation layer (e.g JNI based) Java SE Application Java EE (or other Java app server) Java SE

12 Integrating Java and AIS AIS ServiceExisting Java APIs (*) Availability Management FrameworkNo existing API Custer Membership ServiceNo existing API Checkpoint ServicePersistence API (JSR 220) Event ServiceJava Message Service Message ServiceJava Message Service Lock ServiceN/A (language constructs exist) Naming ServiceJava Naming and Directory Interface (JNDI) Log ServiceJava Logging API Timer ServiceN/A (core Java library support exists) Notification ServiceJava Management Extension (JMX) Information Model Management Service Java Management Extension (JMX) (*) Note that the list of existing Java APIs is incomplete

13 Integrating Java and AIS The lower level: AIS Service APIs Provide semantically the same service as the C AIS API. Utilization: –Used directly by Java applications (Java SE) –Low-level building block for higher-level Java (Java EE, etc.) SA Forum intends to define these Java APIs for every AIS service.

14 Integrating Java and AIS The higher level: Option 1: Exploit/use existing Java APIs that provide similar service Preferred, if there is such a Java API (“don’t reinvent the wheel”) Still, the integration layer of between the AIS Service API and the high-level Java API may not be straightforward. SA Forum should create white papers that describe how these existing Java APIs could be integrated with the AIS Services. Option 2: Create new Java APIs that provide similar service Only if the service is not covered at all: AMF, CLM These APIs should be defined within JCP, i.e. without direct SA Forum involvement. (See JSR-319 for Availability Management…)

15 Integrating Java and AIS What has been done so far? Container Component, defined in AMF B (mid-2007) (models the role of Java VM, allowing multiple AMF components in a JVM…) Log white paper (eof 2007) (on the integration of Java LOG API and AIS Log service) AIS Release 5.1 (July 2008) (Java APIs for AMF, CLM and NTF, defining also the framework for future APIs) (compliant with Release 5 AIS services) NTF white paper (July 2008) (on the integration of JMX and AIS NTF service)

16 Integrating Java and AIS Current roadmap: Release 2 (B.01.01) Java APIs for AMF and CLM, expected 4Q (*) (for inclusion in OpenSAF), Release 6 Java APIS, expected eof 4Q (Java APIs for AMF, CLM, IMM and NTF, compliant with Release 6 AIS services) In future (roadmap not yet defined): Release 3 and 4 for AMF and CLM (*) (for inclusion in OpenSAF) More APIs More White Papers (*): Contribution by Nokia Siemens Networks

17 Content Integrating Java and AIS  Java APIs for AIS JNI-based implementation of AIS Java APIs Java AIS APIs in OpenSAF How to write a simple AMF Component? (Demo)

18 Java APIs for AIS AIS Service APIs (the lower level): Semantically identical mapping of native AIS services, tailored to Java conventions and patterns AIS Service (native code) AIS adaptation layer (e.g JNI based) Java integration layer Container integration layer Java EE Application Java EE API Java SE API AIS Service Java API AIS Service C API AIS Service (native code) AIS adaptation layer (e.g JNI based) Java integration layer Java SE Application AIS Service (native code) AIS adaptation layer (e.g JNI based) Java SE Application Java EE (or other Java app server) Java SE

19 Java APIs for AIS Separating services into packages org.saforum.ais: Storage for global AIS constants and types. org.saforum.ais.amf: Application Management Framework API org.saforum.ais.clm: Cluster Membership Service API org.saforum.ais.ntf: Notification Service API Etc.

20 Java APIs for AIS The AIS API lifecycle model: 1.The client code initializing a dynamic entity representing the association between the client and the AIS service implementation. 2.The client code communicating with the service via the entity. 3.The client code shutting down the association when it is not needed any more. Note that: each AIS service provides its own entity type The client is free to create more associations with the same service.

21 Java APIs for AIS The core API object: Handle (the entity representing the dynamic association between the client code and the AIS service.) Encapsulates library life cycle (initialize, finalize), Supports asynchronous communication between the AIS service and the client (via registering, detecting and dispatching callbacks) It is a gateway to other objects representing the API calls of the particular AIS service.

22 Java APIs for AIS Key AMF interfaces: Handle (in root package) Encapsulates library lifecycle methods ( Factory.initializeHandle(), finalizeHandle() ) Associates Java callbacks with the library instance: Callbacks Implements callback dispatching ( dispatch(), hasPendingCallback() ) AmfHandle (all other services have a similar class) Component response to framework requests (AMF specific) ( response() ) Returns classes representing API calls (AMF specific) ( getComponentRegistry(), getCsiManager(), etc. ) Classes representing API calls (AMF specific) ComponentRegistry CsiManager ProcessMonitoring ProtectionGroupManager Healthcheck ErrorReporting

23 Java APIs for AIS Key AMF interfaces: ComponentRegistry : Inform the framework that the Component (AMF jargon for application code) is ready to provide service. CsiManager, SetCsiCallback, RemoveCsiCallback : The AMF uses callbacks to request Components to –add or remove CSIs from Components that are in the in service, –change the HA state of a Component on behalf of a CSI (active, standby, quiescing, quiesced). (CSI is Component Service Instance, AMF jargon for service) ProtectionGroupManager : start tracking changes in application states and services. These changes are notified via the invocation of a callback method.

24 Java APIs for AIS Key AMF interfaces: ComponentRegistry

25 Java APIs for AIS Key AMF interfaces: CsiManager and related listeners

26 Java APIs for AIS AMF functions: ProcessMonitoring : Start passive monitoring of specific errors, which may occur to a process and its descendents. If a monitored error occurs, AMF will automatically report an error on the Component. Healthcheck : Start and stop a specific healthcheck. Healthchecks can be invoked by the AMF or by the Component. ErrorReporting : Component errors can be reported to AMF, which will then react on the error report and carry out a recovery operation to retain the required availability of the CSIs supported by the erroneous Component.

27 Content Integrating Java and AIS Java APIs for AIS  JNI-based implementation of AIS Java APIs Java AIS APIs in OpenSAF How to write a simple AMF Component? (Demo)

28 JNI-based implementation of AIS Java APIs Possible implementation strategies –Java layer on native implementation JNI Other, e.g. Sockets –Pure Java implementation Selected strategy: JNI –Best to rely on existing implementation –Can be easily ported to any native AIS impl.

29 JNI-based implementation of AIS Java APIs Architecture: Currently works only with 1 VM - 1 Component mapping Should be easy to extend it to Container Components Modules: Java interface classes Java implementation classes C implementation (JNI layer) Tests

30 JNI-based implementation of AIS Java APIs Modules: Java interface classes –(as defined by SAF) –org.saforum.ais, org.saforum.ais.amf, etc. –Mostly interfaces and classes for data transfer + factory class Java implementation classes –com/org.someVendor.ais –com/org.someVendor.ais.amf –etc.

31 JNI-based implementation of AIS Java APIs Modules: C implementation –JNI layer, calling the C API –Converting data types –Creating Java objects if needed –Converting errors to exceptions Tests –Regression tests based on JUnit –Aim is to tests that the Java layer properly propagates information/control to/from the C API –Sometimes bugs in the underlying implementation may be captured instead of Java bugs

32 Content Integrating Java and AIS Java APIs for AIS JNI-based implementation of AIS Java APIs  Java AIS APIs in OpenSAF How to write a simple AMF Component? (Demo)

33 Java AIS APIs in OpenSAF SAF R2 (B.01.01) Java APIs for AMF and CLM –Being voted by SAF, soon to be official Contributed by Nokia Siemens Networks Assistance by (i.e. special thanks to) –András Kövi and Co. (OptXware / Budapest University), for OpenSAF integration –Jonathan Fournier, for build integration

34 Java AIS APIs in OpenSAF To be included in Release 3 Beta 2 –very soon –Until then: staging-java/rev/0501a2f867b4 staging-java/rev/0501a2f867b4 Requirements: –Java 1.5 or above (e.g. enums) –Ant (for the build process) –JUnit (for the tests)

35 Java AIS APIs in OpenSAF Location: OPENSAF_DIR/java –/ais_api: Java interface classes –/ais_api_impl: Java implementation classes –/ais_api_native: C implementation –/ais_api_test: JUnit tests

36 Java AIS APIs in OpenSAF How to build: Read INSTALL (or ask us!) Optional component, make sure it is switched on Otherwise the same as the normal process

37 Java AIS APIs in OpenSAF How to test it: Look at …/java/INSTALL!!! CLM tests: –can be run using any configuration –ais_api_test/configandscripts/runClmTests.sh Some directories must be properly specified AMF tests: –There is a template configuration –There are two simple AMF example applications

38 Java AIS APIs in OpenSAF Future enhancements: Add new AIS services Update to newer versions Code improvements (e.g.logging) More tests Integrate tests into emerging OpenSAF framework

39 Content Integrating Java and AIS Java APIs for AIS JNI-based implementation of AIS Java APIs Java AIS APIs in OpenSAF  How to write a simple AMF Component? (Demo, hopefully)

40 How to write a simple AMF Component? What we would like to demonstrate? Minimum set of code to be written for an AMF Component: Handle initialization Component registration Callbacks Etc.

41 How to write a simple AMF Component? The demo platform: HW: This laptop SW: VmWare + Linux + OpenSAF The AMF configuration: 1 Controller Node 1 Payload Node –2 Components (2N redundancy) –3 Component Service Instances (CSI)

42 How to write a simple AMF Component? A single-threaded AMF Component: Starting the Component –Initialize AMF handle Prepare callbacks Specify version Ask for a handle –Get Registry –Register Component Dispatch loop Stopping the component –Unregister the Component (if needed) –Finalize AMF handle

43 How to write a simple AMF Component? Create callbacks: // implement Callback interfaces Class MySetCsiCallback implements SetCsiCallback{ public void setCsiCallback( long invocation, java.lang.String componentName, HaState haState, CsiDescriptor csiDescriptor ){ // add implementation here… } // add other Callback definitions here… // collect created callback objects AmfHandle.Callbacks amfCallbacks = new AmfHandle.Callbacks(); amfCallbacks.csiSetCallback = new MySetCsiCallback(); amfCallbacks.removeCsiCallback = new MyRemoveCsiCallback(); amfCallbacks.terminateComponentCallback = …; // plus any other callback, if needed…

44 How to write a simple AMF Component? Specify version: Version amfVersion = new Version( ‘B’, 3, 1 ); Ask for an AMF handle: AmfHandleFactory amfFactory = new AmfHandleFactory(); try{ AmfHandle amfHandle = amfFactory.initializeHandle( amfCallbacks, amfVersion ); }catch( AisVersionException e ){ // incompatible version, // check amfVersion for supported version } // some more exceptions should be caught here

45 How to write a simple AMF Component? GetRegistry: try{ ComponentRegistry compRegistry = amfHandle.getComponentRegistry(); }catch( AisNotExistException e ){ // not associated with an AMF Component } // some more exceptions should be caught here Register Component: try{ compRegistry.registerComponent(); }catch( AisExistException e ){ // this Component is already registered } // some more exceptions should be caught here

46 How to write a simple AMF Component? The dispatching loop: while( ! terminateCallbackCalled ){ // may do some actual service here before … // checking for pending callbacks if( amfHandle.hasPendingCallback() ){ dispatch(); } // Note: exception handling not shown here! Some ways to improve: Blocking dispatch method instead of polling Use NIO selector for watching multiple callback sources (e.g multiple services) Use dedicated callback thread(s) – if your framework allows

47 How to write a simple AMF Component? Stopping the component: if( ! terminated ){ compRegistry.unregisterComponent(); } amfHandle.finalizeHandle(); // Note: exception handling not shown here! Time for a demo!

48 How to write a simple AMF Component? Adding healthchecks: Add healthcheck to AMF configuration Add healthcheck implementation to Component –Healtcheck callback (if AMF invoked) –Start healthcheck // implement healthcheck callback interface Class MyHealthcheckCallback implements HealthcheckCallback{ public void healthcheckCallback( long invocation, String componentName, byte[] healthcheckKey ){ // add implementation here… } // callback registration not shown here…

49 How to write a simple AMF Component? Adding healthchecks: // initiate healthchecks: should be done after registration Healthcheck healthcheck = amfHandle.getHealtcheck(); healthcheck.startHealthcheck( compRegistry.getComponentName(), healthcheckKey, Healthcheck.HealthcheckInvocation.AMF_INVOKED, RecommendedRecovery.COMPONENT_RESTART ); // Note: exception handling not shown here! // stop healthchecks: should be done before unregistering healthcheck.stopHealthcheck( compRegistry.getComponentName(), healthcheckKey ); // Note: exception handling not shown here! Time for a demo!

50 Questions?

Thank You! Additional questions can be sent to: Developer's Mailing List András Kövi József Bíró