2014-02-25 14:29 GMT+01:00 Christian Schneider <[email protected]>:
> As Achim stated in the roadmap thread Guillaume and me had a lot of > discussions on the irc channel recently. I fully agree that we need to > recapitulate the discussions here on the list to give the other community > members a chance to take part in the discussion. > > Overview > ------------ > So I would like to start with a short overview on what we have now: > > Karaf Commands: > - Based on Karaf Action interface > - One Class per command > - Action objects are not thread safe. They need to be created per command > call and are discarded after that > Just fyi, the goal was to remove the burden of writing thread safe classes for the user, so it's not really a limitation, it's a feature. The consequence of this feature is that actions lifecycle is handled by the framework and not the user. > - Command arguments and options are described as private attributes with > annotations > - Completion support using the Karaf specific Completer interface > - Fully work in karaf > - Do not work at all in felix gogo > - Needs an intermediary command class that kind of translates from Action > to command and that publishes the command as a service > - Because of the intermediary the user is exposed to internals like > AbstractCommand and DefaultActionPreparator which makes blurs the API a bit > The user is not really exposed to it. I don't think any of our command uses those classes, more below. > - As Action is not meant to be called we currently do not expose it as a > service so the intermediary either has to be created by a framework > extension (DS plugin or Blueprint namespace handler) > - The blueprint extender and new namespace support safes a lot of xml > configuration but on the other hand introduces some special DI annotations > that are karaf proprietary > Those new annotations are not much different from @Command or @Option / @Argument. You think they are different because you're looking at what is done inside the implementation. From a user perspective, it defines the command and the completers and needed services if any, so they're all additional metadata to actions and completers. > > Felix Commands > - Based on Command interface > - Alternatively based any pojo Class. I will describe this type of > commands in below as they are more modern > - One method per Command > - Arguments and Options are described as method parameters with annotations > - No Completion support for arguments and options as far as I know > - Work fully in gogo > - Are not shown in karaf but can be called > Those 2 last things are the same from a gogo perspective. The gogo commands in karaf works the same as the gogo commands in gogo afaik. > > So based on the current situation we discussed what can be done to make > using and providing commands easier. > > Target Audience > --------------------- > > So who do we address? > - Karaf developers who write commands for karaf itself > - Developers of external projects that like to provide shell commands for > karaf but also for other environments like Eclipse RCP. Or custom > application with felix + gogo. ( Examples are cxf, camel, activemq, several > pax projects) > > Goals > ------- > > Some goals here: > - We would like to have a simple API for commands that does not expose the > inner workings to users > - Ideally we would like to be framework agnostic as the external projects > typically already decided about their framework choices or might want to > switch in the future > - For karaf itself we do not absolutely need the framework agnostic goal. > Instead we want to achieve ease of use in Blueprint and DS which are the > main frameworks in karaf. For the future DS is probably even the more > important > - External projects should be able to write one style of commands that > runs in a wide range of environments > > Ideas > ------- > > 1. Minimize exposed api > Currently most internals are exposed in DefaultActionPreparator. We could > provide it as a service with the ActionPreparator interface. So instead of > "new" in AbstractCommand we could look up the service there > The API exposed to the user is the Action interface and the @Command, @Option, @Argument, @Completer, @Service, @Reference annotations. That looks pretty minimal to me. The fact that some implementation classes (such as AbstractCommand, etc...) are leaking is mostly due to classloader constraints. If that's really a problem, I think we could easily write an extender. As a matter of fact, it was in master until a few days ago. See https://github.com/apache/karaf/commit/2bd28679e01f3800a2d686fcc214c850f0a3c2c5 Maybe we should pursue this way as it should enable us to completely hide the implementation classes. > > 2. Create generic Actionpublisher using whiteboard model > I created a whiteboard model for an ActionPublisher. In this case the > Action would be published as services. So this would minimize the API the > user sees and be easy to use. Downsides is that we publish an Action > service that is more a template than a real service. So Guillaume had some > major issues with this attempt. > So probably this is not the way we will proceed > > 3. Create generic ActionPublisher as service > An alternative to the above would be to create a service that can be > called with your Action object as a parameter and that publishes a suitable > command for it. So in this case the ActionPunlisher is a real service and > still manages to hide our implementations. We could reuse the simple > reflection based action copying form the whiteboard model. This would allow > to have one ActionPublisher instead of the different commands we use right > now. (Blueprint, DS, ...). The service could also be reused in the DS > plugin and the blueprint namespace > I think this actually make things more complicated, as blueprint and DS are not really meant to call a service from the registry without any user code. > > 4. Improve support for gogo commands > The current gogo command model is quite feature rich. Compared to karaf it > mainly lacks completion support. So I am pretty sure we could make gogo > commands work in karaf with the same feature set like karaf Actions. This > would provide especially external developers a way to create commands that > is easy to handle and does not expose them to the implementations without > any framework extensions. As gogo commands are real services it is > especially easy in DS as the normal injection model works I don't really have any problem with that. It should not be very difficult to improve the console to give visibility to those commands. For completion, we definitely can't go as far as karaf commands, but at least the name of the command and maybe option names could be completed, and eventually use the same default completers, though it kinda depends how the parsing is done (not sure how boolean options are parsed). > > 5. Make karaf commands work in gogo > I prepared a branch where I split the command runtime (api + abstract > command impls) from the console. It should be possible to install this on > top of felix gogo to make karaf commands work outside karaf. > Have you tried it in bare felix + gogo yet ? > > > > I would be happy about feedback to these ideas. @Guillaume please correct > me if I stated anything incomplete or incorrectly. > > Christian > > > > -- > Christian Schneider > http://www.liquid-reality.de > > Open Source Architect > http://www.talend.com > >
