incubator-aries-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From z..@apache.org
Subject svn commit: r1040087 [2/5] - in /incubator/aries/branches/site: branches/ images/ resources/ trunk/ trunk/cgi-bin/ trunk/content/ trunk/content/images/ trunk/content/resources/ trunk/lib/ trunk/templates/
Date Mon, 29 Nov 2010 12:32:25 GMT
Added: incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,62 @@
+h1. The Blog Sample - version 0.1-incubating.
+
+
+h2. Running the Blog Sample
+
+
+h3. Prereqs
+
+Follow the instructions [here|http://db.apache.org/derby/papers/DerbyTut/install_software.html#derby] to complete the following actions: Download Derby, Install Derby, Set DERBY_INSTALL, Configure Embedded Derby and then Verify Derby. 
+{note}
+The version of Derby used by the current release and development versions of the Blog Sample is 10.5.3.0. Since May 2010 the Derby tutorial points to the latest Derby release (10.6.x) - if this is installed the Blog sample will not work. See [ARIES-317|https://issues.apache.org/jira/browse/ARIES-317]. For the present the best solution is to install Derby 10.5.3.
+{note}
+
+h3. Create the OSGi platform for the Blog sample
+
+Download and unzip the source zip for the [latest release|ARIES:Downloads] of Aries Samples and build the blog-assembly module:
+{code}
+cd samples-0.1-incubating/blog/blog-assembly
+mvn install
+{code}
+This procedure will pull in the binaries from the latest release and its dependencies.
+
+h3. Running the Blog sample
+
+Download the JDBC based Blog sample application (.eba file) from the [latest release|ARIES:Downloads].
+
+Create the database
+{code}
+cd samples-0.1-incubating/blog-sample/blog-assembly/target
+export CLASSPATH=$DERBY_INSTALL/lib/derby.jar:$DERBY_INSTALL/lib/derbytools.jar:.
+java org.apache.derby.tools.ij blogDB.sql
+{code}
+now start Aries in an OSGi framework (we're using Eclipse Equinox in this case)
+{code}
+java -jar osgi-3.5.0.v20090520.jar -console
+{code}
+
+The OSGi console should start up, the 'ss' command should show all of the Blog bundles in state 'ACTIVE'.
+
+Now start the blog application (.eba file) you downloaded earlier, by copying it into the load directory which was created when Aries started.
+
+Point your browser to [http://localhost:8080/org.apache.aries.samples.blog.web/]
+
+If you subsequently delete the .eba from the load directory the application will be uninstalled.
+
+h3. Running the sample using a JPA persistence layer
+
+The first blog sample application was written to use a JDBC persistence layer. There is a second application implemented to demonstrate the JPA capability
+
+To run the blog sample which uses the JPA persistence layer, start the OSGi framework, remove any previous copies of the blog sample from the target/load directory, then copy the Blog sample JPA .eba file into the load directory.
+
+Finally, after typing 'refresh' at the OSGi console, point your browser at [http://localhost:8080/org.apache.aries.samples.blog.web/]. You should see something that looks precisely the same as the blog sample running with the JDBC persistence layer, but this time running using the JPA persistence layer.
+
+h2. Using the latest, unreleased code
+
+If you prefer to use the very latest code from subversion, checkout and build the Aries trunk by following the [Building Aries instructions|ARIES:BuildingAries].
+
+h2. About the Blog sample
+
+The blog sample components can be visualised like this:
+
+!BlogSample.png!
\ No newline at end of file

Added: incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/blogsample-0.1-incubating.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,95 @@
+Title: BlogSample-0.1-incubating
+<a name="BlogSample-0.1-incubating-TheBlogSample-version0.1-incubating."></a>
+# The Blog Sample - version 0.1-incubating.
+
+
+<a name="BlogSample-0.1-incubating-RunningtheBlogSample"></a>
+## Running the Blog Sample
+
+
+<a name="BlogSample-0.1-incubating-Prereqs"></a>
+### Prereqs
+
+Follow the instructions [here](http://db.apache.org/derby/papers/DerbyTut/install_software.html#derby)
+ to complete the following actions: Download Derby, Install Derby, Set
+DERBY_INSTALL, Configure Embedded Derby and then Verify Derby. 
+{note}
+The version of Derby used by the current release and development versions
+of the Blog Sample is 10.5.3.0. Since May 2010 the Derby tutorial points to
+the latest Derby release (10.6.x) - if this is installed the Blog sample
+will not work. See [ARIES-317](https://issues.apache.org/jira/browse/ARIES-317)
+. For the present the best solution is to install Derby 10.5.3.
+{note}
+
+<a name="BlogSample-0.1-incubating-CreatetheOSGiplatformfortheBlogsample"></a>
+### Create the OSGi platform for the Blog sample
+
+Download and unzip the source zip for the [latest release](aries:downloads.html)
+ of Aries Samples and build the blog-assembly module:
+{code}
+cd samples-0.1-incubating/blog/blog-assembly
+mvn install
+{code}
+This procedure will pull in the binaries from the latest release and its
+dependencies.
+
+<a name="BlogSample-0.1-incubating-RunningtheBlogsample"></a>
+### Running the Blog sample
+
+Download the JDBC based Blog sample application (.eba file) from the [latest release](aries:downloads.html)
+.
+
+Create the database
+{code}
+cd samples-0.1-incubating/blog-sample/blog-assembly/target
+export
+CLASSPATH=$DERBY_INSTALL/lib/derby.jar:$DERBY_INSTALL/lib/derbytools.jar:.
+java org.apache.derby.tools.ij blogDB.sql
+{code}
+now start Aries in an OSGi framework (we're using Eclipse Equinox in this
+case)
+{code}
+java -jar osgi-3.5.0.v20090520.jar -console
+{code}
+
+The OSGi console should start up, the 'ss' command should show all of the
+Blog bundles in state 'ACTIVE'.
+
+Now start the blog application (.eba file) you downloaded earlier, by
+copying it into the load directory which was created when Aries started.
+
+Point your browser to [http://localhost:8080/org.apache.aries.samples.blog.web/](http://localhost:8080/org.apache.aries.samples.blog.web/)
+
+If you subsequently delete the .eba from the load directory the application
+will be uninstalled.
+
+<a name="BlogSample-0.1-incubating-RunningthesampleusingaJPApersistencelayer"></a>
+### Running the sample using a JPA persistence layer
+
+The first blog sample application was written to use a JDBC persistence
+layer. There is a second application implemented to demonstrate the JPA
+capability
+
+To run the blog sample which uses the JPA persistence layer, start the OSGi
+framework, remove any previous copies of the blog sample from the
+target/load directory, then copy the Blog sample JPA .eba file into the
+load directory.
+
+Finally, after typing 'refresh' at the OSGi console, point your browser at [http://localhost:8080/org.apache.aries.samples.blog.web/](http://localhost:8080/org.apache.aries.samples.blog.web/)
+. You should see something that looks precisely the same as the blog sample
+running with the JDBC persistence layer, but this time running using the
+JPA persistence layer.
+
+<a name="BlogSample-0.1-incubating-Usingthelatest,unreleasedcode"></a>
+## Using the latest, unreleased code
+
+If you prefer to use the very latest code from subversion, checkout and
+build the Aries trunk by following the [Building Aries instructions](aries:buildingaries.html)
+.
+
+<a name="BlogSample-0.1-incubating-AbouttheBlogsample"></a>
+## About the Blog sample
+
+The blog sample components can be visualised like this:
+
+!BlogSample.png!

Added: incubator/aries/branches/site/trunk/content/blueprint.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprint.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprint.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/blueprint.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,343 @@
+h1. Blueprint
+
+h2. Introduction
+
+Blueprint provides a dependency injection framework for OSGi and was standardized by the OSGi Alliance in OSGi Compendium R4.2. It is designed to deal with the dynamic nature of OSGi, where services can become available and unavailable at any time. The specification is also designed to work with plain old Java objects (POJOs) enabling simple components to be written and unit tested in a JSE environment without needing to be aware of how they are assembled. The Blueprint XML files that define and describe the assembly of various components are key to the Blueprint programming model. The specification describes how the components get instantiated and wired together to form a running module. 
+
+The following documentation covers the 80:20 usage of Blueprint.  For further details, please refer to the OSGi Compendium R4.2 specification.
+
+
+h2.  Blueprint Bundles
+
+The Blueprint Container specification uses an extender pattern, whereby an extender bundle monitors the state of bundles in the framework and performs actions on behalf of those bundles based on their state. The Blueprint extender bundle waits for the bundles to be activated and checks whether they are Blueprint bundles. A bundle is considered to be a Blueprint bundle when it contains one or more Blueprint XML files. These XML files are at a fixed location under the OSGI-INF/blueprint/ directory or are specified explicitly in the Bundle-Blueprint manifest header.
+
+Once the extender determines that a bundle is a Blueprint bundle, it creates a Blueprint Container on behalf of that bundle. The Blueprint Container is responsible for:
+
+    * Parsing the Blueprint XML files
+    * Instantiating the components
+    * Wiring the components together
+    * Registering services
+    * Looking up service references
+
+During initialization, the Blueprint Container ensures that mandatory service references are satisfied, registers all the services into the service registry, and creates initial component instances. The Blueprint extender bundle also destroys the Blueprint Container for a bundle when the bundle is stopped. 
+
+h2.  Blueprint XML
+
+The Blueprint XML file is identified by a top-level blueprint element, as shown below:
+
+{code:xml|title=blueprint.xml|borderStyle=solid}
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+    ...
+</blueprint>
+{code} 
+
+The XML namespace identifies the document as conforming to the Blueprint version 1.0.0.  The top-level blueprint element identifies the document as a blueprint module definition.
+
+*TODO:* ensure id, activation and dependsOn get documented somewhere.
+
+
+h2.  Beans
+
+Beans are declared using the bean element.  The following defines a single bean called {{accountOne}} implemented by the POJO {{org.apache.aries.simple.Account}}.
+
+{code:xml|title=bean.xml|borderStyle=solid}
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+   <bean id="accountOne" class="org.apache.aries.simple.Account" />
+</blueprint>
+{code} 
+
+h3.  Bean Construction
+
+During object construction, the Blueprint Container must first find the right constructor or a factory method with a compatible set of parameters that matches the arguments specified in the XML. By default, the Blueprint Container uses the number and order of the argument elements in XML to find the right constructor or method. If the argument  elements cannot be mapped to the parameters in the order they are in, the Blueprint Container will attempt to reorder the argument elements and find the best-fitting arrangement.
+
+To help the Blueprint Container pick the right constructor, method, or parameter arrangement, additional attributes, such as index or type, can be specified on the argument element. For example, the type attribute specifies a class name used to match the argument element to a parameter by the exact type. 
+
+A bean can be constructed using a class constructor. In the following example, the {{class}} attribute specifies the name of the Java class to instantiate. The Blueprint Container will create the {{Account}} object by passing {{1}} as the argument to the constructor. 
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account(long number) {
+          ...
+       }
+       ...
+   }
+{code} 
+
+{code:xml|title=constructor.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <argument value="1"/>
+   </bean>
+{code} 
+
+
+A bean can be constructed using a static factory method.  In this example, the {{class}} attribute specifies the name of the class that contains a static factory method. The name of the static factory method is specified by the {{factory-method}}  attribute. The Blueprint Container will call the {{createAccount()}} static method on the {{StaticAccountFactory}} class and pass 2 as the argument to create the Account object. 
+
+{code:java|title=StaticAccountFactory.java|borderStyle=solid}
+   public class StaticAccountFactory {      
+       public static Account createAccount(long number) {
+          return new Account(number);
+       }
+   }
+{code} 
+
+{code:xml|title=staticfactory.xml|borderStyle=solid}
+   <bean id="accountTwo" class="org.apache.aries.simple.StaticAccountFactory" 
+         factory-method="createAccount">   
+       <argument value="2"/>
+   </bean>
+{code} 
+
+A bean can be constructed using an instance factory method.  In the example, the {{accountFactory}} bean is the factory. The Blueprint Container will first create the {{AccountFactory}} instance with its own arguments and properties. In this case, only a single argument is specified: the factory name. The Blueprint Container will then call the {{createAccount()}} method on the {{AccountFactory}} instance and pass 3 as the argument to create the Account object.
+
+{code:java|title=AccountFactory.java|borderStyle=solid}
+   public class AccountFactory {      
+       public AccountFactory(String factoryName) {
+          ...
+       }
+       public Account createAccount(long number) {
+          return new Account(number);
+       }
+   }
+
+{code} 
+
+{code:xml|title=instancefactory.xml|borderStyle=solid}
+   <bean id="accountFactory" class="org.apache.aries.simple.AccountFactory">  
+       <argument value="account factory"/>      
+   </bean>
+
+   <bean id="accountThree"
+         factory-ref="accountFactory" 
+         factory-method="createAccount">   
+       <argument value="3"/>
+   </bean>
+{code} 
+
+h3.  Bean Properties
+
+Beans can have property values injected.  Injection is performed immediately after the bean is constructed.  The following example creates the Account bean and then sets the description property using the Java Beans naming convention.
+
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account(long number) {
+          ...
+       }
+       public String getDescription() {
+          ...
+       }
+   }
+{code} 
+
+{code:xml|title=constructor.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <argument value="1"/>
+       <property name="description" value="#1 account"/>
+   </bean>
+{code}
+
+h4. Bean Wiring
+
+Property injection is used for wiring beans together.  In the following example {{accountOne}} is injected with a {{Currency}} bean.
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account() {
+          ...
+       }
+       public void setCurrency(Currency currency) {
+          ...
+       }
+   }
+{code} 
+
+{code:java|title=Currency.java|borderStyle=solid}
+   public class Currency {      
+       public Currency() {
+          ...
+       }
+   }
+{code} 
+
+{code:xml|title=properties.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <property name="currency" ref="currency" />
+   </bean>
+
+   <bean id="currency" class="org.apache.aries.simple.Currency" />
+{code}
+
+
+
+h2.  Services
+
+In Blueprint XML, a service element defines the registration of a service in the OSGi service registry. 
+
+The bean that provides the service object can be referenced using the {{ref}} attribute.  The interfaces under which the service is registered can be specified using the {{interface}} attribute:
+
+{code:java|title=AccountImpl.java|borderStyle=solid}
+   public class AccountImpl implements Account {      
+       public Account() {
+          ...
+       }
+       public void setCurrency(Currency currency) {
+          ...
+       }
+   }
+{code} 
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceOne" ref="account" interface="org.apache.aries.simple.Account" />
+
+   <bean id="account" class="org.apache.aries.simple.AccountImpl" />
+{code}
+
+The bean that provides the service object can be inlined in the service element as follows:
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceTwo"  interface="org.apache.aries.simple.Account">
+      <bean class="org.apache.aries.simple.AccountImpl" />
+   </service>
+{code}
+
+The interfaces under which a service is registered can be determined by Blueprint using {{auto-export}}.  The following registers the service under all the bean's interfaces:
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceOne" ref="account" auto-export="interfaces" />
+
+   <bean id="account" class="org.apache.aries.simple.AccountImpl" />
+{code}
+
+Other values for {{auto-export}} are {{disabled}} (the default) {{class-hierarchy}} and {{all-classes}}.
+
+h3. Service Properties
+
+A service can also be registered with a set of properties that can be specified using the {{service-properties}}  sub-element. The {{service-properties}} element contains multiple {{entry}} sub-elements that represent the individual properties. The property key is specified using a {{key}} attribute, but the property value can be specified as a {{value}} attribute or inlined within the element. The service property values can be of different types, but only OSGi service property types are permitted: primitives, primitive wrapper classes, collections, or arrays of primitive types. 
+
+The following is an example of a service registration with two service properties. The {{active}} service property has type of {{java.lang.Boolean}}. The {{mode}} property is of the default type, {{String}}. 
+
+{code:xml|title=serviceproperties.xml|borderStyle=solid}
+   <service id="serviceFour" ref="account" autoExport="all-classes">
+      <service-properties>
+          <entry key="active">
+              <value type="java.lang.Boolean">true</value>
+          </entry>
+          <entry key="mode" value="shared"/>
+      </service-properties>
+   </service>
+{code}
+
+h3. Service Ranking
+
+Service ranking can be used to affect the choice of service when there are multiple matches.  When choosing between two services, the higher ranked service will be returned ahead of the lower.  The default ranking value is 0. Service ranking is specified using the {{ranking}} attributes as follows:
+
+{code:xml|title=serviceranking.xml|borderStyle=solid}
+   <service id="serviceFive" ref="account" auto-export="all-classes" ranking="3" />
+{code}
+
+
+h2. References
+
+Services are found in the service registry using the reference element. The following shows a reference named {{accountRef}} to an {{Account}} service.  If a service matching this reference is found in the service registry then it is set on the {{accountClient}} bean through the {{account}} property.
+
+{code:xml|title=servicereference.xml|borderStyle=solid}
+   <bean id="accountClient" class="...">
+       <property name="account" ref="accountRef" />
+   </bean>
+
+   <reference id="accountRef" interface="org.apache.aries.simple.Account" /> 
+{code}
+
+h3. Reference Dynamism
+
+The object that is injected for a reference is actually a proxy to the service registered in the service registry. A proxy enables the injected object to remain the same while the backing service can come and go or be replaced with another service. Calls on a proxy that does not have a backing service will block until a service becomes available or a timeout occurs at which point a ServiceUnavailableException will be thrown.
+
+{code:java|title=AccountClient.java|borderStyle=solid}
+   try {
+      balance = account.getBalance();
+   } catch (ServiceUnavailableException e) {
+      ...
+   }
+{code} 
+
+The default timeout Blueprint will wait for is 300000 milliseconds (5 minutes).  This value can be changed on a per bundle basis using directives on the Bundle-SymbolicName.  The following switches the timeout off completely (the default is true):
+
+{code:java|title=MANIFEST.MF|borderStyle=solid}
+   Bundle-SymbolicName: org.apache.aries.simple.account; blueprint.graceperiod:=false
+{code} 
+
+The following sets the timeout to 10000 milliseconds (10 seconds):
+
+{code:java|title=MANIFEST.MF|borderStyle=solid}
+   Bundle-SymbolicName: org.apache.aries.simple.account; blueprint.graceperiod:=false; blueprint.timeout=10000;
+{code} 
+
+The timeout can also be set on an individual reference using the {{timeout}} attribute.  The following sets the timeout for the account reference to 20000 milliseconds (20 seconds).
+
+{code:xml|title=servicereference.xml|borderStyle=solid}
+   <reference id="accountRef" timeout="20000" interface="org.apache.aries.simple.Account" /> 
+{code}
+
+In all cases, a value of 0 means wait indefinitely for the reference to become satisfied.
+
+h3. Reference Lists
+
+Multiple matching services can be found using the {{reference-list}} element.  The {{reference-list}} provides a {{List}} object that contains the service proxy objects or {{ServiceReference}} objects, depending on the {{member-type}} setting. The provided {{List}} object is dynamic, as it can grow and shrink as matching services are added or removed from the service registry. The {{List}} object is read-only and only supports a subset of the {{List}} API.
+
+The proxies in a {{reference-list}} are different from the proxies for a reference. The {{reference-list}} proxies target a specific service, do not have a {{timeout}}, and throw {{ServiceUnavailableException}} immediately if their service becomes unavailable.
+
+The following example shows a reference-list that returns a list of service objects (proxies).  This is the default value for the {{member-type}} attribute
+
+{code:xml|title=referencelist.xml|borderStyle=solid}
+   <reference-list id="accountRefs" member-type="service-object" interface="org.apache.aries.simple.Account" /> 
+{code}
+
+The following shows an example of a reference-list that returns a list of ServiceReferences:
+
+{code:xml|title=referencelist.xml|borderStyle=solid}
+   <reference-list id="accountRefs" member-type="service-reference" interface="org.apache.aries.simple.Account" /> 
+{code}
+
+Example showing mandatory or optional references (availability)
+
+Example showing use of filter
+
+h2. Bean Properties
+
+Example showing use of bean properties
+
+h2. Scopes
+
+Example showing singleton scope
+
+Example showing prototype scope for beans
+
+Example showing prototype scope for services
+
+h2. Object Values
+
+Intro to Object Values
+
+Examples showing the use of the various different object value types - ref, map, props collection (list, array, set).
+
+h2.  Lifecycle
+
+Example showing use of init/destroy-method
+
+h2.  Lazy and Eager Activiation
+
+Example showing lazy activiation.
+
+Example showing eager activation.
+
+h2.  Dynamism
+
+Example showing service-listener
+
+Example showing reference-listener
+
+h2.  Type Converters
+
+

Added: incubator/aries/branches/site/trunk/content/blueprint.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprint.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprint.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/blueprint.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,481 @@
+Title: Blueprint
+<a name="Blueprint-Blueprint"></a>
+# Blueprint
+
+<a name="Blueprint-Introduction"></a>
+## Introduction
+
+Blueprint provides a dependency injection framework for OSGi and was
+standardized by the OSGi Alliance in OSGi Compendium R4.2. It is designed
+to deal with the dynamic nature of OSGi, where services can become
+available and unavailable at any time. The specification is also designed
+to work with plain old Java objects (POJOs) enabling simple components to
+be written and unit tested in a JSE environment without needing to be aware
+of how they are assembled. The Blueprint XML files that define and describe
+the assembly of various components are key to the Blueprint programming
+model. The specification describes how the components get instantiated and
+wired together to form a running module. 
+
+The following documentation covers the 80:20 usage of Blueprint.  For
+further details, please refer to the OSGi Compendium R4.2 specification.
+
+
+<a name="Blueprint-BlueprintBundles"></a>
+##  Blueprint Bundles
+
+The Blueprint Container specification uses an extender pattern, whereby an
+extender bundle monitors the state of bundles in the framework and performs
+actions on behalf of those bundles based on their state. The Blueprint
+extender bundle waits for the bundles to be activated and checks whether
+they are Blueprint bundles. A bundle is considered to be a Blueprint bundle
+when it contains one or more Blueprint XML files. These XML files are at a
+fixed location under the OSGI-INF/blueprint/ directory or are specified
+explicitly in the Bundle-Blueprint manifest header.
+
+Once the extender determines that a bundle is a Blueprint bundle, it
+creates a Blueprint Container on behalf of that bundle. The Blueprint
+Container is responsible for:
+
+    * Parsing the Blueprint XML files
+    * Instantiating the components
+    * Wiring the components together
+    * Registering services
+    * Looking up service references
+
+During initialization, the Blueprint Container ensures that mandatory
+service references are satisfied, registers all the services into the
+service registry, and creates initial component instances. The Blueprint
+extender bundle also destroys the Blueprint Container for a bundle when the
+bundle is stopped. 
+
+<a name="Blueprint-BlueprintXML"></a>
+##  Blueprint XML
+
+The Blueprint XML file is identified by a top-level blueprint element, as
+shown below:
+
+{code:xml|title=blueprint.xml|borderStyle=solid}
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+    ...
+</blueprint>
+{code} 
+
+The XML namespace identifies the document as conforming to the Blueprint
+version 1.0.0.	The top-level blueprint element identifies the document as
+a blueprint module definition.
+
+*TODO:* ensure id, activation and dependsOn get documented somewhere.
+
+
+<a name="Blueprint-Beans"></a>
+##  Beans
+
+Beans are declared using the bean element.  The following defines a single
+bean called *accountOne* implemented by the POJO
+*org.apache.aries.simple.Account*.
+
+{code:xml|title=bean.xml|borderStyle=solid}
+<?xml version="1.0" encoding="UTF-8"?>
+<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
+   <bean id="accountOne" class="org.apache.aries.simple.Account" />
+</blueprint>
+{code} 
+
+<a name="Blueprint-BeanConstruction"></a>
+###  Bean Construction
+
+During object construction, the Blueprint Container must first find the
+right constructor or a factory method with a compatible set of parameters
+that matches the arguments specified in the XML. By default, the Blueprint
+Container uses the number and order of the argument elements in XML to find
+the right constructor or method. If the argument  elements cannot be mapped
+to the parameters in the order they are in, the Blueprint Container will
+attempt to reorder the argument elements and find the best-fitting
+arrangement.
+
+To help the Blueprint Container pick the right constructor, method, or
+parameter arrangement, additional attributes, such as index or type, can be
+specified on the argument element. For example, the type attribute
+specifies a class name used to match the argument element to a parameter by
+the exact type. 
+
+A bean can be constructed using a class constructor. In the following
+example, the *class* attribute specifies the name of the Java class to
+instantiate. The Blueprint Container will create the *Account* object by
+passing *1* as the argument to the constructor. 
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account(long number) {
+	  ...
+       }
+       ...
+   }
+{code} 
+
+{code:xml|title=constructor.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <argument value="1"/>
+   </bean>
+{code} 
+
+
+A bean can be constructed using a static factory method.  In this example,
+the *class* attribute specifies the name of the class that contains a
+static factory method. The name of the static factory method is specified
+by the *factory-method*  attribute. The Blueprint Container will call the
+*createAccount()* static method on the *StaticAccountFactory* class and
+pass 2 as the argument to create the Account object. 
+
+{code:java|title=StaticAccountFactory.java|borderStyle=solid}
+   public class StaticAccountFactory {	    
+       public static Account createAccount(long number) {
+	  return new Account(number);
+       }
+   }
+{code} 
+
+{code:xml|title=staticfactory.xml|borderStyle=solid}
+   <bean id="accountTwo"
+class="org.apache.aries.simple.StaticAccountFactory" 
+	 factory-method="createAccount">   
+       <argument value="2"/>
+   </bean>
+{code} 
+
+A bean can be constructed using an instance factory method.  In the
+example, the *accountFactory* bean is the factory. The Blueprint
+Container will first create the *AccountFactory* instance with its own
+arguments and properties. In this case, only a single argument is
+specified: the factory name. The Blueprint Container will then call the
+*createAccount()* method on the *AccountFactory* instance and pass 3 as
+the argument to create the Account object.
+
+{code:java|title=AccountFactory.java|borderStyle=solid}
+   public class AccountFactory {      
+       public AccountFactory(String factoryName) {
+	  ...
+       }
+       public Account createAccount(long number) {
+	  return new Account(number);
+       }
+   }
+
+{code} 
+
+{code:xml|title=instancefactory.xml|borderStyle=solid}
+   <bean id="accountFactory"
+class="org.apache.aries.simple.AccountFactory">  
+       <argument value="account factory"/>	
+   </bean>
+
+   <bean id="accountThree"
+	 factory-ref="accountFactory" 
+	 factory-method="createAccount">   
+       <argument value="3"/>
+   </bean>
+{code} 
+
+<a name="Blueprint-BeanProperties"></a>
+###  Bean Properties
+
+Beans can have property values injected.  Injection is performed
+immediately after the bean is constructed.  The following example creates
+the Account bean and then sets the description property using the Java
+Beans naming convention.
+
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account(long number) {
+	  ...
+       }
+       public String getDescription() {
+	  ...
+       }
+   }
+{code} 
+
+{code:xml|title=constructor.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <argument value="1"/>
+       <property name="description" value="#1 account"/>
+   </bean>
+{code}
+
+<a name="Blueprint-BeanWiring"></a>
+#### Bean Wiring
+
+Property injection is used for wiring beans together.  In the following
+example *accountOne* is injected with a *Currency* bean.
+
+{code:java|title=Account.java|borderStyle=solid}
+   public class Account {      
+       public Account() {
+	  ...
+       }
+       public void setCurrency(Currency currency) {
+	  ...
+       }
+   }
+{code} 
+
+{code:java|title=Currency.java|borderStyle=solid}
+   public class Currency {	
+       public Currency() {
+	  ...
+       }
+   }
+{code} 
+
+{code:xml|title=properties.xml|borderStyle=solid}
+   <bean id="accountOne" class="org.apache.aries.simple.Account">
+       <property name="currency" ref="currency" />
+   </bean>
+
+   <bean id="currency" class="org.apache.aries.simple.Currency" />
+{code}
+
+
+
+<a name="Blueprint-Services"></a>
+##  Services
+
+In Blueprint XML, a service element defines the registration of a service
+in the OSGi service registry. 
+
+The bean that provides the service object can be referenced using the
+*ref* attribute.  The interfaces under which the service is registered
+can be specified using the *interface* attribute:
+
+{code:java|title=AccountImpl.java|borderStyle=solid}
+   public class AccountImpl implements Account {      
+       public Account() {
+	  ...
+       }
+       public void setCurrency(Currency currency) {
+	  ...
+       }
+   }
+{code} 
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceOne" ref="account"
+interface="org.apache.aries.simple.Account" />
+
+   <bean id="account" class="org.apache.aries.simple.AccountImpl" />
+{code}
+
+The bean that provides the service object can be inlined in the service
+element as follows:
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceTwo"  interface="org.apache.aries.simple.Account">
+      <bean class="org.apache.aries.simple.AccountImpl" />
+   </service>
+{code}
+
+The interfaces under which a service is registered can be determined by
+Blueprint using *auto-export*.  The following registers the service under
+all the bean's interfaces:
+
+{code:xml|title=service.xml|borderStyle=solid}
+   <service id="serviceOne" ref="account" auto-export="interfaces" />
+
+   <bean id="account" class="org.apache.aries.simple.AccountImpl" />
+{code}
+
+Other values for *auto-export* are *disabled* (the default)
+*class-hierarchy* and *all-classes*.
+
+<a name="Blueprint-ServiceProperties"></a>
+### Service Properties
+
+A service can also be registered with a set of properties that can be
+specified using the *service-properties*  sub-element. The
+*service-properties* element contains multiple *entry* sub-elements
+that represent the individual properties. The property key is specified
+using a *key* attribute, but the property value can be specified as a
+*value* attribute or inlined within the element. The service property
+values can be of different types, but only OSGi service property types are
+permitted: primitives, primitive wrapper classes, collections, or arrays of
+primitive types. 
+
+The following is an example of a service registration with two service
+properties. The *active* service property has type of
+*java.lang.Boolean*. The *mode* property is of the default type,
+*String*. 
+
+{code:xml|title=serviceproperties.xml|borderStyle=solid}
+   <service id="serviceFour" ref="account" autoExport="all-classes">
+      <service-properties>
+	  <entry key="active">
+	      <value type="java.lang.Boolean">true</value>
+	  </entry>
+	  <entry key="mode" value="shared"/>
+      </service-properties>
+   </service>
+{code}
+
+<a name="Blueprint-ServiceRanking"></a>
+### Service Ranking
+
+Service ranking can be used to affect the choice of service when there are
+multiple matches.  When choosing between two services, the higher ranked
+service will be returned ahead of the lower.  The default ranking value is
+0. Service ranking is specified using the *ranking* attributes as
+follows:
+
+{code:xml|title=serviceranking.xml|borderStyle=solid}
+   <service id="serviceFive" ref="account" auto-export="all-classes"
+ranking="3" />
+{code}
+
+
+<a name="Blueprint-References"></a>
+## References
+
+Services are found in the service registry using the reference element. The
+following shows a reference named *accountRef* to an *Account* service.
+ If a service matching this reference is found in the service registry then
+it is set on the *accountClient* bean through the *account* property.
+
+{code:xml|title=servicereference.xml|borderStyle=solid}
+   <bean id="accountClient" class="...">
+       <property name="account" ref="accountRef" />
+   </bean>
+
+   <reference id="accountRef" interface="org.apache.aries.simple.Account"
+/> 
+{code}
+
+<a name="Blueprint-ReferenceDynamism"></a>
+### Reference Dynamism
+
+The object that is injected for a reference is actually a proxy to the
+service registered in the service registry. A proxy enables the injected
+object to remain the same while the backing service can come and go or be
+replaced with another service. Calls on a proxy that does not have a
+backing service will block until a service becomes available or a timeout
+occurs at which point a ServiceUnavailableException will be thrown.
+
+{code:java|title=AccountClient.java|borderStyle=solid}
+   try {
+      balance = account.getBalance();
+   } catch (ServiceUnavailableException e) {
+      ...
+   }
+{code} 
+
+The default timeout Blueprint will wait for is 300000 milliseconds (5
+minutes).  This value can be changed on a per bundle basis using directives
+on the Bundle-SymbolicName.  The following switches the timeout off
+completely (the default is true):
+
+{code:java|title=MANIFEST.MF|borderStyle=solid}
+   Bundle-SymbolicName: org.apache.aries.simple.account;
+blueprint.graceperiod:=false
+{code} 
+
+The following sets the timeout to 10000 milliseconds (10 seconds):
+
+{code:java|title=MANIFEST.MF|borderStyle=solid}
+   Bundle-SymbolicName: org.apache.aries.simple.account;
+blueprint.graceperiod:=false; blueprint.timeout=10000;
+{code} 
+
+The timeout can also be set on an individual reference using the
+*timeout* attribute.	The following sets the timeout for the account
+reference to 20000 milliseconds (20 seconds).
+
+{code:xml|title=servicereference.xml|borderStyle=solid}
+   <reference id="accountRef" timeout="20000"
+interface="org.apache.aries.simple.Account" /> 
+{code}
+
+In all cases, a value of 0 means wait indefinitely for the reference to
+become satisfied.
+
+<a name="Blueprint-ReferenceLists"></a>
+### Reference Lists
+
+Multiple matching services can be found using the *reference-list*
+element.  The *reference-list* provides a *List* object that contains
+the service proxy objects or *ServiceReference* objects, depending on the
+*member-type* setting. The provided *List* object is dynamic, as it can
+grow and shrink as matching services are added or removed from the service
+registry. The *List* object is read-only and only supports a subset of
+the *List* API.
+
+The proxies in a *reference-list* are different from the proxies for a
+reference. The *reference-list* proxies target a specific service, do not
+have a *timeout*, and throw *ServiceUnavailableException* immediately
+if their service becomes unavailable.
+
+The following example shows a reference-list that returns a list of service
+objects (proxies).  This is the default value for the *member-type*
+attribute
+
+{code:xml|title=referencelist.xml|borderStyle=solid}
+   <reference-list id="accountRefs" member-type="service-object"
+interface="org.apache.aries.simple.Account" /> 
+{code}
+
+The following shows an example of a reference-list that returns a list of
+ServiceReferences:
+
+{code:xml|title=referencelist.xml|borderStyle=solid}
+   <reference-list id="accountRefs" member-type="service-reference"
+interface="org.apache.aries.simple.Account" /> 
+{code}
+
+Example showing mandatory or optional references (availability)
+
+Example showing use of filter
+
+<a name="Blueprint-BeanProperties"></a>
+## Bean Properties
+
+Example showing use of bean properties
+
+<a name="Blueprint-Scopes"></a>
+## Scopes
+
+Example showing singleton scope
+
+Example showing prototype scope for beans
+
+Example showing prototype scope for services
+
+<a name="Blueprint-ObjectValues"></a>
+## Object Values
+
+Intro to Object Values
+
+Examples showing the use of the various different object value types - ref,
+map, props collection (list, array, set).
+
+<a name="Blueprint-Lifecycle"></a>
+##  Lifecycle
+
+Example showing use of init/destroy-method
+
+<a name="Blueprint-LazyandEagerActiviation"></a>
+##  Lazy and Eager Activiation
+
+Example showing lazy activiation.
+
+Example showing eager activation.
+
+<a name="Blueprint-Dynamism"></a>
+##  Dynamism
+
+Example showing service-listener
+
+Example showing reference-listener
+
+<a name="Blueprint-TypeConverters"></a>
+##  Type Converters
+
+

Added: incubator/aries/branches/site/trunk/content/blueprintannotation.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprintannotation.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprintannotation.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/blueprintannotation.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,185 @@
+h1. Introduction
+
+Blueprint annotation is being prototyped in Apache Aries in trunk/blueprint.   The blueprint annotation service is an optional service to the blueprint core and should not affect the blueprint core if annotation supported is not required.   If the blueprint annotation service is available, the bundle contains no blueprint definition XML and the bundle contains the manifest header {{Bundle-Blueprint-Annotation}} with the value set to true, the blueprint annotation service will attempt to scan the bundle for blueprint annotations, such as @Blueprint, @Bean, @Service, @Reference, @ReferenceList, etc.  The blueprint annotation api is available in trunk/blueprint/blueprint-annotation-api module, while the blueprint implementation is available in trunk/blueprint/blueprint-annotatiom-impl module.  A blueprint annotated sample is also provided in trunk/blueprint/blueprint-sample-annotation.
+
+h2. Overview of Available blueprint Annotations
+
+h3. @Inject Annotation
+@Inject annotation can be used to inject fields or methods.
+
+{code:java|title=Bar.java|borderStyle=solid}
+
+@Bean(id="bar")
+public class Bar {
+    
+    @Inject(value="Hello FooBar")
+    private String value;
+
+    @Inject(ref="blueprintBundleContext")
+    private BundleContext context;
+    ...
+}
+{code}
+
+h3. @Bean Annotation
+
+You can annotate a bean using @Bean annotation.  The bean id is currently required, even tho it is possible we may want to the annotation service to auto generate one in the future.  Optionally, you can also specify activation, dependsOn, description, scope, factoryRef, factoryMethod and args of the bean.
+
+\* Example of using args property for the @Bean annotation.
+{code:java|title=Account.java|borderStyle=solid}
+@Bean(id="accountOne", args=@Arg(value="1"))
+public class Account {
+
+    private long accountNumber;
+
+    public Account(long number) {
+        this.accountNumber = number;
+    }
+}
+{code}
+
+\* Example of using factoryMethod and args properties for the @Bean annotation
+{code:java|title=StaticAccountFactory.java|borderStyle=solid}
+@Bean(id="accountTwo",
+      factoryMethod="createAccount",
+      args = @Arg(value="2"))
+public class StaticAccountFactory {
+
+    public static Account createAccount(long number) {
+        return new Account(number);
+     }
+}
+{code}
+
+
+\* Example of using factoryRef, factoryMethod, and args properties for the @Bean annotation
+{code:java|title=NewAccount.java|borderStyle=solid}
+@Bean(id="accountThree",
+      factoryRef="accountFactory",
+      factoryMethod="createAccount",
+      args=@Arg(value="3"))
+public class NewAccount {
+
+    private long accountNumber;
+
+    public NewAccount(long number) {
+        this.accountNumber = number;
+    }
+    ...
+}
+{code}
+
+h3. @Service, @RegistrationListener, @Register, @Unregister Annotations
+If you want to register a bean as a service, you can use @Service annotation to do so.  You can specify ranking, autoExport, interfaces, serviceProperties and registrationListeners for the service.
+
+{code:java|title=Foo.java|borderStyle=solid}
+@Bean(id="foo")
+@Service(autoExport="all-classes",
+        serviceProperties = @ServiceProperty(key="blueprint.annotation.sample", value="true"),
+        registerationListeners = @RegistrationListener(ref="fooRegistrationListener"), 
+        ranking=0)
+public class Foo implements Serializable {
+   ...
+}
+{code}
+
+
+To annotation a class as registration listener, you can use the @RegistrationListener annotation.  @Register can be used to annotate the register-method for the registration listener and @Unregister annotation can be used on the unregister-method for the registration listener.
+{code:java|title=FooRegistrationListener.java|borderStyle=solid}
+@Bean(id="fooRegistrationListener")
+@RegistrationListener
+public class FooRegistrationListener {
+        
+    @Register
+    public void serviceRegistered(Serializable foo, Map props) {
+        System.out.println("Service registration notification: " + foo + " " + props);
+    }
+    
+    @Unregister
+    public void serviceUnregistered(Foo foo, Map props) {
+        System.out.println("Service unregistration notification: " + foo + " " + props);
+    }
+
+}
+{code}
+
+h3. @Reference, @ReferenceList, @ReferenceListener Annotations
+
+For a bean that you want to act as a ReferenceListener, you can use @ReferenceListener to annotate the bean class.   
+
+For the service that you want to inject the reference, you can use the @Inject and @Reference annotation, with the id, serviceInterface, timeout and referenceListeners properties specified for the reference.   
+
+{code:java|title=BindingListener.java|borderStyle=solid}
+@Bean(id="bindingListener")
+@ReferenceListener
+public class BindingListener {
+
+    @Inject @Reference (id="ref2", 
+            serviceInterface = InterfaceA.class,
+            timeout=100, referenceListeners=@ReferenceListener(ref="bindingListener"))
+    private InterfaceA a;
+    ...
+    @Init
+    public void init() {
+    }
+
+    @Bind
+    public void bind(InterfaceA a, Map props) {
+        this.a = a;
+        this.props = props;
+    }
+
+    @Unbind
+    public void unbind(InterfaceA a, Map props) {
+        this.a = null;
+        this.props = null;
+    }
+
+}
+{code}
+
+
+@ReferenceList is very similar as @Reference, except that the timeout property is not supported in @ReferenceList, while the memberType property is supported in @ReferenceList.  This is same as the blueprint XML schema.
+
+{code:java|title=ListBindingListener.java|borderStyle=solid}
+@Bean(id="listBindingListener")
+@ReferenceListener
+public class ListBindingListener {
+
+    @Inject @ReferenceList (id="ref-list", 
+            serviceInterface = InterfaceA.class,
+            referenceListeners=@ReferenceListener(ref="listBindingListener"))
+    private InterfaceA a;
+    ...
+}
+{code}
+
+h3. @Blueprint annotation
+@Blueprint annotation can be used on any class to annotate the global property of the blueprint bundle, such as defaultActivation, defaultTimeout, defaultAvailability.
+
+{code:java|title=Bar.java|borderStyle=solid}
+@Blueprint(defaultActivation="eager", defaultTimeout=300, defaultAvailability="optional")
+@Bean(id="bar")
+public class Bar {
+    ...
+}
+{code}
+
+h3. Type converters
+If type converters are desired, you can use the @Bean annotation for it.  The blueprint annotation service will recognize it as a type converter if it implements the {{org.osgi.service.blueprint.container.Converter}} interface
+
+{code:java|title=DateTypeConverter.java|borderStyle=solid}
+@Bean(id="converter1")
+public class DateTypeConverter implements Converter {
+
+    @Inject(name="format", value="yyyy.MM.dd")
+    DateFormat dateFormat;
+    ...
+}
+{code}
+
+h3. Limitation
+Blueprint Annotation is still prototype work and currently only runtime annotation scanning is supported.  While it provides some basic useful functions, there are still many things that you cannot do using annotation, such as inject a list with values, inject inline beans, etc.
+
+
+

Added: incubator/aries/branches/site/trunk/content/blueprintannotation.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprintannotation.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprintannotation.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/blueprintannotation.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,238 @@
+Title: BlueprintAnnotation
+<a name="BlueprintAnnotation-Introduction"></a>
+# Introduction
+
+Blueprint annotation is being prototyped in Apache Aries in
+trunk/blueprint.   The blueprint annotation service is an optional service
+to the blueprint core and should not affect the blueprint core if
+annotation supported is not required.	If the blueprint annotation service
+is available, the bundle contains no blueprint definition XML and the
+bundle contains the manifest header *Bundle-Blueprint-Annotation* with
+the value set to true, the blueprint annotation service will attempt to
+scan the bundle for blueprint annotations, such as @Blueprint, @Bean,
+@Service, @Reference, @ReferenceList, etc.  The blueprint annotation api is
+available in trunk/blueprint/blueprint-annotation-api module, while the
+blueprint implementation is available in
+trunk/blueprint/blueprint-annotatiom-impl module.  A blueprint annotated
+sample is also provided in trunk/blueprint/blueprint-sample-annotation.
+
+<a name="BlueprintAnnotation-OverviewofAvailableblueprintAnnotations"></a>
+## Overview of Available blueprint Annotations
+
+<a name="BlueprintAnnotation-@InjectAnnotation"></a>
+### @Inject Annotation
+@Inject annotation can be used to inject fields or methods.
+
+{code:java|title=Bar.java|borderStyle=solid}
+
+@Bean(id="bar")
+public class Bar {
+    
+    @Inject(value="Hello FooBar")
+    private String value;
+
+    @Inject(ref="blueprintBundleContext")
+    private BundleContext context;
+    ...
+}
+{code}
+
+<a name="BlueprintAnnotation-@BeanAnnotation"></a>
+### @Bean Annotation
+
+You can annotate a bean using @Bean annotation.  The bean id is currently
+required, even tho it is possible we may want to the annotation service to
+auto generate one in the future.  Optionally, you can also specify
+activation, dependsOn, description, scope, factoryRef, factoryMethod and
+args of the bean.
+
+\* Example of using args property for the @Bean annotation.
+{code:java|title=Account.java|borderStyle=solid}
+@Bean(id="accountOne", args=@Arg(value="1"))
+public class Account {
+
+    private long accountNumber;
+
+    public Account(long number) {
+	this.accountNumber = number;
+    }
+}
+{code}
+
+\* Example of using factoryMethod and args properties for the @Bean
+annotation
+{code:java|title=StaticAccountFactory.java|borderStyle=solid}
+@Bean(id="accountTwo",
+      factoryMethod="createAccount",
+      args = @Arg(value="2"))
+public class StaticAccountFactory {
+
+    public static Account createAccount(long number) {
+	return new Account(number);
+     }
+}
+{code}
+
+
+\* Example of using factoryRef, factoryMethod, and args properties for the
+@Bean annotation
+{code:java|title=NewAccount.java|borderStyle=solid}
+@Bean(id="accountThree",
+      factoryRef="accountFactory",
+      factoryMethod="createAccount",
+      args=@Arg(value="3"))
+public class NewAccount {
+
+    private long accountNumber;
+
+    public NewAccount(long number) {
+	this.accountNumber = number;
+    }
+    ...
+}
+{code}
+
+<a name="BlueprintAnnotation-@Service,@RegistrationListener,@Register,@UnregisterAnnotations"></a>
+### @Service, @RegistrationListener, @Register, @Unregister Annotations
+If you want to register a bean as a service, you can use @Service
+annotation to do so.  You can specify ranking, autoExport, interfaces,
+serviceProperties and registrationListeners for the service.
+
+{code:java|title=Foo.java|borderStyle=solid}
+@Bean(id="foo")
+@Service(autoExport="all-classes",
+	serviceProperties =
+@ServiceProperty(key="blueprint.annotation.sample", value="true"),
+	registerationListeners =
+@RegistrationListener(ref="fooRegistrationListener"), 
+	ranking=0)
+public class Foo implements Serializable {
+   ...
+}
+{code}
+
+
+To annotation a class as registration listener, you can use the
+@RegistrationListener annotation.  @Register can be used to annotate the
+register-method for the registration listener and @Unregister annotation
+can be used on the unregister-method for the registration listener.
+{code:java|title=FooRegistrationListener.java|borderStyle=solid}
+@Bean(id="fooRegistrationListener")
+@RegistrationListener
+public class FooRegistrationListener {
+        
+    @Register
+    public void serviceRegistered(Serializable foo, Map props) {
+	System.out.println("Service registration notification: " + foo + "
+" + props);
+    }
+    
+    @Unregister
+    public void serviceUnregistered(Foo foo, Map props) {
+	System.out.println("Service unregistration notification: " + foo +
+" " + props);
+    }
+
+}
+{code}
+
+<a name="BlueprintAnnotation-@Reference,@ReferenceList,@ReferenceListenerAnnotations"></a>
+### @Reference, @ReferenceList, @ReferenceListener Annotations
+
+For a bean that you want to act as a ReferenceListener, you can use
+@ReferenceListener to annotate the bean class.	 
+
+For the service that you want to inject the reference, you can use the
+@Inject and @Reference annotation, with the id, serviceInterface, timeout
+and referenceListeners properties specified for the reference.	 
+
+{code:java|title=BindingListener.java|borderStyle=solid}
+@Bean(id="bindingListener")
+@ReferenceListener
+public class BindingListener {
+
+    @Inject @Reference (id="ref2", 
+	    serviceInterface = InterfaceA.class,
+	    timeout=100,
+referenceListeners=@ReferenceListener(ref="bindingListener"))
+    private InterfaceA a;
+    ...
+    @Init
+    public void init() {
+    }
+
+    @Bind
+    public void bind(InterfaceA a, Map props) {
+	this.a = a;
+	this.props = props;
+    }
+
+    @Unbind
+    public void unbind(InterfaceA a, Map props) {
+	this.a = null;
+	this.props = null;
+    }
+
+}
+{code}
+
+
+@ReferenceList is very similar as @Reference, except that the timeout
+property is not supported in @ReferenceList, while the memberType property
+is supported in @ReferenceList.  This is same as the blueprint XML schema.
+
+{code:java|title=ListBindingListener.java|borderStyle=solid}
+@Bean(id="listBindingListener")
+@ReferenceListener
+public class ListBindingListener {
+
+    @Inject @ReferenceList (id="ref-list", 
+	    serviceInterface = InterfaceA.class,
+	   
+referenceListeners=@ReferenceListener(ref="listBindingListener"))
+    private InterfaceA a;
+    ...
+}
+{code}
+
+<a name="BlueprintAnnotation-@Blueprintannotation"></a>
+### @Blueprint annotation
+@Blueprint annotation can be used on any class to annotate the global
+property of the blueprint bundle, such as defaultActivation,
+defaultTimeout, defaultAvailability.
+
+{code:java|title=Bar.java|borderStyle=solid}
+@Blueprint(defaultActivation="eager", defaultTimeout=300,
+defaultAvailability="optional")
+@Bean(id="bar")
+public class Bar {
+    ...
+}
+{code}
+
+<a name="BlueprintAnnotation-Typeconverters"></a>
+### Type converters
+If type converters are desired, you can use the @Bean annotation for it. 
+The blueprint annotation service will recognize it as a type converter if
+it implements the *org.osgi.service.blueprint.container.Converter*
+interface
+
+{code:java|title=DateTypeConverter.java|borderStyle=solid}
+@Bean(id="converter1")
+public class DateTypeConverter implements Converter {
+
+    @Inject(name="format", value="yyyy.MM.dd")
+    DateFormat dateFormat;
+    ...
+}
+{code}
+
+<a name="BlueprintAnnotation-Limitation"></a>
+### Limitation
+Blueprint Annotation is still prototype work and currently only runtime
+annotation scanning is supported.  While it provides some basic useful
+functions, there are still many things that you cannot do using annotation,
+such as inject a list with values, inject inline beans, etc.
+
+
+

Added: incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,104 @@
+h1. Blueprint tutorial
+
+h3. Introduction
+
+This tutorial is designed for people who are starting to use the Apache Aries Blueprint implementation. After you have worked through the tutorial you will
+* be able to run a very simple piece of code in the Aries Blueprint container
+* understand bean, service and reference definitions in Blueprint
+
+The tutorial assumes a basic working knowledge of Java development, Eclipse and some understanding of OSGi.
+
+In order to work through the tutorial you will need to do checkout and build copy of Aries, the instructions are [here|http://incubator.apache.org/aries/building-aries.html]. This tutorial assumes that you have built Aries and imported the samples/helloworld projects into Eclipse. 
+
+
+\\
+\\
+
+h3. The API, Server and Client projects
+
+\\
+
+When you have checked out and built the Aries code your workspace will contain the four projects highlighted in the picture below. This is a screen shot taken from my Eclipse package explorer:!HW1.png|align=center!
+The project called org.apache.aries.samples.helloworld.blueprint.assembly contains no Java code and is just used to pull together the minimal OSGi platform that is needed to run the sample.
+Expanding the org.apache.aries.samples.helloworld.blueprint.api project shows this:!HW2.png|align=center!
+There are two interesting features of this project, the HelloWorldService.java interface and empty META-INF directory. HelloWorldService.java is the interface for the Helloworld service. It is good OSGi practice to keep interfaces and implementation classes in separate bundles. This allows implementations to be replaced independently of their interfaces. The META-INF directory is where you would expect to see a file called MANIFEST.MF. You don't see it because we are using a Maven plugin (look at the pom.xml) to generate the bundle manifest automatically.
+
+\\
+Expanding the org.apache.aries.samples.helloworld.blueprint.server project shows !HW3.png|align=center!
+There are again two interesting files. HelloWorldServiceImpl.java is an implementation of the HelloWorldService interface in the first blueprint-helloworld-api project. The file config.xml is the Blueprint configuration for this package. 
+
+\\
+The org.apache.aries.samples.helloworld.blueprint.client project looks like this !HW4.png|align=center!
+The client implementation is in HelloWorldClient.java. The file config.xml contains the Blueprint for the client.
+\\
+\\
+
+h3. The Blueprint XML
+
+\\
+
+Blueprint xml files contain all the information that the Blueprint runtime needs to internally wire a bundle's components. They also contain the information that the Blueprint runtime needs to register and locate services in the OSGi service registry. This allows for service-based interactions between bundles. 
+
+\\
+This is a view of what the xml in the two config.xml files is describing: !BPTutorial5F.png|align=center!
+
+\\
+The client configuration file has one bean definition which names the Java class that it requires and gives the name of the method that will be run when the bean has been initialised. The bean definition also describes a property, helloWorldService, which points (see the arrow) to the reference definition. This is telling Blueprint that the bean (helloclient) needs the container to supply a service matched by the 'helloservice' reference, which in turns specifies the interface to be implemented by that service. !BPTutorial6F.png|align=center!
+
+\\
+The server configuration file is similar - with one bean definition which points to the Java class that implements HelloWorldService. The second element in this file is the service definition. This registers a service under the HelloWorldService interface, implemented by the 'helloservice' bean. !BPTutorial7F.png|align=center!
+
+\\
+h3. The Java classes
+
+\\
+
+Both the Java classes are very simple, there are just a couple of minor points to make about each one. The HelloWorldClient class looks like this:!BPTutorial8F.png|align=center!
+# The setHelloWorldService() method will be called by the Blueprint container in order to inject an object implementing the HelloWorldService interface.
+# The startUp() method will be run when the bundle is started: remember that this was specified in the Blueprint. This method executes a hello() method which must be supplied by an implementation of HelloWorldService. The startUp() method in this case will only be run after dependencies have been injected. This is the default Blueprint behaviour.
+
+\\
+\\
+The HelloWorldServiceImpl class is even simpler. It has two methods:!BPTutorial9F.png|align=center!
+# A startUp() method which writes a message to say that the bundle is being started
+# A hello() method which writes a 'hello' message
+
+\\
+\\
+
+h3. Running the code
+
+\\
+
+The code can be run on an Equinox (or Felix) framework. The org.apache.aries.samples.helloworld.blueprint.assembly package assembles an Equinox based platform that contains all of the OSGi bundles you need. To start it up go to the target directory in  org.apache.aries.samples.helloworld.blueprint.assembly, and from command line, type:
+{code}
+java -jar osgi-3.5.0.v20090520.jar -console
+{code}
+You will see some messages, after which you should get the 'osgi>' prompt; sometimes you will need to press return to see it. At the prompt, type 'ss' to see the status of the bundles:!BPTutorial10.png|align=center!
+Next, start the Blueprint container bundle by typing 'start 5' at the osgi prompt.  You will see many debug messages in the code, this is because the target/configuration/config.ini specifies the message level to be DEBUG, if there are too many messages you can change this to 'INFO'. The debug messages are quite interesting to look through in themselves, but a little beyond the scope of this tutorial. The last debug message should indicate that a Blueprint container is running in state 'created'. After that, start the blueprint-helloworld-api in the same way by typing 'start 6' at the prompt.
+
+\\
+The next step is to  start the blueprint-helloworld-server bundle. In amongst the DEBUG messages you should see the single line of output from the startUp() method if the HelloWorldServiceImpl class:
+{code}
+======>>> Starting HelloWorld Server
+{code}
+At this point it is possible to see if the HelloWorldService is registered, like this:
+{code}
+osgi> services (objectClass=org.apache.aries.samples.blueprint.helloworld.api.HelloWorldService)
+{code}
+running this command will tell you that a service is registered but that nothing is using it.
+
+Finally, start the blueprint-helloworld-client bundle. If things have gone according to plan you should see a sequence of 3 messages from the startUp() method, the second message will be a 'hello' from HelloWorldService:
+{code}
+========>>>>Client HelloWorld: About to execute a method from the Hello World server
+======>>> A message from the server: Hello World!
+========>>>>Client HelloWorld: ... if you didn't just see a Hello World message something went wrong
+{code}
+If you re-run the services command above it will tell you that the blueprint-helloworldclient bundle is using the blueprint-helloworldservice.
+
+One interesting experiment is to start the blueprint-helloworldclient bundle before the blueprint-helloworldserver bunde. When you do this, you will see no output until the second bundle is started because the 'helloclient' bean cannot be initialised until that point. If you wait more than five minutes by default, there will be a timeout and the client will not be initialised at all.
+
+
+h3. Summary
+
+In the tutorial you have seen how to construct three simple Blueprint bundles. The client bundle depends directly on the api and indirectly on the server bundle. Blueprint takes care of registering a service from the server bundle so that the client bundle can use it. You will have some appreciation of the classes and XML that form a Blueprint application, and you have seen a simple example working. Of course, this tutorial barely touches on many of the features provided by the Aries Blueprint implementation. Anyone keen to explore the features of Blueprint should look at this [article|http://www.ibm.com/developerworks/opensource/library/os-osgiblueprint/index.html] and continue by reading the [OSGi specification|http://www.osgi.org/Download/Release4V42] (see the 4.2 Compendium spec, section 121, "Blueprint Container Specification") and making modifications to the sample code.
\ No newline at end of file

Added: incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/blueprinthelloworldtutorial.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,225 @@
+Title: BlueprintHelloWorldTutorial
+<a name="BlueprintHelloWorldTutorial-Blueprinttutorial"></a>
+# Blueprint tutorial
+
+<a name="BlueprintHelloWorldTutorial-Introduction"></a>
+### Introduction
+
+This tutorial is designed for people who are starting to use the Apache
+Aries Blueprint implementation. After you have worked through the tutorial
+you will
+* be able to run a very simple piece of code in the Aries Blueprint
+container
+* understand bean, service and reference definitions in Blueprint
+
+The tutorial assumes a basic working knowledge of Java development, Eclipse
+and some understanding of OSGi.
+
+In order to work through the tutorial you will need to do checkout and
+build copy of Aries, the instructions are [here](http://incubator.apache.org/aries/building-aries.html)
+. This tutorial assumes that you have built Aries and imported the
+samples/helloworld projects into Eclipse. 
+
+
+  
+  
+  
+  
+
+<a name="BlueprintHelloWorldTutorial-TheAPI,ServerandClientprojects"></a>
+### The API, Server and Client projects
+
+  
+  
+
+When you have checked out and built the Aries code your workspace will
+contain the four projects highlighted in the picture below. This is a
+screen shot taken from my Eclipse package explorer:!HW1.png|align=center!
+The project called org.apache.aries.samples.helloworld.blueprint.assembly
+contains no Java code and is just used to pull together the minimal OSGi
+platform that is needed to run the sample.
+Expanding the org.apache.aries.samples.helloworld.blueprint.api project
+shows this:!HW2.png|align=center!
+There are two interesting features of this project, the
+HelloWorldService.java interface and empty META-INF directory.
+HelloWorldService.java is the interface for the Helloworld service. It is
+good OSGi practice to keep interfaces and implementation classes in
+separate bundles. This allows implementations to be replaced independently
+of their interfaces. The META-INF directory is where you would expect to
+see a file called MANIFEST.MF. You don't see it because we are using a
+Maven plugin (look at the pom.xml) to generate the bundle manifest
+automatically.
+
+  
+  
+Expanding the org.apache.aries.samples.helloworld.blueprint.server project
+shows !HW3.png|align=center!
+There are again two interesting files. HelloWorldServiceImpl.java is an
+implementation of the HelloWorldService interface in the first
+blueprint-helloworld-api project. The file config.xml is the Blueprint
+configuration for this package. 
+
+  
+  
+The org.apache.aries.samples.helloworld.blueprint.client project looks like
+this !HW4.png|align=center!
+The client implementation is in HelloWorldClient.java. The file config.xml
+contains the Blueprint for the client.
+  
+  
+  
+  
+
+<a name="BlueprintHelloWorldTutorial-TheBlueprintXML"></a>
+### The Blueprint XML
+
+  
+  
+
+Blueprint xml files contain all the information that the Blueprint runtime
+needs to internally wire a bundle's components. They also contain the
+information that the Blueprint runtime needs to register and locate
+services in the OSGi service registry. This allows for service-based
+interactions between bundles. 
+
+  
+  
+This is a view of what the xml in the two config.xml files is describing:
+!BPTutorial5F.png|align=center!
+
+  
+  
+The client configuration file has one bean definition which names the Java
+class that it requires and gives the name of the method that will be run
+when the bean has been initialised. The bean definition also describes a
+property, helloWorldService, which points (see the arrow) to the reference
+definition. This is telling Blueprint that the bean (helloclient) needs the
+container to supply a service matched by the 'helloservice' reference,
+which in turns specifies the interface to be implemented by that service.
+!BPTutorial6F.png|align=center!
+
+  
+  
+The server configuration file is similar - with one bean definition which
+points to the Java class that implements HelloWorldService. The second
+element in this file is the service definition. This registers a service
+under the HelloWorldService interface, implemented by the 'helloservice'
+bean. !BPTutorial7F.png|align=center!
+
+  
+  
+<a name="BlueprintHelloWorldTutorial-TheJavaclasses"></a>
+### The Java classes
+
+  
+  
+
+Both the Java classes are very simple, there are just a couple of minor
+points to make about each one. The HelloWorldClient class looks like
+this:!BPTutorial8F.png|align=center!
+1. The setHelloWorldService() method will be called by the Blueprint
+container in order to inject an object implementing the HelloWorldService
+interface.
+1. The startUp() method will be run when the bundle is started: remember
+that this was specified in the Blueprint. This method executes a hello()
+method which must be supplied by an implementation of HelloWorldService.
+The startUp() method in this case will only be run after dependencies have
+been injected. This is the default Blueprint behaviour.
+
+  
+  
+  
+  
+The HelloWorldServiceImpl class is even simpler. It has two
+methods:!BPTutorial9F.png|align=center!
+1. A startUp() method which writes a message to say that the bundle is being
+started
+1. A hello() method which writes a 'hello' message
+
+  
+  
+  
+  
+
+<a name="BlueprintHelloWorldTutorial-Runningthecode"></a>
+### Running the code
+
+  
+  
+
+The code can be run on an Equinox (or Felix) framework. The
+org.apache.aries.samples.helloworld.blueprint.assembly package assembles an
+Equinox based platform that contains all of the OSGi bundles you need. To
+start it up go to the target directory in 
+org.apache.aries.samples.helloworld.blueprint.assembly, and from command
+line, type:
+{code}
+java -jar osgi-3.5.0.v20090520.jar -console
+{code}
+You will see some messages, after which you should get the 'osgi>' prompt;
+sometimes you will need to press return to see it. At the prompt, type 'ss'
+to see the status of the bundles:!BPTutorial10.png|align=center!
+Next, start the Blueprint container bundle by typing 'start 5' at the osgi
+prompt.  You will see many debug messages in the code, this is because the
+target/configuration/config.ini specifies the message level to be DEBUG, if
+there are too many messages you can change this to 'INFO'. The debug
+messages are quite interesting to look through in themselves, but a little
+beyond the scope of this tutorial. The last debug message should indicate
+that a Blueprint container is running in state 'created'. After that, start
+the blueprint-helloworld-api in the same way by typing 'start 6' at the
+prompt.
+
+  
+  
+The next step is to  start the blueprint-helloworld-server bundle. In
+amongst the DEBUG messages you should see the single line of output from
+the startUp() method if the HelloWorldServiceImpl class:
+{code}
+======>>> Starting HelloWorld Server
+{code}
+At this point it is possible to see if the HelloWorldService is registered,
+like this:
+{code}
+osgi> services
+(objectClass=org.apache.aries.samples.blueprint.helloworld.api.HelloWorldService)
+{code}
+running this command will tell you that a service is registered but that
+nothing is using it.
+
+Finally, start the blueprint-helloworld-client bundle. If things have gone
+according to plan you should see a sequence of 3 messages from the
+startUp() method, the second message will be a 'hello' from
+HelloWorldService:
+{code}
+========>>>>Client HelloWorld: About to execute a method from the Hello
+World server
+======>>> A message from the server: Hello World!
+========>>>>Client HelloWorld: ... if you didn't just see a Hello World
+message something went wrong
+{code}
+If you re-run the services command above it will tell you that the
+blueprint-helloworldclient bundle is using the blueprint-helloworldservice.
+
+One interesting experiment is to start the blueprint-helloworldclient
+bundle before the blueprint-helloworldserver bunde. When you do this, you
+will see no output until the second bundle is started because the
+'helloclient' bean cannot be initialised until that point. If you wait more
+than five minutes by default, there will be a timeout and the client will
+not be initialised at all.
+
+
+<a name="BlueprintHelloWorldTutorial-Summary"></a>
+### Summary
+
+In the tutorial you have seen how to construct three simple Blueprint
+bundles. The client bundle depends directly on the api and indirectly on
+the server bundle. Blueprint takes care of registering a service from the
+server bundle so that the client bundle can use it. You will have some
+appreciation of the classes and XML that form a Blueprint application, and
+you have seen a simple example working. Of course, this tutorial barely
+touches on many of the features provided by the Aries Blueprint
+implementation. Anyone keen to explore the features of Blueprint should
+look at this [article](http://www.ibm.com/developerworks/opensource/library/os-osgiblueprint/index.html)
+ and continue by reading the [OSGi specification|http://www.osgi.org/Download/Release4V42]
+ (see the 4.2 Compendium spec, section 121, "Blueprint Container
+Specification") and making modifications to the sample code.

Added: incubator/aries/branches/site/trunk/content/boardreports.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/boardreports.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/boardreports.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/boardreports.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1 @@
+{children:sort=creation|reverse=true}
\ No newline at end of file

Added: incubator/aries/branches/site/trunk/content/boardreports.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/boardreports.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/boardreports.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/boardreports.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,7 @@
+# Board Reports
+- [September 2010](september-2010.html)
+- [June 2010](june-2010.html)
+- [March 2010](march-2010.html)
+- [December 2010](december-2009.html)
+- [November 2010](november-2009.html)
+- [October 2010](october-2009.html)

Added: incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.cwiki?rev=1040087&view=auto
==============================================================================
    (empty)

Added: incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.mdtext_bak
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.mdtext_bak?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.mdtext_bak (added)
+++ incubator/aries/branches/site/trunk/content/building-aries-in-eclipse.mdtext_bak Mon Nov 29 12:32:22 2010
@@ -0,0 +1 @@
+Title: Building Aries in Eclipse

Added: incubator/aries/branches/site/trunk/content/buildingaries.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/buildingaries.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/buildingaries.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/buildingaries.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,89 @@
+h1. Extracting and building Aries
+
+There are two ways to do this. The first avoids using the command line but can leave you with some fixing up to do on the projects.
+
+h2. Prereqs
+
+ * Check that Maven is 2.0.10 or higher (mvn --version)
+ * Download and extract eclipse-jee-ganymede-SR2-linux-gtk.tar.gz (this is the 3.4 version)
+ * Install Subversion client http://subclipse.tigris.org/update_1.6.x (Just the Subclipse and Core)
+ * Install m2eclipse http://m2eclipse.sonatype.org/update/ (Maven Integration and Maven optional components)
+
+
+
+h2. Build at the command line then import into Eclipse if you need Eclipse.
+This is the easiest way to build Aries and then work on the modules using Eclipse. If you don't care about Eclipse go to the next section.
+
+ * check out from the command line {{svn co https://svn.apache.org/repos/asf/incubator/aries/trunk aries}}
+ * cd aries
+ * mvn clean
+ * cd parent
+ * mvn install
+ * cd ../eba-maven-plugin
+ * mvn install (*See note below*)
+ * cd ..
+ * mvn install
+ * mvn eclipse:eclipse (should see 'BUILD SUCCESSFUL' message)
+ * fire up eclipse and switch to the Java perspective
+ * import the projects. File->import->General->existing projects into workspace. Import 'blueprint, 'jndi', 'testsupport' and 'transaction'
+
+If everything looks good run a  maven build with the target 'install' (adds jars to your local repository) or 'package' (just creates jars in your workspace). Hit F5 in the package explorer view to refresh and you should see packaged jar files under the *target* directories in the projects.
+
+{note}
+Note: There is currently (September 2010) what appears to be a timing issue that is causing unpredictable test failures during a full build. If you see test failures, try 'mvn install -fae'
+{note}
+
+h2. Just build it - no Eclipse
+ * check out from the command line {{svn co https://svn.apache.org/repos/asf/incubator/aries/trunk aries}}
+ * cd aries
+ * mvn clean
+ * cd parent
+ * mvn install
+ * cd ../eba-maven-plugin
+ * mvn install
+ * cd ..
+ * {{mvn -fn install}} (-fn continues after failures), or {{mvn -fn package}} (alternatively, you can disable the tests with {{mvn -Dmaven.test.skip=true install}} with the side-effect of making the build process much faster)
+
+h2. Eclipse only
+This should work if you are command-line averse. On the other hand it seems to be the best way to get into a mess with the M2Eclipse plugin.
+
+ * In the SVN view, add the aries repository https://svn.apache.org/repos/asf/incubator/aries
+ * Expand the repository, right click on trunk and take 'check out as Maven project'
+There will be errors in the projects. To fix these:
+ * Right click on pom/xml in the aries project, select 'run as Maven build....'
+ * Type 'clean' in as the build goal
+ * Repeat the process using 'eclipse:eclipse' as the build goals'
+ * Close and re-open all the projects
+
+If there are still failures see the "Fixing failures" step below. If everything looks good run a final maven build with the target 'install' (adds jars to your local repository) or 'package' (just creates jars in your workspace). Hit F5 in the package explorer view to refresh and you should see packaged jar files under the *target* directories in the projects.
+
+
+h2. Fixing failures
+
+h5. In Eclipse
+
+You will see some of the blueprint projects don't build. To fix this you need to comment out the following line:
+{code}
+<!-- <classpathentry kind="src"
+path="/Users/linsun/aries/blueprint/blueprint-api/src/main/resources/org/osgi/service/blueprint"
+including="blueprint.xsd" excluding="**/*.java"/> -->
+{code}
+
+in the .classpath file in the aries-blueprint-core project.
+
+If there is a build error in the org.apache.aries.blueprint.itests project then remove this jar:
+{code}
+org/apache/felix/org.osgi.foundation/1.2.0.jar
+{code}
+from the project's classpath.
+
+If there is a build error in the aries-jmx-core project then configure this project's build path to add the JRE System Library to Java Build Path.
+
+There should be no outstanding errors.
+
+h5. Out of memory errors
+You may find that building Aries fails with out of memory exceptions on some systems (eg Mac)  if you use the standard Java settings. Setting the two environment variables as shown below may help.
+{code}
+export MAVEN_OPTS="-XX:MaxPermSize=128m -Xms512m -Xmx512m -XX:+HeapDumpOnOutOfMemoryError"
+export JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=128m -XX:+HeapDumpOnOutOfMemoryError"
+{code}
\ No newline at end of file

Added: incubator/aries/branches/site/trunk/content/buildingaries.mdtext
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/buildingaries.mdtext?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/buildingaries.mdtext (added)
+++ incubator/aries/branches/site/trunk/content/buildingaries.mdtext Mon Nov 29 12:32:22 2010
@@ -0,0 +1,130 @@
+Title: BuildingAries
+<a name="BuildingAries-ExtractingandbuildingAries"></a>
+# Extracting and building Aries
+
+There are two ways to do this. The first avoids using the command line but
+can leave you with some fixing up to do on the projects.
+
+<a name="BuildingAries-Prereqs"></a>
+## Prereqs
+
+ * Check that Maven is 2.0.10 or higher (mvn --version)
+ * Download and extract eclipse-jee-ganymede-SR2-linux-gtk.tar.gz (this is
+the 3.4 version)
+ * Install Subversion client http://subclipse.tigris.org/update_1.6.x (Just
+the Subclipse and Core)
+ * Install m2eclipse http://m2eclipse.sonatype.org/update/ (Maven
+Integration and Maven optional components)
+
+
+
+<a name="BuildingAries-BuildatthecommandlinethenimportintoEclipseifyouneedEclipse."></a>
+## Build at the command line then import into Eclipse if you need Eclipse.
+This is the easiest way to build Aries and then work on the modules using
+Eclipse. If you don't care about Eclipse go to the next section.
+
+ * check out from the command line {{svn co
+https://svn.apache.org/repos/asf/incubator/aries/trunk aries}}
+ * cd aries
+ * mvn clean
+ * cd parent
+ * mvn install
+ * cd ../eba-maven-plugin
+ * mvn install (*See note below*)
+ * cd ..
+ * mvn install
+ * mvn eclipse:eclipse (should see 'BUILD SUCCESSFUL' message)
+ * fire up eclipse and switch to the Java perspective
+ * import the projects. File->import->General->existing projects into
+workspace. Import 'blueprint, 'jndi', 'testsupport' and 'transaction'
+
+If everything looks good run a	maven build with the target 'install' (adds
+jars to your local repository) or 'package' (just creates jars in your
+workspace). Hit F5 in the package explorer view to refresh and you should
+see packaged jar files under the *target* directories in the projects.
+
+{note}
+Note: There is currently (September 2010) what appears to be a timing issue
+that is causing unpredictable test failures during a full build. If you see
+test failures, try 'mvn install -fae'
+{note}
+
+<a name="BuildingAries-Justbuildit-noEclipse"></a>
+## Just build it - no Eclipse
+ * check out from the command line {{svn co
+https://svn.apache.org/repos/asf/incubator/aries/trunk aries}}
+ * cd aries
+ * mvn clean
+ * cd parent
+ * mvn install
+ * cd ../eba-maven-plugin
+ * mvn install
+ * cd ..
+ * *mvn -fn install* (-fn continues after failures), or {{mvn -fn
+package}} (alternatively, you can disable the tests with {{mvn
+-Dmaven.test.skip=true install}} with the side-effect of making the build
+process much faster)
+
+<a name="BuildingAries-Eclipseonly"></a>
+## Eclipse only
+This should work if you are command-line averse. On the other hand it seems
+to be the best way to get into a mess with the M2Eclipse plugin.
+
+ * In the SVN view, add the aries repository
+https://svn.apache.org/repos/asf/incubator/aries
+ * Expand the repository, right click on trunk and take 'check out as Maven
+project'
+There will be errors in the projects. To fix these:
+ * Right click on pom/xml in the aries project, select 'run as Maven
+build....'
+ * Type 'clean' in as the build goal
+ * Repeat the process using 'eclipse:eclipse' as the build goals'
+ * Close and re-open all the projects
+
+If there are still failures see the "Fixing failures" step below. If
+everything looks good run a final maven build with the target 'install'
+(adds jars to your local repository) or 'package' (just creates jars in
+your workspace). Hit F5 in the package explorer view to refresh and you
+should see packaged jar files under the *target* directories in the
+projects.
+
+
+<a name="BuildingAries-Fixingfailures"></a>
+## Fixing failures
+
+<a name="BuildingAries-InEclipse"></a>
+##### In Eclipse
+
+You will see some of the blueprint projects don't build. To fix this you
+need to comment out the following line:
+{code}
+<!-- <classpathentry kind="src"
+path="/Users/linsun/aries/blueprint/blueprint-api/src/main/resources/org/osgi/service/blueprint"
+including="blueprint.xsd" excluding="**/*.java"/> -->
+{code}
+
+in the .classpath file in the aries-blueprint-core project.
+
+If there is a build error in the org.apache.aries.blueprint.itests project
+then remove this jar:
+{code}
+org/apache/felix/org.osgi.foundation/1.2.0.jar
+{code}
+from the project's classpath.
+
+If there is a build error in the aries-jmx-core project then configure this
+project's build path to add the JRE System Library to Java Build Path.
+
+There should be no outstanding errors.
+
+<a name="BuildingAries-Outofmemoryerrors"></a>
+##### Out of memory errors
+You may find that building Aries fails with out of memory exceptions on
+some systems (eg Mac)  if you use the standard Java settings. Setting the
+two environment variables as shown below may help.
+{code}
+export MAVEN_OPTS="-XX:MaxPermSize=128m -Xms512m -Xmx512m
+-XX:+HeapDumpOnOutOfMemoryError"
+export JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=128m
+-XX:+HeapDumpOnOutOfMemoryError"
+{code}

Added: incubator/aries/branches/site/trunk/content/community.cwiki
URL: http://svn.apache.org/viewvc/incubator/aries/branches/site/trunk/content/community.cwiki?rev=1040087&view=auto
==============================================================================
--- incubator/aries/branches/site/trunk/content/community.cwiki (added)
+++ incubator/aries/branches/site/trunk/content/community.cwiki Mon Nov 29 12:32:22 2010
@@ -0,0 +1,12 @@
+h1. Community
+
+There are many ways to be part of the Apache Aries community. You will find suggestions under [getting involved|GettingInvolved]. 
+
+ - [Getting Involved|GettingInvolved]
+ - [Who we are|People]
+ - [Mailing lists|MailingLists]
+ - [Aries Group Blog|http://blogs.apache.org/aries/]
+
+You can also find us on IRC, attach freenode and join #apache-aries.
+
+Our twitter tag is #apache-aries.
\ No newline at end of file



Mime
View raw message