…or why documentation is important 😉
remark: the goal of this blog post is to report my experiences from my very personal POV and to help that projects can be more attractive to developers and perhaps also helping some developers how to solve problems if the TargetPlatform doesn’t work as expected
if you’re a member of an Open Source project perhaps you know this phenomen: someone is new on your newsgroup, asks questions and suddenly he/she disappears. there’s a chance that he/she isn’t a satisfied consumer of your project.
let me tell you a short story from my experiences last days:
as you probably know, I’m working on enterprise and mobile solutions, where for the enterprise site I prefer Eclipse RT projects like Equinox, Riena, … and at mobile site at the moment I’m focused on BlackBerry Java development. (not forget to mention Eclipse Modeling projects like MWE, Xpand/Xtend or Xtext helping me to solve my requirements to develop great apps in a short timeframe)
if developing mobile Business APPs, then you not only have a mobile APP – there’s always the need to communicate with a server and most times you have to support a bunch of protocols. The task I had to solve was communicating to a server from a mobile using TCP Socket. on BlackBerry devices this can be a ‘direct’ TCP Socket connection from the device to a server or a connection thru BES (BlackBerry Enterprise Server)
what do I need for Socket Connections:
- should fit into my Equinox OSGI server
- easy to be added to my TargetPlatform
- using Declarative Services to be flexible
- EPL licensed because I always provide core parts of my work under EPL
I googled to see if there’s a ready-to-go OSGI solution and found some TCP Socket servers but not OSGI – ready and in many cases not compatible with EPL.
but hey – I know that TCP Socket isn’t the only connection I need – there’s this great Eclipse Project supporting all kinds of communication: ECF (Eclipse Communication Framework)
at first I visited the ECF project homepage to see if there’s such a thing like a simple TCP Socket Server available but didn’t found one, then I asked in the NewsGroup and got an answer very soon: yes, ECF is using TCP Socket in many cases and I should take a look at the Generic Server.
because working on RT projects I need all to be available in my Target Platform. this should be easy for an eclipse RT project (I thought)
looked at the project sites to find installation docs how to do this but only found the update site.
to avoid all side effects I started with a fresh 3.6.1 EPP Modeling installation and created a new TargetPlatform based on the IDE, then I added the update site to my Target Platform definition. at first I checked that required software should be included.
unfortunately this runs into errors:
ok – nice try but then let’s try it without checking “include required software” – but this doesn’t help because after setting the Target Platform the ECF plug-ins are not resolved.
because there’s no documentation and I’m not getting answers to this from the newsgroup I started to try out some combinations.
btw: did all work using the normal update site and also the nightly builds.
after adding Equinox Target Components and Eclipse RCP SDK to my TargetPlatform:
it looks better and only some plug-ins were not resolved:
hint: if you read some of my blog posts about Eclipse Target Platforms you probably know that the “Target Platform State” view is your helper in these cases.
I found 3 problems:
- required bundle org.apache.log4j as dependency from org.apache.zookeeper
- missing javax.xml
- missing org.eclipse.ecf.core.util in version 3.2.0
1. log4j: I don’t want to discuss now if required bundle or import package is better, but there are some good reasons for dependencies to logging frameworks to use import package because you never know which bundle will provide the log4j packages. in my case I’m using SLF4J where’s a bundle available to do this. ok – I opened a bugzilla (335784) to change this and there’s some work on this. for now I solved this and imported the bundle org.apache.zookeeper into the workspace, opened the MANIFEST.MF and changed it. also I added my SLF4J and Logback bundles.
2. the missing javax.xml: thats also easy to solve. perhaps you know that you can add bundles on-the-fly to your Target Platform without knowing who’s providing it. You can ‘Add Artifacts’ (on the Mac CMD-ALT-SHIFT-A to get this view:)
simply enter javax.xml and by magic it’s added to your Target Platform 🙂
3. missing constraint: org.eclipse.ecf.osgi.services.distribution tries to import the package org.eclipse.ecf.core.util in version 3.2.0. This package was provided by org.eclipse.ecf bundle, but this bundle exports the package without a version number so it couldn’t be resolved. again as a good citizen I opened a bugzilla (335786). to help me in the meantime I imported org.eclipse.ecf.osgi.services.distribution into the workspace and removed the version from import-package-dependency. this was fixed very soon from ECF – so if using the N-Builds it should be there soon.
great: all ECF PlugIns resolved – so I created my OSGI launch config and really I got the Generic Server running 🙂
now the real work can start: to see how to get a TCP Socket Server running from ECF. …worked thru the code of GenericServer and found that there’s a ServerManager created in Activator. worked thru this code to find out where I can add my classes to get the Socket Connection and work with ServerSocket and Socket. found out that I can define properties (like port number) in xml or extension registry. decided to use the xml – but trying to connect from outside doesn’t work. found out that there was a bug in an if-else construct and the xml was never read. again opened a bugzilla, added the solution and got soon answers inside the bugzilla.
but I wasn’t satisfied to hear ‘this ServerManager is outdated, only for backword compatibility, we know there’s no documentation but we have no resources…‘
uuups: no time to declare it as deprecated ?
THIS was the point I decided to stop evaluating ECF and started to write an (OSGI aware) TCP Socket Server by myself. will blog about this and provide sources.
I spent more time trying to find out what happens inside ECF (without finding the solution) then developing it by myself.
ECF is a great project and I can imagine that you can do all what you want, but from my POV it’s more important to have documentation to guide new users then always adding new features or changing the way how it works.
comparing my experiences with another RT Project like Riena – there are lightyears between Riena and ECF.
- well documentation
- installation-hints-to-get-target-platform running
- many different examples to be run as eclipse project or client-server
- wizards to create your own project based on Riena technologie
- uncount unit tests
…and Riena is also a very complex project …but it’s really fun
remark: the only goal of this blog post is to give the ECF team some hints to become better. it also may be that I don’t found the right informations from wiki. and maybe if you’re looking for another kind of communication it will run out of the box from ECF.
the good things: work on my reported bugzilla happens soon after reporting – even on the weekend – thx to the ECF team