qpid-proton mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rafael Schloming <...@alum.mit.edu>
Subject proton-j/proton-c integration primer
Date Mon, 02 Feb 2015 20:56:03 GMT
This question has been raised a couple times on IRC now, so I figured I
should write up a quick summary. If you're newish to proton development,
you might be wondering why there are two apparently independent projects
(proton-c and proton-j) that share the same git repo and release cycle.

These projects aren't actually quite as independent as they look. There is
a common test suite that runs against both implementations to help keep
them in sync with each other. This is the python test suite that lives
underneath the top level tests/python directory.
These tests have been integrated into the maven build via jython so that
the whole java build looks like a normal maven build and java developers
don't need to deal with cmake or getting jython themselves or anything
that's outside of the normal java experience.

Likewise, the cmake build will detect if java is unavailable and opt out of
building the java code, so it's easy for C developers to pretend that Java
doesn't exist. It also does this for all the different bindings, e.g. if
perl or ruby isn't installed it will not attempt to build them.

As a core proton developer, it's a good idea to make a point of having all
the optional stuff enabled. This will ensure that you are testing any of
your changes against the widest range of code possible.

It's also good to be aware of exactly how the common test suite integrates
with both proton-c and proton-j. The python binding actually consists of a
hand written wrapper layer that encapsulates the raw swig generated API.
The raw swig API is actually much lower level and is available in the
'cproton' module. When you run the python test suite in jython, the swig
generated cproton doesn't actually exist since it is a C module. Instead,
you get the cproton.py that resides in the java source tree
(proton-j/src/main/resources/cproton.py). This cproton.py and its dependent
files serve as a shim that adapts between the Java API and the C API. These
files can actually be quite handy as a reference for how to translate a
given idiom from proton-j into proton-c or vice versa.

You might notice some parts of the shim are stubbed out, e.g. like this:

  def pn_flowcontroller(window):
      raise Skipped()

Throwing a Skipped exception will signal to the test runner that whatever
code is being called is not available, and the test will be reported as
"skipped" rather than flagged as an error.

I've put this content up on the proton web site here:

  http://qpid.apache.org/proton/proton-j-proton-c.html

--Rafael

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message