felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fmesc...@apache.org
Subject svn commit: r1421893 [17/24] - in /felix/site/trunk/content: ./ documentation/ documentation/community/ documentation/development/ documentation/faqs/ documentation/subprojects/ documentation/subprojects/apache-felix-commons/ documentation/subprojects/...
Date Fri, 14 Dec 2012 14:30:22 GMT
Added: felix/site/trunk/content/documentation/subprojects/apache-felix-service-component-runtime.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-service-component-runtime.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-service-component-runtime.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-service-component-runtime.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,260 @@
+Title: Apache Felix Service Component Runtime
+
+[TOC]
+
+The Apache Felix Service Component Runtime described by the OSGi Declarative Services Specification is implemented by the `org.apache.felix.scr` bundle. As specified, the components must be declared in XML-formatted descriptor files which in turn must be listed in the `Service-Component` header of the declaring bundle.
+
+The component declarations are read when the declaring bundle is started and the respective components are verified and activated depending on their declaration.
+
+The Apache Felix Declarative Services implementation with the OSGi Declarative Services Specification Version 1.1  passes the OSGi CT.
+
+## Example
+
+To help you get a head start, here is an example of using Declarative Services. You will find more examples in the `trunk/examples` folder of the Apache Felix Project.
+
+## Component
+
+First of all the component must be implemented in a simple Java class. The Declarative Services Specification basically places no restrictions on the contents of this class. If you make use of advanced functionality such as providing an `activate()` or `deactivate()` method or using service loopup by *event strategy* (see 112.3.1 Accessing Services) you will of course have to provide the respective methods.
+
+For the sake of example, lets define a very simple class, which implements a `java.util.Comparator` service:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sample/SampleComparator.java</B></DIV><DIV class="codeContent panelContent">
+    package sample;
+    import java.util.Comparator;
+    public class SampleComparator implements Comparator
+    {
+        public int compare( Object o1, Object o2 )
+        {
+            // TODO: calculate the result
+            return o1.equals( o2 ) ? 0 : -1;
+        }
+    }
+
+
+This is of course a very simple and not very intelligently implemented comparator...
+
+## Declaration
+
+The next step consists of writing the declaration. I usually put these files in the `OSGI-INF` folder of the bundle, but the files may be placed anywhere within the bundle or any of the bundle's fragments as long as its path is listed in the `Service-Component` bundle manifest header.
+
+So here we go with the file:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>OSGI-INF/sample.xml</B></DIV><DIV class="codeContent panelContent">
+    <?xml version="1.0" encoding="UTF-8"?>
+    <component name="sample.component" immediate="true">
+      <implementation class="sample.SampleComparator" />
+      <property name="service.description" value="Sample Comparator Service" />
+      <property name="service.vendor" value="Apache Software Foundation" />
+      <service>
+        <provide interface="java.util.Comparator" />
+      </service>
+    </component>
+
+
+There are some noteworthy settings in this descriptor already:
+
+* *name* - Uniquely identifies this component and is also used to retrieve optional configuration from the Configuration Admin Service (if available).
+* *immediate* - Defines whether the component is to be instantiated immediately (`true`) or on-demand (`false`).
+* *implementation.class* - The fully qualified name of the class implementing the component. This class must be public and have a public default constructor for it to be usable by the Service Component Runtime. This class is not required to be exported and may as well be private to the bundle. In fact, you will generally not export the component implementation class.
+* *property* - These elements define configuration properties to the component. These properties are available through the `ComponentContext` which is presented to the component in the `activate` method (see below).
+* *service* - If the component is to be registered as a service, the service names are listed in *provide* elements inside the *service* element. These names will generally be interfaces and must be visible to other bundles for the service to be usable. In this sample, the service is the Java `java.util.Comparator` class, which is always visible.
+
+To finalize this declaration, add the following header to the bundle manifest:
+
+    Service-Component: OSGI-INF/sample.xml
+
+
+## Activation
+
+It may well be that the component needs to be notified, when it is activated and deactivated. For this, the component may implement an `activate` method and a `deactivate` method. Both methods must be `public` or `protected` and take a single argument, the `org.osgi.service.ComponentContext`. It is recommended for this method to the `protected` as it is only used by the Service Component Runtime and should of course not be part of the public API of the component.
+
+Here is the initial class extended with activation and deactivation methods:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sample/SampleComparator.java</B></DIV><DIV class="codeContent panelContent">
+    package sample;
+    import java.util.Comparator;
+    import org.osgi.service.component.ComponentContext;
+    public class SampleComparator implements Comparator
+    {
+        public int compare( Object o1, Object o2 )
+        {
+            // TODO: calculate the result
+            return o1.equals( o2 ) ? 0 : -1;
+        }
+    
+        protected void activate(ComponentContext context)
+        {
+            // TODO: Do something on activation
+        }
+        
+        protected void deactivate(ComponentContext context)
+        {
+            // TODO: Do something on deactivation
+        }
+    }
+
+
+Nothing more needs to be done as the Service Component Runtime automatically recognizes and calls these methods.
+
+## Service Binding
+
+The next step would probably be to do some service binding. This is somewhat more overhead, as the referred to services must be declared. On the other hand, you do not have to care to listen for these services. As examples of these strategies we will first use the lookup strategy to access an OSGi `HttpService` and then we will use the event strategy to access an OSGi `LogService` (I personally prefer the event strategy, but your mileage may vary).
+
+### Looking up the Service
+
+To use the service, the reference must be declared in the service declaration in an *reference* element. Here is the respective declaration for a log service to lookup:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>LogService Reference</B></DIV><DIV class="codeContent panelContent">
+    <component...>
+       ...
+        <reference name="http"
+            interface="org.osgi.service.http.HttpService"
+            cardinality="1..1" 
+            policy="static"
+        />
+       ...
+    </component>
+
+
+To use this service you call the `ComponentContext.getService(String)` method, for example in the `activate` method:
+
+
+    protected void activate(ComponentContext context)
+    {
+        HttpService http = ( HttpService ) context.locateService( "http" );
+    }
+
+
+### Receiving the Service
+
+The event strategy works by declaring bind and unbind methods in the component descriptor. These methods take a single parameter of the type defined in the *reference.interface* attribute and must be declared `public` or `protected`. As with the `activate` and `deactive` it is recommended for the bind and unbind methods to be declared `protected` as they are generally not part of the public API of the component.
+
+When using the event strategy, you will want to store the service in a private field of the component for later use.
+
+First here is the reference declaration:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>LogService Reference</B></DIV><DIV class="codeContent panelContent">
+    <component...>
+       ...
+       <reference name="log"
+             interface="org.osgi.service.log.LogService"
+             cardinality="1..1"
+             policy="static"
+             bind="bindLog"
+             unbind="unbindLog"
+       />
+       ...
+    </component>
+
+
+And here is some code:
+
+
+    private LogService log;
+    
+    protected void activate(ComponentContext context)
+    {
+        log.log(LogService.LOG_INFO, "Hello Components!");
+    }
+    
+    protected void bindLog(LogService log)
+    {
+        this.log = log;
+    }
+    
+    protected void unbindLog(LogService log)
+    {
+        this.log = null;
+    }
+
+
+Note, that you may refer to the `log` field in the `activate` method as we declared the reference as required. In this case the reference is provided to the component in the `bind` method before the `activate` method is called.
+
+
+## Maven SCR Plugin
+
+To simplify the tasks of generating the SCR Desriptor and adding the `Service-Component` header to the bundle manifest, the [Apache Felix Maven SCR Plugin]({{ refs.apache-felix-maven-scr-plugin.path }}) may be used. This helps keeping the descriptor and the code in sync especially during development.
+
+
+## Configuration
+
+The Apache Felix Declarative Services implementation can be configured with Framework properties which are read on startup of the implementation bundle and Configuration Admin Service configuraiton which is provided by the Configuration Admin Service to the service PID `org.apache.felix.scr.ScrService`.
+
+The following properties are supported:
+
+| Property | Default Value | Description |
+|--|--|--|
+| `ds.loglevel` | 1 | Defines a logging level at which messages are logged. This configuration property is converted to an `int` number used as the OSGi Log Service logging level.
+* If the property is a number, the `int` value of the number is used
+* If the property is a string parseable to an `int` the parsed value is used
+* If the property is any of the strings *debug*, *info*, *warn*, or *error*, the respective log level of `4`, `3`, `2`, or `1` is used.
+* Otherwise, unless the `ds.showtrace` or `ds.showerrors` property is set, the default value is assumed |
+| `ds.showtrace` | `false` | sets the log level to `debug` if set to `true` and the `ds.loglevel` cannot be converted to a value log level |
+| `ds.showerrors` | `true` | Disables logging completely if set to `false` and the `ds.loglevel` cannot be converted to a value log level and the `ds.showtrace` is not set to `true` |
+| `ds.factory.enabled` | `false` | Enables Component Factory functionality not compliant with the Declarative Services 1.1 specification if set to `true`. Only set this if you really know you need this. See the *Non-Standard Component Factory Behaviour* section below for more details. |
+| `ds.ctworkaround` | `false` | Enables workaround functionality to pass the OSGi CT. Generally this property should not be set to `true` because it enables behaviour which is not compliant with the Declarative Services 1.1 specification. See [FELIX-2526](https://issues.apache.org/jira/browse/FELIX-2526) for details. |
+| `ds.delayed.keepInstances` | `false` | Whether or not to keep instances of delayed components once they are not referred to any more. The Declarative Services specifications suggests that instances of delayed components are disposed off if there is not used any longer. Setting this flag causes the components to not be disposed off and thus prevent them from being constantly recreated if often used. Examples of such components may be EventHandler services. The default is to dispose off unused components. See [FELIX-3039](https://issues.apache.org/jira/browse/FELIX-3039) for details. |
+
+This configuration mechanism is implemented in the [ScrConfiguration](http://svn.apache.org/repos/asf/felix/trunk/scr/src/main/java/org/apache/felix/scr/impl/config/ScrConfiguration.java) and its helper classes.
+
+
+## Non-Standard Component Factory Behaviour
+
+<div class="note" markdown="1">
+If you don't know what this section is about, just ignore it and leave the `ds.factory.enabled` configuration property unconfigured.
+</div>
+
+Versions of the Apache Felix Declarative Services implementation prior to 1.2.0 supported handling of Component Factory components which is not specification compliant.
+
+This behaviour assumes the component name of the Component Factory component to be Service Factory PID and each configuration with this Service Factory PID causes the service component runtime to actually create and activate an instance of the Component Factory component automatically. This is not foreseen by the specification which defines instantiation of Component Factory components as being purely application controled and not configuration induced.
+
+To have components instantiated with factory configurations, regular components should be used. This case each factory configuration instance will create a component instance.
+
+If you know that you are using Component Factory components depending on this non-standard behaviour you may set the `ds.factory.enabled` configuration property to `true` (the default of this property is `false` thus disabling this functionality for specification compliance).
+
+For details also refer to [FELIX-1416](https://issues.apache.org/jira/browse/FELIX-1416)
+
+
+## Administration
+
+The OSGi Compendium specification defines no administrative API for Declarative Services. As of version 0.9.0-20071123.131249-8 a simple administrative API is provided the Apache Felix implementation. The bundle itself also has a Felix Shell Command providing easy commands to introspect the states of the registered components.
+
+The [Apache Felix Web Console]({{ refs.apache-felix-web-console.path }}) has built-in support for Declarative Services administration based on this API.
+
+
+### Shell Command
+
+The management API is made available to the Felix Shell as the `scr` command with a short list of subcommands:
+
+| Synopsis | Description |
+|--|--|
+| `scr help [ <subcommand> ]({{ refs.-subcommand.path }})` | Show help of the specific `<subcommand>` or list all known subcommands |
+| `scr list [ <bundleId> ]({{ refs.-bundleid.path }})` | List registered components of the bundle specified by `<bundleId>` or list all components. Each component is listed with its component ID, the state and the name. `<bundleId>` man be either the ID of a bundle or the symbolic name of a bundle. |
+| `scr info <componentId>` | Show a complete information dump of the given component. This dump includes the name, status, provided services and information on the service references. `<componentId>` may be either the ID of a component or the component's name. The component name must be used for disabled components. |
+| `scr enable <componentId>` | Enable the given component if not already enabled. If the component is already destroyed or enabled, this command has no effect. `<componentId>` may be either the ID of a component or the component's name. The component name must be used for disabled components. |
+| `scr disable <componentId>` | Disable the given component if not already disabled. If the component is already destroyed or disabled, this command has no effect. `<componentId>` may be either the ID of a component or the component's name. The component name must be used for disabled components. |
+
+The administrative API commands are also available in the Gogo shell where the subcommand names must be prefixed with the name space `scr`. Thus the `list` command corresponds to `scr:list` in the Gogo shell.
+
+
+### API Use
+
+The API consists of the main interface `org.apache.felix.scr.ScrService` and two helper interfaces `org.apache.felix.scr.Component` describing a registered component and `org.apache.felix.scr.Reference` describing a single reference of a registered component. To access the management API, client applications just ask for the `ScrService` as usual:
+
+
+    ....
+    ServiceReference scrServiceRef = bundleContext.getServiceReference( ScrService.class.getName() );
+    ScrService scrService = (ScrService) bundleContext.getService(scrServiceRef);
+    ....
+
+
+Alternatively, you may of course use the `ServiceTracker` or if you are using the `ScrService` in a component, you may have the `ScrService` bound according to the component declaration.
+
+The `ScrService` allows access to all registered components, to a specific component by component ID or to all registered components of a specific bundle.
+
+
+## Summary
+
+This tutorial just listed some very basic information on Declarative Service. To get more information, for example on hoe the Configuration Admin Service may be used to configure components, refer to the Declarative Services Sepecification in the OSGi Service Platform *Service Compendium* book.
+
+Have Fun !
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-shell-tui.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-shell-tui.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-shell-tui.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-shell-tui.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,11 @@
+Title: Apache Felix Shell TUI
+
+# Apache Felix Shell TUI
+
+The Apache Felix Shell TUI (Textual User Interface) sub-project provides a simple, text-based user interface for the [Apache Felix Shell]({{ refs.apache-felix-shell.path }}). This bundle is not of much use by itself and should always be used in conjunction with the shell service bundle. The shell service and shell TUI bundles are used by the standard Felix launcher to provide a means for interacting with the launched Felix framework instance. The shell TUI bundle is not required to use the shell service; it is possible to use it programmatically, via a GUI interface, or a remote access interface.
+
+Shell TUI supports one configuration property:
+
+* `shell.tui.checkinput` \- This is a simple workaround for a JRE bug which can appear when running Shell TUI inside Eclipse; the default value is `false`. Note that if this workaround is enabled, when running from the command line under Windows, character input is not echoed back to the screen.
+
+To set this property, add it to the `conf/config.properties` file of your Felix installation.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-shell.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-shell.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-shell.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-shell.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,241 @@
+Title: Apache Felix Shell
+
+# Apache Felix Shell
+
+* [Overview]({{ refs.-overview.path }})
+* [How the Shell Service Works]({{ refs.-service.path }})
+* [How Commands Work]({{ refs.-commands.path }})
+* [Creating a Command]({{ refs.-creating.path }})
+* [Security and the Shell Service]({{ refs.-security.path }})
+* [Feedback]({{ refs.-feedback.path }})
+
+
+
+## Overview
+
+In order to interact with Felix it is necessary to have some sort of interactive shell that allows you to issue commands to the framework and to obtain information from it. The OSGi specification does not define how an OSGi framework should provide this interactivity. Felix defines a shell service for creating and executing arbitrary commands. The shell service does not define a user interface, only a service API.
+
+The benefit of the Felix shell service approach is that it is possible to:
+
+* have multiple shell user interfaces (e.g., textual and graphical),
+* add custom commands to the shell (i.e., bundles can make commands available via the shell service), and
+* use the shell service from other bundles/services.
+
+The remainder of this document describes how the shell service works and how to create custom commands for it. This document does not describe how to use the command shell, nor does it describe the text-based or GUI-based user interfaces that are available for the shell.
+
+
+
+## How the Shell Service Works
+
+The Felix shell service is intended to be a simple, but extensible shell service that can have multiple user interface implementations, all of which are independent from the Felix framework. The shell service is currently not intended to be sophisticated, rather it is just a mechanism to execute commands. The shell service maintains a list of command services, each of which have a unique command name. The shell service is defined by the following service interface:
+
+
+    package org.apache.felix.shell;
+    
+    public interface ShellService
+    {
+        public String[] getCommands();
+        public String getCommandUsage(String name);
+        public String getCommandDescription(String name);
+        public ServiceReference getCommandReference(String name);
+        public void executeCommand(
+            String commandLine, PrintStream out, PrintStream err)
+            throws Exception;
+    }
+
+
+Using the shell service interface, it is possible to access and execute available commands. The shell service methods perform the following functions:
+
+* `getCommands()` - returns an array of strings that correspond to the names of the installed shell commands.
+* `getCommandUsage()` - returns the command usage string for a particular command name
+* `getCommandDescription()` - returns a short description for a particular command name.
+* `getCommandReference()` - returns the service reference for a particular command name.
+* `executeCommand()` - executes a particular command using the specified command line and print streams.
+
+Most of the shell service methods require no explanation except for the executeCommand() method. Even though this method is the most complex, it is still fairly simplistic. The assumption of the shell service is that a command line will be typed by the user (or perhaps constructed by a GUI) and passed into it for execution. The shell service interprets the command line in a very simplistic fashion; it takes the leading string of characters terminated by a space character (not including it) and assumes that this leading token is the command name. Consider the following command line:
+
+
+    update 3 http://www.foo.com/bar.jar
+
+
+The shell service interprets this as an `update` command and will search for a command service with the same name. If a corresponding command service is not found, then it will print an error message to the error print stream. If a corresponding command service is found, then it will pass the entire command line string and the print streams into the `executeCommand()` method of the command service (for a more detailed description of command services, see the next section).
+
+Notice that there is no method to add commands to the shell service interface. This is because commands are implemented as OSGi services and the shell service listens for service events and when a command service registers/unregisters it automatically updates its list of commands accordingly.
+
+
+
+## How Commands Work
+
+All commands available in the shell service are implemented as OSGi services. The advantage of this approach is two-fold: the shell service can leverage OSGi service events to maintain its list of available commands and the set available commands is dynamically extendable by installed bundles. The command service interface is defined as follows:
+
+
+    package org.apache.felix.shell;
+    
+    public interface Command
+    {
+        public String getName();
+        public String getUsage();
+        public String getShortDescription();
+        public void execute(String line, PrintStream out, PrintStream err);
+    }
+
+
+The semantics of the command service methods are:
+
+* `getName()` - returns the name of the command; this must not contain whitespace and must be unique.
+* `getUsage()` - returns the usage string of the command; this should be one line and as short as possible (this is used for generating the help command output).
+* `getShortDescription()` - returns a short description of the command; this should be one line and as short as possible (this is used for generating the help command output).
+* `execute()` - executes the command's functionality using supplied command line and print streams.
+
+
+
+## Creating a Command
+
+The following example creates a simple version of the `start` command.
+
+
+    package test;
+    
+    import java.io.PrintStream;
+    import java.net.URL;
+    import java.net.MalformedURLException;
+    import java.util.StringTokenizer;
+    
+    import org.osgi.framework.*;
+    import org.apache.felix.shell.ShellService;
+    import org.apache.felix.shell.Command;
+    
+    public class MyStartCommandImpl implements Command
+    {
+        private BundleContext m_context = null;
+    
+        public MyStartCommandImpl(BundleContext context)
+        {
+            m_context = context;
+        }
+    
+        public String getName()
+        {
+            return "mystart";
+        }
+    
+        public String getUsage()
+        {
+            return "mystart <id> [<id> ...]";
+        }
+    
+        public String getShortDescription()
+        {
+            return "start bundle(s).";
+        }
+    
+        public void execute(String s, PrintStream out, PrintStream err)
+        {
+            StringTokenizer st = new StringTokenizer(s, " ");
+    
+            // Ignore the command name.
+            st.nextToken();
+    
+            // There should be at least one bundle id.
+            if (st.countTokens() >= 1)
+            {
+                while (st.hasMoreTokens())
+                {
+                    String id = st.nextToken().trim();
+    
+                    try {
+                        long l = Long.valueOf(id).longValue();
+                        Bundle bundle = m_context.getBundle(l);
+                        if (bundle != null)
+                        {
+                            bundle.start();
+                        }
+                        else
+                        {
+                            err.println("Bundle ID " + id + " is invalid.");
+                        }
+                    } catch (NumberFormatException ex) {
+                        err.println("Unable to parse id '" + id + "'.");
+                    } catch (BundleException ex) {
+                        if (ex.getNestedException() != null)
+                            err.println(ex.getNestedException().toString());
+                        else
+                            err.println(ex.toString());
+                    } catch (Exception ex) {
+                        err.println(ex.toString());
+                    }
+                }
+            }
+            else
+            {
+                err.println("Incorrect number of arguments");
+            }
+        }
+    }
+
+
+A bundle activator class is needed for packaging the command servce; the bundle activator registers the command service in its `start()` method. Note: You do not need one activator per command, a single activator can register any number of commands.
+
+
+    package test;
+    
+    import org.osgi.framework.BundleActivator;
+    import org.osgi.framework.BundleContext;
+    
+    public class MyStartActivator implements BundleActivator
+    {
+        private transient BundleContext m_context = null;
+    
+        public void start(BundleContext context)
+        {
+            m_context = context;
+    
+            // Register the command service.
+            context.registerService(
+                org.apache.felix.shell.Command.class.getName(),
+                new MyStartCommandImpl(m_context), null);
+        }
+    
+        public void stop(BundleContext context)
+        {
+            // Services are automatically unregistered so
+            // we don't have to unregister the factory here.
+        }
+    }
+
+
+To compile these classes you will need to have `org.apache.felix.framework-x.y.z.jar` and `org.apache.felix.shell-x.y.z.jar` on your class path. Compile all of the source files using a command like:
+
+
+    java -cp org.apache.felix.framework-1.8.1.jar:org.apache.felix.shell-1.2.0.jar -d c:\classes *.java
+
+
+This command compiles all of the source files and outputs the generated class files into a subdirectory of the `c:\classes` directory, called test, named after the package of the source files; for the above command to work, the `c:\classes` directory must exist. Once you have compiled all of the above classes, you need to create a bundle JAR file of the generated package directory. The bundle JAR file needs a manifest, so create a file called `manifest.mf` with the following contents:
+
+
+    Bundle-Name: My Start Command
+    Bundle-Description: A 'start' command for the shell service.
+    Bundle-Activator: test.MyStartActivator
+    Bundle-ClassPath: .
+    Import-Package: org.apache.felix.shell,org.osgi.framework
+
+
+To create the bundle JAR file, issue the command:
+
+
+    jar cfm mystart.jar manifest.mf -C c:\classes test
+
+
+This command creates a JAR file using the manifest you created and includes all of the classes in the test directory inside of the `c:\classes` directory. Once the bundle JAR file is created, you are ready to add the command service to the shell service; simply start Felix and install and start the bundle created by the above command. By doing so, the new `mystart` command is made available via the shell service.
+
+
+
+## Security and the Shell Service
+
+The shell service security handling is quite simple, all security is handled by the standard OSGi framework mechanisms. For example, if a bundle should not be able to register a shell service, then it should not be given the corresponding service permission. Security handling may change in future release after some experience is gained through usage.
+
+
+
+## Feedback
+
+Subscribe to the Felix users mailing list by sending a message to [users-subscribe@felix.apache.org]({{ refs.mailto-users-subscribe-felix-apache-org.path }}); after subscribing, email questions or feedback to [users@felix.apache.org|mailto:users@felix.apache.org].
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,14 @@
+Title: Apache Felix Sigil
+
+#### Sigil: Felix
+
+Sigil provides OSGi centric development tooling, where the OSGi runtime model is extended to provide build time dependencies.
+
+- [Key Features]({{ refs.sigil-key-features-sigil-key-features.path }})
+- [User Guide]({{ refs.sigil-user-guide-sigil-user-guide.path }})
+- [Road Map]({{ refs.sigil-road-map-sigil-road-map.path }})
+- [Contributing]({{ refs.sigil-contributing-how-to-contribute-to-sigil.path }})
+
+#### Sigil: Wikipedia
+
+A sigil (pronounced /'sɪdʒ.ɪl/) is a symbol created for a specific magical purpose. A sigil is usually made up of a complex combination of several specific symbols or geometric figures each with a specific meaning or intent.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-contributing.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-contributing.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-contributing.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-contributing.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,39 @@
+Title: Sigil Contributing
+
+### Status
+
+Sigil is currently being migrated to Apache Felix from it's original home on http://sigil.codecauldron.org. As part of this migration it has been decided to go for a completely self hosted mode of development - i.e. use Sigil to build Sigil.
+
+### Issues:
+
+Please help development of Sigil by reporting issues and contributing patches [here](http://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&&pid=12310100&component=12312962&resolution=-1&sorter/field=priority&sorter/order=DESC).
+
+### Build Instructions
+
+If you want to try it out or contribute here are the steps to build Sigil in it's current form:
+
+1. Check out or update the Felix trunk (i.e., svn checkout http://svn.apache.org/repos/asf/felix/trunk felix)
+1. cd felix/sigil
+1. ant clean dist 
+
+The ant build will probably take a *long* time on first pass as it needs to download a lot of large eclipse dependencies first time around. But after this first pass the secondary builds should run quickly i.e. seconds not minutes. By way of a brief explanation of what is going on in this build.
+
+1. I've hosted a prebuilt sigil-ivy-plugin at http://people.apache.org/~dsavage/sigil/
+1. The ant build downloads ivy, sigil-plugin, bnd and equinox.common.jar and stores them in $felix-svn/sigil/cache/ant/lib
+1. Ivy caches a set of remote bundles that sigil can't yet index (i.e. no obr index to these resources yet)
+1. Sigil creates local indexes of ivy cached bundles (just indexes filesystem)
+1. Sigil builds all projects in $felix-svn/sigil/common and $felix-svn/sigil/eclipse using the meta data from the various sigil.properties files. Import-Package or Require-Bundle dependencies expressed in the sigil.properties file are resolved from either: the local workspace; the local cached repo; or the spring enterprise bundle repository (for which we do have an OBR index).
+
+### Testing
+Currently the Sigil build does not create an eclipse update site, but it will generate the plugins to install in eclipse:
+
+
+    # ls site/plugins
+    bndlib.jar                                      org.apache.felix.sigil.common.junit.jar         org.apache.felix.sigil.eclipse.help.jar         org.apache.felix.sigil.eclipse.ui.jar
+    com.springsource.org.apache.commons.lang.jar    org.apache.felix.sigil.common.obr.jar           org.apache.felix.sigil.eclipse.obr.jar          org.apache.felix.sigil.eclipse.utils.jar
+    org.apache.felix.sigil.common.core.jar          org.apache.felix.sigil.eclipse.core.jar         org.apache.felix.sigil.eclipse.search.jar
+
+
+You can copy these bundles to your dropins directory of your Eclipse install to get Eclipse to manually install these bundles from the file system.
+
+Please let us know if you have any problems, questions, or want to help out via the Felix [dev]({{ refs.mailto-dev-felix-apache-org.path }}) email list.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,28 @@
+Title: Sigil Key Features
+
+### Sigil: Key Features
+
+#### Resolves build dependencies based upon OSGi meta-data
+
+- determines compilation dependencies using the same Import-Package meta-data used by OSGi at runtime
+- avoids duplication and error
+
+#### Pluggable [repositories]({{ refs.sigil-repositories-sigil-repositories.path }}), including OBR
+
+- searches SpringSource Enterprise Bundle Repository using OBR index
+
+#### Build projects using IDE and/or command-line
+
+- IDE and command-line use same [project file]({{ refs.sigil-properties-sigil-properties-file-format.path }})
+- Currently supports [Eclipse]({{ refs.apache-felix-sigil-eclipse-sigil-eclipse-integration.path }}) and Ant/[Ivy|Sigil Ivy|Sigil ivy integration] plugins
+
+#### Simple properties-based project file
+
+- edit directly or using Eclipse Sigil project editor
+- supports multiple bundles per project
+- BND creates bundles using instructions inferred from project file
+
+#### JUnit test support
+
+- automatically resolves [JUnit]({{ refs.sigil-junit-sigil-junit-integration.path }}) test cases in a running OSGi JVM
+- generate reports in ant xml format

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,3 @@
+Title: Apache Felix Sigil Eclipse
+
+[Features]({{ refs.apache-felix-sigil-eclipse-features-sigil-eclipse-features.path }})
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse/apache-felix-sigil-eclipse-features.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse/apache-felix-sigil-eclipse-features.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse/apache-felix-sigil-eclipse-features.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-key-features/apache-felix-sigil-eclipse/apache-felix-sigil-eclipse-features.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,35 @@
+Title: Apache Felix Sigil Eclipse Features
+
+## Project Editor
+
+Double click on a sigil.properties file to open it in the project editor. From here you can control the main features of your project, including:
+* bundle headers
+* bundle contents
+* dependencies (i.e. import-package, require-bundle etc)
+* exports (package exports, sca composites, etc)
+
+To link to other OSGi bundles (either in the workspace or from an external repository) just add the appropriate OSGi dependencies and Sigil will resolve a bundle and add it to your classpath. To link to non OSGi bundles you can use the standard project build path tool to add jars - if you want these jars to be included in your built bundle, add them to the classpath table on the contents tab.
+
+## Quick Fix
+
+Sigil provides a number of quick fix options whilst editing java files. If a class needs to be imported to the bundle classpath press the quick fix icon in the left hand border (or ctrl+1 - by default) to search for a package export that provides the class and add it to the project's classpath.
+
+## Repositories
+
+Repositories are where the external dependencies for your project live. For more information see the [overview]({{ refs.sigil-repositories.path }}).
+
+## Views
+
+Sigil provides a number of views to help aid the developer. To open these views open them via "Window \-> Show View \-> Other" and navigate to the Sigil sub section.
+
+### Bundle Dependency View
+
+Select a sigil.properties file to show the dependencies for that project.
+
+!bundle-dependency-view.png|thumbnail!
+
+### Repository View
+
+The repository view allows the developer to browse the contents of a repository via a tree view.
+
+!bundle-repository-view.png|thumbnail!
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-road-map.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-road-map.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-road-map.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-road-map.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,30 @@
+Title: Sigil Road Map
+
+The Sigil framework is aiming for an initial 1.0.0 release which includes the following features:
+
+* Migration of existing build functionality from http://sigil.codecauldron.org
+* Runtime support using RFC 132 launching api
+* Self hosting (sigil builds sigil)
+
+After this there are a number of usability improvements we'd like to make that will come in a number of minor releases after 1.0.0 these may include:
+
+* Common IDE/Headless repository configuration
+* Common version handling (version inheritance in IDE is currently implicit vs explicit)
+* Refactoring support (dealing with moving packages from one bundle to another - auto add/remove import/export package)
+* Source code linking in IDE (to aid debugging)
+* Improve migration tools
+
+Also in the medium and longer term there are a number of directions we could take, and it depends on interest from the community as to where Sigil goes in the future. Some potential ideas that have been discussed so far:
+
+* Netbeans Integration - OSGi aware classpath syntax highlighting, repository management, debug support etc.
+* PDE Integration - why does the world need two eclipse OSGi development environments?
+* Maven Integration - combine with Maven Bundle Plugin? Maven 3.0?
+* Resolver enhancements - common resolver API shared by Felix, OBR and Sigil?
+* Integration with iPojo eclipse plugins
+* Extensions for DS and Blueprint development
+* Improved search support
+* Analysis tools and API's
+
+Please help by discussing requirements at the Felix [Dev]({{ refs.mailto-dev-felix-apache-org.path }}) Mailing lists.
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,5 @@
+Title: Sigil User Guide
+
+# Sigil User Guide
+
+{children}
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-installation.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-installation.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-installation.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-installation.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,43 @@
+Title: Sigil Installation
+
+# Sigil Installation
+
+We're currently in the process of setting up the Sigil build - the last remaining task here is set up of the build on the apache bamboo servers. In the mean time we have set up a daily build hosted at Sigils previous home (codecauldron.org).
+
+### Daily builds
+
+If you feel like living on the edge you can install Sigil from the daily build at code cauldron - as it is a daily build please be careful when using this in your development environments - i.e. ensure you have code checked into version control. There shouldn't be any major problems as the code is being used to develop Sigil itself - but it is only fare to give the warning. 
+
+The daily build is hosted here:
+
+http://ci.codecauldron.org/hudson/job/sigil-apache-daily/
+
+##### Eclipse Update Site
+
+Add the following update site to Eclipse 3.4, 3.5 or 3.5.1
+
+http://ci.codecauldron.org/hudson/job/sigil-apache-daily/lastSuccessfulBuild/artifact/sigil/site/
+
+##### Ivy plugin
+
+The ivy plugin is available here:
+
+[org.apache.felix.sigil.ivy.resolver.jar](http://ci.codecauldron.org/hudson/job/sigil-apache-daily/lastSuccessfulBuild/artifact/sigil/site/ivy/org.apache.felix.sigil.ivy.resolver.jar)
+
+### Build from source
+
+The following script is useful to ensure builds are created with incremental timestamps vs 0.9.0.SNAPSHOT.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>release.sh</B></DIV><DIV class="codeContent panelContent">
+    now=$(date +%Y%m%d_%H%M%S)
+    ant -DbuildVersion=0.9.0.$now clean dist
+
+
+To build (note the first build can take a /long/ time as various dependencies need to be cached - but subsequent builds take an order of 10's of seconds)
+
+    svn co http://svn.apache.org/repos/asf/felix/trunk/sigil sigil-trunk
+    cd sigil-trunk
+    sh release.sh
+
+
+Then add an update site to eclipse under `file:/path-to/sigil-trunk/site`.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,7 @@
+Title: Sigil Ivy
+
+## Sigil Ivy Extension
+
+[Quick start]({{ refs.apache-felix-sigil-ivy-quickstart-sigil-ivy-integration-quickstart.path }})
+
+[ivysettings.xml]({{ refs.apache-felix-sigil-ivy-settings-sigil-ivysettings-xml.path }})
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-quickstart.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-quickstart.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-quickstart.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-quickstart.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,281 @@
+Title: Apache Felix Sigil Ivy Quickstart
+
+[TOC]
+
+## Overview
+
+The sigil-ivy-plugin integrates Sigil with [Apache Ivy](http://ant.apache.org/ivy/). If you are not familiar with Ivy, you should visit their [tutorial|http://ant.apache.org/ivy/history/latest-milestone/tutorial.html].
+
+Sigil provides a custom Ivy resolver, which allows Ivy to resolve dependencies specified as OSGi Package-Imports, rather than as specific jar artifacts. This avoids the duplication and possible error of having to specify build dependencies separately from OSGi runtime dependencies.
+
+The plugin works by intercepting the ivy.xml parser and dynamically replacing any dependencies with the results of resolving the OSGi Package-Imports specified in sigil.properties. Sigil can resolve dependencies using a local directory of OSGi bundles, or using an [OBR repository](http://www.osgi.org/Repository/).
+
+The plugin also provides an Ant task to generate (multiple) OSGi bundles from each sigil.properties file using [Bnd](http://www.aqute.biz/Code/Bnd). sigil.properties is similar to .bnd instruction files, but it supports multiple bundles.
+
+This Quick Start is based on the Ivy [project dependencies](http://ant.apache.org/ivy/history/latest-milestone/tutorial/dependence.html) tutorial, modified to use Sigil. The modified example is in `example/dependence` in the Sigil download.
+
+## Shared Configuration
+
+### ivysettings.properties
+
+You will need to change ivy.jar to point to the location of your Ivy jar. If you don't have Ivy, you can download it from http://ant.apache.org/ivy/download.cgi.
+
+
+    repository.dir=${ivy.settings.dir}/repository
+    sigil-ivy-plugin.jar=${ivy.settings.dir}/../../../lib/sigil-ivy-plugin.jar
+    ivy.jar=/opt/apache-ivy-2.0.0-rc2/ivy-2.0.0-rc2.jar
+
+
+
+### ivysettings.xml
+
+The lines containing "sigil" need to be added to your ivysettings.xml:
+
+* *classpath* - this references the location of the sigil-ivy-plugin.jar
+* *typedef* - this defines the sigil-parser and sigil-resolver
+* *parsers* - the sigil-parser must be the last parser in the parsers section
+* *resolvers* - the sigil-resolver requires a config attribute to specify the repository configuration file
+* *modules* - the modules entry ensures that the sigil-resolver is used to resolve the injected dependencies
+
+
+
+    <ivysettings>
+        <properties file="${ivy.settings.dir}/ivysettings.properties"/>
+        <settings defaultResolver="projects"/>
+        <caches defaultCacheDir="${ivy.settings.dir}/ivy-cache" />
+    
+        <classpath file="${sigil-ivy-plugin.jar}" />
+        <typedef name="sigil-parser" classname="org.cauldron.bld.ivy.SigilParser" />
+        <typedef name="sigil-resolver" classname="org.cauldron.bld.ivy.SigilResolver" />
+    
+        <parsers>
+            <sigil-parser/>
+        </parsers>
+    
+        <resolvers>
+            <sigil-resolver name="sigil" config="${ivy.settings.dir}/sigil-repos.properties" />
+            <filesystem name="projects">
+                <artifact pattern="${repository.dir}/[artifact]-[revision].[ext]" />
+                <ivy pattern="${repository.dir}/[module]-[revision].xml" />
+            </filesystem>
+        </resolvers>
+    
+        <modules>
+            <module organisation="sigil" name="*" resolver="sigil"/>
+        </modules>
+    </ivysettings>
+
+
+
+### sigil-repos.properties
+
+This file contains the definition of the Sigil repositories. It is referenced via the config attribute on the sigil-resolver in ivysettings.xml.
+
+The repositories defined are:
+
+* *system* - resolves internal Java packages, such as `javax.swing` and optionally packages from bundle 0 of an OSGi framework provider
+* *project* - resolves against exports in sigil.properties of other projects. This allows Ivy to automatically determine the correct build order.
+* *spring* - this resolves against an OBR index for the SpringSource Enterprise Repository.
+
+It's also possible to define a *filesystem* repository based on a local directory containing bundles.
+
+
+    # repository config
+    
+    -repositories:  system, project, spring
+    
+    system;provider:        system
+    system;level:           -1
+    
+    project;provider:       project
+    project;level:  0
+    project;pattern:        ../*/[sigilproject]
+    
+    spring;provider:        obr
+    spring;level:           2
+    spring;url:             http://sigil.codecauldron.org/spring-repository.obr
+    spring;index:           ../settings/spring-repository.obr
+
+
+## Project Configuration
+
+
+### build.xml
+
+The sigil-ivy-plugin provides an Ant task to build bundles using Bnd. It requires bndlib.jar, which is on the manifest Class-Path, so you don't need to explicitly add bndlib.jar to the classpath, as long as it is present in the same directory as sigil-ivy-plugin.jar.
+
+
+    <taskdef name="sigil.bundle"
+        classname="org.cauldron.bld.ant.BundleTask"
+        classpath="${sigil-ivy-plugin.jar}"/>
+    
+    <target name="jar" depends="compile">
+        <sigil.bundle destpattern="${build.dir}/[id].[ext]"
+                     classpathref="run.path.id" />
+    </target>
+
+
+
+### ivy.xml
+
+The ivy.xml for the dependee project is unchanged (but, by default, Sigil ignores any dependences it contains).
+
+
+    <ivy-module version="1.0">
+        <info organisation="org.apache" module="dependee"/>
+        <dependencies>
+            <dependency org="commons-lang" name="commons-lang" rev="2.0"/>
+        </dependencies>
+    </ivy-module>
+
+
+
+### sigil.properties
+
+Placing a sigil.properties file next to an ivy.xml file, causes the sigil-parser to dynamically replace the dependencies contained in ivy.xml with dependencies determined from the -imports property in sigil.properties.
+
+
+    # dependee sigil.properties
+    
+    version: 1.0.0
+    
+    -bundles: dependee
+    
+    -exports: standalone
+    
+    -imports: \
+      org.apache.commons.lang;version="[2.0.0,2.4.0)", \
+    
+    -resources: \
+      version.properties
+
+
+
+## Project Build
+
+{code:bgColor=#FFFFCE}
+$ cd dependee
+$ ant jar
+Buildfile: build.xml
+
+init:
+
+resolve:
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) :: Ivy 2.0.0-rc2 - 20081028224207 :: http://ant.apache.org/ivy/ ::
+:: loading settings :: file = /Volumes/Users/derek/sigil-0.7.0/example/dependence/settings/ivysettings.xml
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) Sigil: augmenting module=dependee ant.project.name=dependee
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) Sigil: loading Project Repository: /Volumes/Users/derek/sigil-0.7.0/example/dependence/*/sigil.properties
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) :: resolving dependencies :: org.apache#dependee;working@rodney
+[ivy:retrieve]({{ refs.ivy-retrieve.path }})  confs: [default]
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) Sigil: augmenting module=com.springsource.org.apache.commons.lang ant.project.name=dependee
+[ivy:retrieve]({{ refs.ivy-retrieve.path }})  found sigil#com.springsource.org.apache.commons.lang;2.1.0 in sigil
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) downloading http://repository.springsource.com/ivy/bundles/external/org.apache.commons/
+    com.springsource.org.apache.commons.lang/2.1.0/com.springsource.org.apache.commons.lang-2.1.0.jar ...
+[ivy:retrieve]({{ refs.ivy-retrieve.path }})  [SUCCESSFUL ] sigil#com.springsource.org.apache.commons.lang;2.1.0!com.springsource.org.apache.commons.lang.jar (2619ms)
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) :: resolution report :: resolve 232ms :: artifacts dl 2620ms
+        ---------------------------------------------------------------------
+        |                  |            modules            ||   artifacts   |
+        |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
+        ---------------------------------------------------------------------
+        |      default     |   1   |   1   |   1   |   0   ||   1   |   1   |
+        ---------------------------------------------------------------------
+[ivy:retrieve]({{ refs.ivy-retrieve.path }}) :: retrieving :: org.apache#dependee
+[ivy:retrieve]({{ refs.ivy-retrieve.path }})  confs: [default]
+[ivy:retrieve]({{ refs.ivy-retrieve.path }})  1 artifacts copied, 0 already retrieved (204kB/11ms)
+
+compile:
+    [mkdir]({{ refs.mkdir.path }}) Created dir: /Volumes/Users/derek/sigil-0.7.0/example/dependence/dependee/build/classes
+    [javac]({{ refs.javac.path }}) Compiling 1 source file to /Volumes/Users/derek/sigil-0.7.0/example/dependence/dependee/build/classes
+
+jar:
+[propertyfile]({{ refs.propertyfile.path }}) Creating new property file: /Volumes/Users/derek/sigil-0.7.0/example/dependence/dependee/build/classes/version.properties
+[sigil.bundle]({{ refs.sigil-bundle.path }}) creating bundle: dependee
+[sigil.bundle]({{ refs.sigil-bundle.path }}) dependee: 0 errors, 0 warnings
+
+BUILD SUCCESSFUL
+Total time: 6 seconds
+
+    
+    Notice how 
+
+-imports: \
+  org.apache.commons.lang;version="[2.0.0,2.4.0)"
+
+    
+    in sigil.properties is resolved to com.springsource.org.apache.commons.lang-2.1.0.jar, using the OBR resolver.
+    
+    The dependencies in ivy.xml are ignored by default, you can retain them by setting the keepDependencies attribute on the sigil-parser.
+    
+    Now let's pretend that we've added some code which requires the following imports in sigil.properties:
+
+-imports: \
+  org.apache.commons.lang;version="[2.0.0,2.4.0)", \
+  javax.servlet;version="(2.4,3.0]", \
+  org.apache.log4j;version="[1.2.14,1.3)", \
+  org.apache.commons.logging
+
+    
+    {code:bgColor=#FFFFCE}
+    $ ant jar
+    Buildfile: build.xml
+    
+    init:
+    
+    resolve:
+    [ivy:retrieve] :: Ivy 2.0.0-rc2 - 20081028224207 :: http://ant.apache.org/ivy/ ::
+    :: loading settings :: file = /Volumes/Users/derek/sigil-0.7.0/example/dependence/settings/ivysettings.xml
+    [ivy:retrieve] Sigil: augmenting module=dependee ant.project.name=dependee
+    [ivy:retrieve] Sigil: loading Project Repository: /Volumes/Users/derek/sigil-0.7.0/example/dependence/*/sigil.properties
+    [ivy:retrieve] :: resolving dependencies :: org.apache#dependee;working@rodney
+    [ivy:retrieve]  confs: [default]
+    [ivy:retrieve] Sigil: augmenting module=com.springsource.org.apache.commons.logging ant.project.name=dependee
+    [ivy:retrieve]  found sigil#com.springsource.org.apache.commons.logging;1.1.1 in sigil
+    [ivy:retrieve] Sigil: augmenting module=com.springsource.org.apache.log4j ant.project.name=dependee
+    [ivy:retrieve]  found sigil#com.springsource.org.apache.log4j;1.2.15 in sigil
+    [ivy:retrieve]  found sigil#com.springsource.org.apache.commons.lang;2.1.0 in sigil
+    [ivy:retrieve] Sigil: augmenting module=com.springsource.javax.servlet ant.project.name=dependee
+    [ivy:retrieve]  found sigil#com.springsource.javax.servlet;2.5.0 in sigil
+    [ivy:retrieve] downloading http://repository.springsource.com/ivy/bundles/external/org.apache.commons/
+        com.springsource.org.apache.commons.logging/1.1.1/com.springsource.org.apache.commons.logging-1.1.1.jar ...
+    [ivy:retrieve]  [SUCCESSFUL ] sigil#com.springsource.org.apache.commons.logging;1.1.1!com.springsource.org.apache.commons.logging.jar (3180ms)
+    [ivy:retrieve] downloading http://repository.springsource.com/ivy/bundles/external/org.apache.log4j/
+        com.springsource.org.apache.log4j/1.2.15/com.springsource.org.apache.log4j-1.2.15.jar ...
+    [ivy:retrieve]  [SUCCESSFUL ] sigil#com.springsource.org.apache.log4j;1.2.15!com.springsource.org.apache.log4j.jar (5680ms)
+    [ivy:retrieve] downloading http://repository.springsource.com/ivy/bundles/external/javax.servlet/
+        com.springsource.javax.servlet/2.5.0/com.springsource.javax.servlet-2.5.0.jar ...
+    [ivy:retrieve]  [SUCCESSFUL ] sigil#com.springsource.javax.servlet;2.5.0!com.springsource.javax.servlet.jar (1856ms)
+    [ivy:retrieve] :: resolution report :: resolve 562ms :: artifacts dl 10733ms
+            ---------------------------------------------------------------------
+            |                  |            modules            ||   artifacts   |
+            |       conf       | number| search|dwnlded|evicted|| number|dwnlded|
+            ---------------------------------------------------------------------
+            |      default     |   4   |   3   |   3   |   0   ||   4   |   3   |
+            ---------------------------------------------------------------------
+    [ivy:retrieve] :: retrieving :: org.apache#dependee
+    [ivy:retrieve]  confs: [default]
+    [ivy:retrieve]  3 artifacts copied, 1 already retrieved (534kB/50ms)
+    
+    compile:
+    
+    jar:
+    [propertyfile] Updating property file: /Volumes/Users/derek/sigil-0.7.0/example/dependence/dependee/build/classes/version.properties
+    [sigil.bundle] creating bundle: dependee
+    [sigil.bundle] BND: Importing packages that are never refered to by any class on the Bundle-Classpath[Jar:dot]: 
+        [javax.servlet, org.apache.commons.logging, org.apache.log4j]
+    [sigil.bundle] dependee: 0 errors, 1 warning
+    
+    BUILD SUCCESSFUL
+    Total time: 16 seconds
+
+
+Notice that the additional dependencies have been resolved against the OBR repository. The warning from Bnd, is because those additional imports are not actually used.
+
+## Next Steps
+
+This Quick Start has shown how easily Sigil can integrate with existing Ivy builds. You should now examine the other examples, which give more details of the Sigil configuration and show some real-world examples.
+
+
+
+
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-settings.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-settings.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-settings.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-ivy/apache-felix-sigil-ivy-settings.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,61 @@
+Title: Apache Felix Sigil Ivy Settings
+
+The following items in ivysetting.xml need to be configured for Sigil.
+
+## Sigil Parser
+
+The sigil-parser takes the following optional attributes:
+
+- *delegateType* the parser type that Sigil delegates to; default it the ivy parser.
+- *delegateFile* the name of the file accepted by the delegate parser; default is ivy.xml.
+- *keepDependencies* a regular expression that matches the artifact names of any dependencies that should be kept; default is for Sigil to ignore all existing dependencies.
+- *quiet* produce less output during the resolution process.
+
+and an *override* child element:
+This is only needed when a delegate parser expects Ant variables to be set during the ivy:buildlist task (or the ProjectRepository initialisation), which they are not. The delegate parser should really be fixed, as otherwise the ivy:buildlist task won't work without this workaround.
+
+- *name* the name of the Ivy variable that will be over-ridden
+- *pattern* a regular expression matching the resource directory path
+- *replace* the value to set
+
+
+    <typedef name="sigil-parser" classname="org.cauldron.bld.ivy.SigilParser"/>
+      <parsers>
+        <!-- sigil-parser must be last, as last parser takes precedence -->
+        <sigil-parser delegateType="build"
+                      delegateFile="build.xml"
+                      quiet="true"
+                      keepDependencies="(^spring-components-.*)|(.*-cmpt$)">
+          <override name="module" pattern=".*/([^/]+)/([^/]+)$" replace="$1"/>
+          <override name="ant.project.name" pattern=".*/([^/]+)/([^/]+)$" replace="$1-$2"/>
+        </sigil-parser>
+      </parsers>
+
+
+## Sigil Resolver
+
+The sigil-resolver takes two mandatory attributes:
+
+- *name* the resolver name
+- *config* the sigil repository configuration properties file
+
+
+     <typedef name="sigil-resolver" classname="org.cauldron.bld.ivy.SigilResolver"/>
+     <resolvers>
+        <sigil-resolver name="sigil" config="${ivy.settings.dir}/sigil-repo.properties"/>
+        ...
+    </resolvers>
+
+
+
+## Modules
+
+Sigil injects dependencies with `organisation="sigil"`. You need to ensure that Ivy uses the sigil-resolver to resolve such dependecies:
+
+
+    <modules>
+        <module organisation="sigil" name=".*" resolver="sigil" />
+        ...
+    </modules>
+
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-junit.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-junit.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-junit.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-junit.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,38 @@
+Title: Sigil JUnit
+
+## Overview
+
+The Sigil JUnit plugin is an OSGi bundle that when started in an OSGi enabled JVM watches for other bundles that contain JUnit TestCase classes in the framework. The main access point to the plugin is the `org.cauldron.sigil.junit.server.JUnitService`.
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>JUnitService.java|borderStyle=solid</B></DIV><DIV class="codeContent panelContent">
+    package org.cauldron.sigil.junit.server;
+    
+    import java.util.Set;
+    
+    import org.osgi.framework.BundleContext;
+    
+    import junit.framework.TestSuite;
+    
+    /**
+     *
+     */	
+    public interface JUnitService {
+    	/**
+    	 * Returns the names of all tests currently installed in the OSGi runtime
+    	 */	
+    	Set<String> getTests();
+    
+    	/**
+    	 * Create a new instance of the specified test. Equivalent to calling createTest(test, null);
+    	 */	
+    	TestSuite createTest(String test);
+    	
+    	/**
+    	 * Create a new instance of the specified test passing the specified bundle context to the test classes.
+    	 * If ctx is null the callers BundleContext is passed to the test.
+    	 */	
+    	TestSuite createTest(String test, BundleContext ctx);
+    }
+
+
+When a test is created the `JUnitService` introspects the test class and looks for a method `public void setBundleContext(BundleContext ctx);` if one is found then the BundleContext is injected into the test class before being returned to the caller. 
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-projects.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-projects.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-projects.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-projects.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,62 @@
+Title: Sigil Projects
+
+# Sigil Projects
+
+This page is meant as an overview of how to set up sigil projects, for an in depth look at the file format see [Sigil Properties]({{ refs.sigil-properties.path }}).
+### Basics
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sigil.properties</B></DIV><DIV class="codeContent panelContent">
+    -bundles: org.foo
+    -version: 1.0.0
+    -exports: org.foo.api
+    -imports: org.foo.api
+    -sourcedirs: src
+
+
+This describes a bundle with symbolic name org.foo that has version 1.0.0 and embeds all java classes found in the folder src within our bundle. It exports the package org.foo.api and imports the package org.foo.api. If we assume that the src folder contains classes in the package org.foo.api then both the exports and imports will also inherit the version from the bundle (as no explicit version is specified).
+
+### Version management
+
+If we wanted to have explicit control we could do:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sigil.properties</B></DIV><DIV class="codeContent panelContent">
+    -bundles: org.foo
+    -version: 1.1.0
+    -exports: org.foo.api;version=1.1.1
+    -imports: org.foo.api;version=[1.0,1.2)
+    -sourcedirs: src
+
+
+### Multi project builds
+
+You can also set default versions and import ranges in your project hierarchy so leaf projects inherit the version strategy of their parent:
+
+
+    + project
+       + sigil-defaults.properties
+       + leaf-project
+          + sigil.properties
+          + src
+             + org
+                + foo
+                   + api
+                      + Foo.java
+
+
+If we define in sigil-defaults.properties:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sigil-defaults.properties</B></DIV><DIV class="codeContent panelContent">
+    version: 1.1.0
+    package;org.foo.api: [1.0,1.2)
+
+
+Then we could change our sigil.properties file to:
+
+<DIV class="code panel" style="border-style: solid;border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;border-bottom-style: solid;"><B>sigil.properties</B></DIV><DIV class="codeContent panelContent">
+    -bundles: org.foo
+    -exports: org.foo.api;version=1.1.1
+    -imports: org.foo.api
+    -sourcedirs: src
+
+
+Where the bundle version and the import range is inherited from the package;org.foo.api property from the parent sigil-defaults.properties file.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-properties.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-properties.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-properties.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-properties.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,52 @@
+Title: Sigil Properties
+
+## Overview
+
+sigil.properties is the common configuration file used in both the Eclipse and Ivy plugins. It is also used for the repository configuration (sigil-repos.properties).
+
+
+It supports 4 types of property:
+
+* *simple* - e.g. name: foo or -activator: org.acme.Activator
+
+* *list* - e.g. -bundles: foo-api, foo-impl
+
+* *map* - e.g. -imports: org.foo; version=1.2, org.bar; version="[1.0, 1.1)"
+
+* *sub-property* - e.g. header;Bundle-Vendor: Acme or foo-api;-exports: org.foo
+
+The sub-property type allows values to be set that are groups of properties. The key prefix before ';' identifies the sub-property name. All keys with the same prefix contribute to the sub-property value.
+
+The -defaults mechanism allows projects to share common bundle headers and default package import versions.
+
+Most values are passed to [Bnd](http://www.aqute.biz/Code/Bnd), so Bnd syntax can usually be used, for example: -resources: @lib, to embed a library.
+
+
+## Reference
+
+| Name | Type | Description |
+|--|--|--|
+| -bundles | list | Set bundles to create. Each bundle should be defined as sub-properties prefixed with the bundle name, unless only a single bundle is defined, when the prefix can be omitted.|
+| -repositories | list | Set repositories to use. Each repository should be defined as sub-properties prefixed with the repository name.|
+| -defaults | simple | Reads in specified defaults file. If prefixed with '-' then any error reading file is ignored. Default is -../sigil-defaults.properties |
+| header;*key* | sub-property | Specify additional bundle headers. |
+| package;*key* | sub-property | Specify default Import-Package versions. e.g. package;org.osgi.framework: 1.4 |
+| bundle;*key* | sub-property | Specify default Require-Bundle versions. |
+| name | simple | Set Bundle-SymbolicName. Default is bundle id from -bundles. |
+| version | simple | Set bundle version and default export version. |
+| -activator | simple | Set bundle activator. |
+| -contents | list | Add specified packages to bundle. Defaults from -sourcedirs, or if not set -exports. |
+| -sourcedirs | list | Alternative way to specify bundle contents. |
+| -resources | list | Specify additional resources to add to bundle. Supports BND use of {} to filter files and @name.jar to embed jar from classpath. |
+| -exports | map | Set Export-Package bundle header. Export version defaults from bundle version.|
+| -requires | map | Specify Require-Bundle dependencies. |
+| -imports | map | Specify Import-Package dependencies. Sigil adds the resolve attribute:
+* resolve=compile Only use import to determine compile dependencies; do NOT add to bundle headers.
+* resolve=runtime Always add import to bundle headers (even if it appears unneeded). Do NOT generate compile dependency. |
+| -fragment | map | Set Fragment-Host bundle header. |
+| -libs | map | Add jars to bundle. Attributes:
+* kind=classpath also adds jar to Bundle-Classpath
+* kind=codebase sets Newton RMI-Codebase
+| option;*name* | sub-property | Specify Sigil options:
+* option;addMissingImports=true Let Bnd calculate imports (i.e. specify *) then update with Sigil versions. Default: true.
+* option;omitUnusedImports=true (implies addMissingImports=true) Avoids Bnd warnings when project contains multiple bundles which don't all use all imports. Default: true for projects with multiple bundles; otherwise false.|
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,8 @@
+Title: Sigil Repositories
+
+Repositories are where the external dependencies for your project live. Sigil resolves and downloads dependencies for OSGi bundles via an extensible repository interface.
+
+Current implementations provided in Sigil are:
+{children}
+
+To add a repository to your workspace go to the Eclipse preferences panel (OS specific instructions) then navigate to Sigil -> Repositories. You can add, edit or remove repositories from here.
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-filesystem.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-filesystem.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-filesystem.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-filesystem.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,3 @@
+Title: Apache Felix Sigil Filesystem
+
+The file system repository looks in a specific directory (optionally recursing through sub directories) to find OSGi bundles
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-obr.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-obr.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-obr.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-sigil/sigil-user-guide/sigil-repositories/apache-felix-sigil-obr.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,32 @@
+Title: Apache Felix Sigil OBR
+
+## Overview
+
+The OSGi Bundle Repository is an XML index to allow external tools to find out what contents an OSGi bundle provides and a link to a location where the bundle can be downloaded.
+
+You can generate your own repositories using the [bindex](http://www.osgi.org/Repository/BIndex) utility from the OSGi Alliance. If you do create your own repository and it's usable by the public let us know and we'll add it to the list below.
+
+## Available Repositories
+
+The following is a list of OBR repositories.
+- Felix Repository
+
+    http://felix.apache.org/obr/releases.xml 
+
+- Knopflerfish
+
+    http://www.knopflerfish.org/repo/bindex.xml
+
+- [OSGi Bundle Repository](http://www.osgi.org/Repository/HomePage):
+
+    http://www.osgi.org/obr/browse?cmd=repository&_xml=1
+
+- Sonatype OSGi Central
+
+    http://osgi.sonatype.org/content/groups/osgi-central-obr/.meta/obr.xml
+
+- [Spring Enterprise Bundle Repository](http://www.springsource.com/repository/app/):
+
+    http://sigil.codecauldron.org/spring-external.obr
+    http://sigil.codecauldron.org/spring-release.obr
+

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,21 @@
+Title: Apache Felix UPnP
+
+# Felix UPnP Documentation
+
+
+## Introduction&nbsp;
+
+The Felix UPnP project provides an implementation of the OSGi UPnP specification (version 1.1) as described in the [OSGi Service Compendium (Release 4)](http://www.osgi.org/Specifications/HomePage) . The specification is implemented by the *org.apache.felix.upnp.basedriver* bundle and it comes with other bundles, which have been developed to ease the writing and testing of UPnP code.
+
+The OSGi UPnP specification defines a set of interfaces which should be used by the developers in order to write UPnP Devices and UPnP Control Points on the OSGi Service Platform. From the OSGi point of view, UPnP devices are services registered with the framework, thus the different phases of the UPnP protocol stack, as defined in the [UPnP™ Device Architecture (UDA 1.0)](http://www.upnp.org/resources/documents/CleanUPnPDA101-20031202s.pdf), have been mapped to the discovery and notification mechanisms offered by the OSGi framework.
+
+The specification defines a UPnP Base Driver component that acts as software bridge between UPnP networks and OSGi. Developers writing UPnP code do not need to interact directly with the driver through some API. The driver works in background by exporting the registered services as UPnP devices, and by registering as services the UPnP devices discovered on UPnP networks. However, the Felix UPnP project has defined few additional interfaces, so a base knowledge of the way the UPnP Base Driver works is useful and will help developers to write their code.
+
+&nbsp;Table of Content:
+1. [Getting Started ]({{ refs.-upnp-getting-started.path }})
+1. [Overview of the Base Driver Architecture ]({{ refs.-upnp-driver-architecture.path }})
+1. [Testing UPnP devices ]({{ refs.-upnp-testing-devices.path }})
+1. [The UPnP examples ]({{ refs.-upnp-examples.path }})
+1. [Writing UPnP Devices and Control Points ]({{ refs.-upnp-writing-cd-and-cp.path }})
+1. [Known issues ]({{ refs.-upnp-known-issues.path }})
+1. [Acknowledgments ]({{ refs.-upnp-acknowledgments.path }})
\ No newline at end of file

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-acknowledgments.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,7 @@
+Title: UPnP Acknowledgments
+
+# Acknowledgments
+
+The Felix UPnP base driver and related bundles were originally developed by the [Domoware ](http://domoware.isti.cnr.it/) project which targeted the OSGi R3. The driver is based on a modified version of the "UPnP for Java" library released by the [Cyberlink |http://www.cybergarage.org/net/upnp/java/index.html] project. This version, called CyberDomo, is currently maintained by the Domoware project team and aligned to the Cyberlink library regularly.
+
+##### [Known Issues]({{ refs.upnp-known-issues.path }}) << 

Added: felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.mdtext
URL: http://svn.apache.org/viewvc/felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.mdtext?rev=1421893&view=auto
==============================================================================
--- felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.mdtext (added)
+++ felix/site/trunk/content/documentation/subprojects/apache-felix-upnp/upnp-driver-architecture.mdtext Fri Dec 14 14:29:22 2012
@@ -0,0 +1,45 @@
+Title: UPnP Driver architecture
+
+# Overview of the Base Driver Architecture&nbsp;
+
+The Figure 4 shows a simplified component view of the base driver. The driver is composed of two components, the *exporter* and *importer*; both using the *CyberDomo* library, which is a modified version of the library released by the ["CyberLink for Java" project](http://www.cybergarage.org/net/upnp/java/index.html ), maintained by the [Domoware project|http://domoware.isti.cnr.it/ ]. The library implements a full UPnP stack. The base driver acts as a bridge between OSGi and the UPnP networks .
+!BaseDriverArchitecture.jpg!
+*Figure 4* The UPnP Base Driver architecture
+
+In order to instantiate UPnP devices, developers must register services implementing the interfaces represented in Figure 5 and provided by the *org.osgi.compendium bundle*. The *exporter* is registered as [ServiceListener ](http://www.osgi.org/javadoc/r4/org/osgi/framework/ServiceListener.html)with the framework and it automatically exposes on the networks each [UPnPDevice |http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html]service registered with the registration property [UPNP*EXPORT|http://www.osgi.org/javadoc/r4/org/osgi/service/upnp/UPnPDevice.html#UPNP*EXPORT]. The *importer* listens to the advertisements sent on the networks by external devices and registers with the framework one or more UPnPDevice services. Even if it is not required by the specification, the devices imported by the Felix base driver are labeled with the registration property [UPNP_IMPORT|http://svn.apache.org/viewvc/felix/trunk/upnp/basedriver/src/main/java/org/apache/felix/upnp/
 basedriver/util/Constants.java?view=markup].
+!UPnPDeviceInterfaces.jpg!
+*Figure 5* The UPnP Device interfaces
+
+Working with UPnP Device from the OSGi point of view means to operate with services; the discovery, controlling and eventing phases of the UPnP protocol are naturally mapped to the OSGi service layer, which allows to publish, find, bind and notify events. There are some aspects that make it different to work with UPnP in OSGi with respect to other UPnP libraries, due basically to the centralized nature of the OSGi registry opposed to the distributed approach used in UPnP networks; some hints are provided in the section "Writing UPnP Devices and Control Points"
+
+The Felix base driver comes with some system properties you can use to configure it at startup.
+
+The system properties:
+• *cyberdomo.ssdp.mx* (default 5)
+• *cyberdomo.ssdp.buffersize* (default 2048)
+• *cyberdomo.ssdp.port* (default 1900)
+
+are used by the UPnP stack library during the UPnP discovery process. The paper "[Adaptive Jitter Control for UPnP M-Search](http://w3.antd.nist.gov/~mills/papers/Paper521.pdf)" \[1\] provides a good analysis of the tuning of such parameters related to scalability issues. The MX parameter default has been set to 5 sec. Higher values improve the discovery effectiveness but increase the latency for new device discovery. The Intel "[Device Spy|http://www.intel.com/cd/ids/developer/asmo-na/eng/downloads/upnp/index.htm]" tool uses a delay of 10 sec, the "CyberLink for Java" library 3 sec. The SSDP port in UPnP specification is by default 1900 we allow the modification of such parameter.
+
+The following system properties:
+• *felix.upnpbase.exporter.enabled* (default true)
+• *felix.upnpbase.importer.enabled* (default true)
+
+can be used to enable or disable the two main components of the base driver. For example with small devices (ARM-based processor), disabling the exporting or importing of devices might reduce the resource consumption.
+
+• *felix.upnpbase.log* (default 2)
+• *felix.upnpbase.cyberdomo.log* (default false)
+
+are properties used to enable the different logging facilities offered by the base driver. You can also modify them at run time by using the GUI provided by the UPnP Tester bundle
+
+Finally the following properties are used to set the networking parameters. The loopback interface is usually disabled :
+
+• *felix.upnpbase.cyberdomo.net.loopback* (default false)
+• *felix.upnpbase.cyberdomo.net.onlyIPV4* (default true)
+• *felix.upnpbase.cyberdomo.net.onlyIPV6* (default false)
+
+##### [Getting Started]({{ refs.upnp-getting-started.path }}) << \| >> [Testing UPnP Devices| UPnP Testing Devices]
+
+
+----
+\[1\]({{ refs.1.path }}) K. Mills, C. Dabrowski "Adaptive Jitter Control for UPnP M-Search" IEEE International Conference on Communications, 2003. ICC '03. page(s): 1008\- 1013 vol.2 
\ No newline at end of file



Mime
View raw message