Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Tutorial: Python+Java for OSGi R7 Remote Services
Contents
Introduction
OSGi Services are an excellent way to implement small, dynamic, component-based systems. With features like service versioning, dynamics, service injection and instance dependency-handling, and a clear separation between contract and implementation make it a valuable technology for the Internet of Things.
Since OSGi is a Java-based framework, services have traditionally been both declared and implemented in Java. With the OSGi Remote Services specification, and ECF's implementation of both the Remote Services and Remote Service Admin specifications -specification, it's now possible to implement and use OSGi services implemented in Python or Java.
This tutorial shows a simple example of implementing an OSGi service implemented in Python, that uses Google Protocol Buffers for high-performance cross-language serialization. These services automatically inherit all of the aspects of a Java-only OSGi service (dynamics, service injection, versioning support, etc.).
Declaring a Service
Here is a simple example Java interface declaring a single 'sayHello' method:
public interface IHello { HelloMsgContent sayHello(HelloMsgContent message) throws Exception; }
This interface is declared here in this project.
The HelloMsgContent class was generated by the Protocol Buffers protoc compiler based upon the following message declaration
syntax = "proto3"; package org.eclipse.ecf.examples.protobuf.hello; message HelloMsgContent { string h = 1; string f = 2; string to = 3; string hellomsg = 4; repeated double x = 5; }
This message declaration, when run through the protoc compiler, generates the Java HelloMsgContent source code, and also generates a Python version of the same class. The hellomsg.proto file is here.
With the IHello interface and the HelloMsgContent class, the IHello service declaration is complete.
Python Implementation of IHello Service
To implement this IHello service in Python it's necessary to provide a Python implementation class. Here's an example:
from hellomsg_pb2 import HelloMsgContent from osgiservicebridge.protobuf import protobuf_remote_service from osgiservicebridge.protobuf import protobuf_remote_service_method from osgiservicebridge import ECF_SERVICE_EXPORTED_ASYNC_INTERFACES def create_hellomsgcontent(message): resmsg = HelloMsgContent() resmsg.h = 'Another response from Python' resmsg.f = 'frompython' resmsg.to = 'tojava' resmsg.hellomsg = message for x in range(0,5): resmsg.x.append(float(x)) return resmsg @protobuf_remote_service(objectClass=['org.eclipse.ecf.examples.protobuf.hello.IHello'],export_properties = { ECF_SERVICE_EXPORTED_ASYNC_INTERFACES: 'org.eclipse.ecf.examples.protobuf.hello.IHello' }) class HelloServiceImpl: def __init__(self,props): self.props = props @protobuf_remote_service_method(arg_type=HelloMsgContent,return_type=HelloMsgContent) def sayHello(self,pbarg): print("sayHello called with arg="+str(pbarg)) return create_hellomsgcontent('responding back to java hello ')
Notes about this code:
- A HelloServiceImpl class that implements the sayHello method
- The HelloServiceImpl class has a decorator:
@protobuf_remote_service(objectClass=['org.eclipse.ecf.examples.protobuf.hello.IHello']) class HelloServiceImpl:
associates the HelloServiceImpl Python class with the IHello Java service interface.
- The sayHello method also has a decorator:
@protobuf_remote_service_method(arg_type=HelloMsgContent,return_type=HelloMsgContent) def sayHello(self,pbarg):
indicates the types (Python class) of the pbarg type and the sayHello return type. In this example they are both HelloMsgContent, but they may be of any type as long as it is a protocol buffers Message type.
The complete Python code is available here in the org.eclipse.ecf.examples.protobuf.hello.pythonhost project.
The HelloServiceImpl class, along with the @protobuf_remote_service and @protobuf_remote_service_method decorators completes the python implementation.
Accessing the hello Module
To create an instance of HelloServiceImpl at runtime, some other python code has to be able to import the hello module. Python 3 has support for creating an Import Hook, that allows Java code (in this case an OSGi bundle) to resolve and import statement like this
import hello
This Py4j remote services provider now allows a Module Resolver service to be registered resulting in a Python 3 Import Hook to call back the Module Resolver to provide the Python code for the hello module. In the org.eclipse.ecf.examples.protobuf.hello.pythonhost bundle, there is a Module Resolver service implementation called PythonHostBundleModuleResolver this implementation of the ModuleResolver service interface simply reads the hello module source code from /python-src directory inside the bundle when the hook is hit by the 'import hello' python statement.
Example Hello Consumer
The example service consumer is available in this project. This consumer uses has the IHello service instance dynamically injected by Declarative Services and then it uses the service via this code (in activate method):
HelloMsgContent.Builder b1 = HelloMsgContent.newBuilder(); b1.addX(1.1); b1.addX(1.2); b1.setF("fromjava"); b1.setTo("topython"); b1.setHellomsg("Hello message from java!"); b1.setH("An additional message from java"); HelloMsgContent request = b1.build(); HelloMsgContent result = this.helloService.sayHello(request); System.out.println("Received result="+result);
The second to last line makes the call from Java to Python via the IHello service proxy.
The Java Gateway
The only other piece required is a bundle to start the Java-side gateway, so that when the Python code is run it can connect to the Java gateway. The Java Gateway is created and configured via this component in this project.
Running the Hello Example
First, start the Java side (with the org.eclipse.ecf.examples.protobuf.hello bundle, org.eclipse.ecf.examples.protobuf.hello.consumer, and org.eclipse.ecf.examples.protobuf.hello.provider bundles). If run within Eclipse you may use the protobufhello.javaconsumer.launch config (note that the target platform must be set first to this target: releng/org.eclipse.ecf.provider.py4j.releng.target/ecf-oxygen.target).
Then the run.py should be started from Python. Prior to starting the following Python libraries must be installed: protobuf version 3.2.0, py4j version 0.10.6, and the osgiservicebridge package located in this project.
Once the run.py is started and the Py4jServiceBridge is connected to the JavaGateway, the IHello proxy will be created, injected into the HelloConsumer class, and then the sayHello call will be made to Python->HelloServiceImpl->sayHello.
This IHello service is just an example. Any other service could be similarly declared, implemented in Python, and injected and consumed in Java.
Background and Related Articles
Tutorial:_Creating_Custom_Distribution_Providers
Getting Started with ECF's OSGi Remote Services Implementation
Asynchronous Proxies for Remote Services
Static File-based Discovery of Remote Service Endpoints