Cpp API Discussion - abroekhuis/NativeOSGi GitHub Wiki

This page is work in progress. It contains details about the C++ API design and lists the differences between the Java and the C++ API.

These requirements are not fixed, but rather discussion points. The main goal is to design an API which is easy and intuitive to use.

Because of the syntactic similarity of Java and C++, only minor differences in the API are expected.

This is mostly an issue for the Service Layer API.

Even in the context of C++11 and move semantics, return value optimization techniques can still lead to better performance compared to 'pass-by-reference' (e.g. std::vector<std::string> getValues() instead of void getValues(std::vector<std::string>&)).

Raw pointers make it necessary to communicate memory ownership and allow easy misuse. E.g. users can delete objects they don't own or access memory by pointers whose lifetime ended. Using objects on the stack which internally reference a common data pointer which is reference counted solves these issues (at a small performance cost, which is negligible for these type of objects and the used API).

Due to missing security features in C++, this layer will not be modelled in the C++ API.

C++ exception specifications are not used to declare the set of exceptions thrown by an API method. They are semantically different to the Java checked exceptions, are not equally well supported across different compilers, problematic in the context of inheritance, and generally of not much use anyway.

The following list contains methods of Java OSGi classes which do not have a direct analogue in the C++ API.

• getAllServiceReferences

  The Java method (doc

  ServiceReference<?>[]
  getAllServiceReferences(String clazz, String filter);

  is equivalent to the following C++ method (doc) because of the inherent difficulty in C++ to find a source package for a given class name.

  std::vector<ServiceReference<void> >
  getServiceReferences(const std::string& clazz, const std::string& filter);

• getDataFile

  The Java method (doc

  File getDataFile(String filename);

  is changed to return a std::string object containing the path to the data file (doc).

  std::string getDataFile(const std::string& filename) const;

• getServiceReference(Class<S>)

  The Java method (doc

  <S> ServiceReference<S> getServiceReference(Class<S> clazz);

  is equivalent to the templated method (doc)

  template<class S> ServiceReference<S> getServiceReference();

  where the template parameter is used to determine a unique interface id defined via the OSGI_DECLARE_SERVICE_INTERFACE macro.

• getServiceReferences(Class<S>, String)

  The Java method (doc

  <S> Collection<ServiceReference<S>>
  getServiceReferences(Class<S> clazz, String filter);

  is equivalent to the templated method (doc)

  template<class S>
  std::vector<ServiceReference<S> >
  getServiceReferences(const std::string& filter = std::string());

  where again the template parameter is used to specify the service type.

• registerService(Class<S>, S, Dictionary<String,?>)

  The Java method (doc

  <S> ServiceRegistration<S>
  registerService(Class<S> clazz, S service,
                  Dictionary<String, ? > properties);

  is equivalent to the templated method (doc)

  template<class S>
  ServiceRegistration<S> 
  registerService(S* service,
             const ServiceProperties& properties = ServiceProperties());

  where the clazz argument is again substituted by the template argument.

• registerService(String[], Object, Dictionary<String,?>)

  The Java method (doc

  ServiceRegistration<?> registerService(String[] clazzes, Object service,
                                         Dictionary<String,?> properties);

  is roughly equivalent to the overloaded template method

  template<class S, class T>
  ServiceRegistration<S,T>
  registerService(S* srvIFace1, T* srvIFace2,
              const ServiceProperties& properties = ServiceProperties());

  and similar overloads for 3 and up to 5 service interfaces.

TBD