===============================================================
*** WARNING - THIS SHOULD NOT BE NEEDED ANYMORE ***
The OSGI stuff has been moved to the trunk, we'll most probably
stop working in this directory.
===============================================================

To test the bundles here the following needs to be done:

Building Cocoon trunk
=====================

The build system in whiteboard/osgi is not integrated with the build
system in the trunk. As the OSGi bundles use results from building the
trunk, the trunk must be build first. Furthermore the bundles
currently has a number of shortcommings that requires some
modification to trunk and care while building to get everyting to
work.

* The Cocoon trunk must be build without blocks,
  "exclude.all.blocks=true", in local.blocks.properties, to avoid
  class not found errors when trying the system.

* The Cocoon bundle doesn't support directory access to sources due to
  limitations in the bundle: protocol. To get the cocoon_webapp to
  start the include patterns with wildecards must be commented away
  from src/webapp/WEB-INF/cocoon.xconf and
  src/webapp/WEB-INF/logkit.xconf. In cocoon.xconf the following line
  must also be added:

    <include src="context://WEB-INF/xconf/cocoon-blocks.xconf"/>

Building the bundles
====================

* Cocoon trunk is supposed to be at .../trunk, otherwise the
  cocoon.trunk property must be changed in bundles/*/build.xml. (This
  would better be handles with a COCOON_HOME environment variable).

* All the bundles can be compiles by

  $ ant

  in the top directory, the bundles can also be build separetly by
  running ant in the bundle/* sub directories. Ant must be version 1.6
  or later, the ant bundled with trunk will do. The build scripts
  require jakarta-bcel.jar to be present in $ANT_HOME/lib. The library
  can be found in e.g. trunk/lib/endorsed.

The Cocoon servlet
==================

* For testing the Cocoon servlet, execute "./cocoon.sh" which loads
  (over http) and starts all needed bundles and start a OSGi
  console. The options can be listed with "help". Point your browser
  at http://localhost:8080.

* If it doesn't work the Cocoon logs can be found in the work
  directory. The startup logs and the bundle logs can be looked at in
  the console: "enter log", "show", and "leave" to get back to the
  main part of the console.

* One exit the framework by writing "shutdown" in the console. OSGi
  is supposed to be persistant after shutdown, so next time uyou start
  it all the bundlles will allready be loaded and started. To reset
  the framework the directory fwdir must be removed.

* During bundle development one have to be carefull about respecting
  the dependencies while stopping, updating andd starting bundles.

The Junit testcases
===================

* Can be started by "enter junit", "run
  org.apache.cocoon.test.components.blocks.BlocksManagerTestCase", but
  it produces a painfull amount of debug messages and stacktraces, so
  it can not be recomended ;)

Bundles
=======

cocoon - contains cocoon.jar and all libraries it depnds on
cocoon_webapp - contains the webapp samples from trunk
cocoon_servlet - looks for the webapp bundle, creates the
  CocoonServlet and register it in the http service.
cocoon_testcase - creates the BlocksManager testcase and register it
  in the junit service.

Using the Eclipse OSGi framework
================================

The Eclipse OSGi is started with:

$ java -Djava.endorsed.dirs=../trunk/lib/endorsed/ -jar org.eclipse.osgi_3.1.0.jar -clean -configuration file:configuration -console

it loads everything as it is supposed to but fails with starting the
cocoon_servlet bundle. And this far I haven't found any way to get any
log messages :/

Part of the problem is that the Knopflerfish log and http service
bundles that I use are designed to be interacted with through
Knopflerfish's console service. But I have not succeeded in using
Knopflerfish's console service together with Eclipse. If I use it
whithout "-console", the framework loads everything and exits, and
with "-console", the Eclipse OSGi console and the Knopflerfish console
are running at the same time which is highly confusing.

Runtime options for Eclipse OSGi ca be found in
http://help.eclipse.org/help30/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html.