modules/ROOT/pages/modules/blueprint-maven-plugin.adoc - aries-antora-site - Git at Google

 Title: blueprint-maven-plugin Notice:    Licensed to the Apache Software Foundation (ASF) under one            or more contributor license agreements.
 See the NOTICE file            distributed with this work for additional information            regarding copyright ownership.
 The ASF licenses this file            to you under the Apache License, Version 2.0 (the            "License");
 you may not use this file except in compliance            with the License.
 You may obtain a copy of the License at            .              http://www.apache.org/licenses/LICENSE-2.0            .            Unless required by applicable law or agreed to in writing,            software distributed under the License is distributed on an            "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY            KIND, either express or implied.
 See the License for the            specific language governing permissions and limitations            under the License.

 Writing blueprint xml is quite verbose and large blueprint xmls are difficult to keep in sync with code changes and especially refactorings.
 So you would like to do most declarations using annoations and ideally these annotations should be standardized.

 == blueprint-maven-plugin

 The blueprint-maven-plugin allows to configure blueprint using annotations.
 It scans one or more paths for annotated classes and creates a blueprint.xml in target/generated-sources/blueprint/OSGI-INF/blueprint.
 So at runtime the bundle behaves like a normal blueprint bundle.
 The generated blueprint can also be used together with a manually created blueprint file.
 So for example cxf services can be created in xml while most of the beans are automatically generated.

 Usage:

  <plugin>
      <groupId>org.apache.aries.blueprint</groupId>
      <artifactId>blueprint-maven-plugin</artifactId>
      <version>1.10.0</version>
      <configuration>
          <scanPaths>
              <scanPath>org.my.package</scanPath>
          </scanPaths>
      </configuration>
      <executions>
          <executions>
              <execution>
                  <goals>
                      <goal>add-resource-dir</goal>
                      <goal>blueprint-generate</goal>
                  </goals>
              </execution>
          </executions>
      </executions>
  </plugin>

 == Goals

 === add-resource-dir

 Creates target/generated-sources/blueprint folder and register it as a maven resource directory in generate-resources phase, so IDEs like IntelliJ IDEA could find it automatically.

 === blueprint-generate

 Creates blueprint xml from annotations in process-classes phase and put file in target/generated-sources/blueprint/OSGI-INF/blueprint/autowire.xml.
 Destination directory (OSGI-INF/blueprint) and file name (autowire.xml) could be change via configuration properties: generatedDir and generatedFileName.

 == Annotations

 === javax.inject (JSR 330)

 * @Inject Inject a bean by type and optionally further qualifiers
 * @Singleton Mark a class as being a bean
 * @Named("Myname") Names a @Singleton and qualifies an @Inject to limit it to matches with the same bean id
 * @Qualifier Annotation on your own annotation

 === javax.enterprise

 * @Produces Create bean using factory method

 === javax.transaction

 * @Transactional mark the class as transactional.

 === javax.transaction.cdi

 * @Transactional mark the class as transactional.

 === javax.annotation (JSR 250)

 * @PostConstruct Marks a method to be called after DI is finished (init-method)
 * @PreDestroy Marks a method to be called before the bean is destroyed (destroy-method)

 === javax.persistence

 * @PersistenceContext(unitName="tasklist") inject a managed EntityManager for the given persistence unit into a field
 * @PersistenceUnit(unitName="tasklist") inject an unmanaged EntityManagerFactory for the given persistence unit into a field

 === Configuration annotations (org.apache.aries.blueprint.annotation.config)

 * @ConfigProperty Inject value as property from property-placeholder or constant
 * @Config Creates cm:property-placehoder
 * @DefaultProperty Configure default values for properties in property-placeholder

 === Collection annotations (org.apache.aries.blueprint.annotation.collection)

 * @CollectionInject Inject list, set or array of existing beans of provided interface

 === Bean annotations (org.apache.aries.blueprint.annotation.bean)

 * @Bean Mark a class as a bean or method as factory of bean

 === Reference listener annotations (org.apache.aries.blueprint.annotation.referencelistener)

 * @ReferenceListener Marks bean as reference listener
 * @Bind Method of referenence listener to be called when service registers
 * @Unbind Method of referenence listener to be called when service unregisters

 === Service annotations (org.apache.aries.blueprint.annotation.service)

 * @Service Publishes a bean as an OSGi service with the given interfaces
 * @ServiceProperty Defines a service property
 * @Reference Creates a reference to an OSGi service
 * @ReferenceList Creates a list of references of an OSGi services

 === pax-cdi (supported in version 1.x, probably dropped in next major versions)

 * @OsgiServiceProvider(classes={TaskService.class}) Publishes a bean as an OSGi service with the given interfaces
 * @OsgiService creates a reference to an OSGi service.
 On optional filter is also possible
 * @Properties Defines service properties for OSGiServiceProvider
 * @Property Defines a service property

 === Spring (supported in version 1.x, probably dropped in next major versions)

 * @Autowired Inject a bean by type and optionally further qualifiers
 * @Component Creates bean witd default or given name
 * @DependsOn Make bean depending on another bean
 * @Lazy Make bean lazy
 * @Qualifier Name injected bean
 * @Transactional mark the class as transactional
 * @Value Inject value or constant

 == Dependencies for annotations

  <dependency>
      <groupId>javax.inject</groupId>
      <artifactId>javax.inject</artifactId>
      <version>1</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>javax.enterprise</groupId>
      <artifactId>cdi-api</artifactId>
      <version>1.2</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>javax.persistence</groupId>
      <artifactId>persistence-api</artifactId>
      <version>1.0.2</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>javax.transaction</groupId>
      <artifactId>javax.transaction-api</artifactId>
      <version>1.2</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>org.apache.aries.blueprint</groupId>
      <artifactId>blueprint-maven-plugin-annotation</artifactId>
      <version>1.3.0</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>org.ops4j.pax.cdi</groupId>
      <artifactId>pax-cdi-api</artifactId>
      <version>0.8.0</version>
      <optional>true</optional>
  </dependency>
  <dependency>
      <groupId>org.apache.servicemix.bundles</groupId>
      <artifactId>org.apache.servicemix.bundles.spring-beans</artifactId>
      <version>3.2.11.RELEASE_1</version>
      <optional>true</optional>
  </dependency>

 Note that the annotations are needed only during build run, so you can exclude them or mark optional in Import-Package header of your bundle.

 == SPI

 Whole plugin is written using 'plugin architecture', so your own annotations could be configured for bleuprint generation.
 All you need to do, is to implement one of interfaces from blueprint-maven-plugin-spi:

  <dependency>
      <groupId>org.apache.aries.blueprint</groupId>
      <artifactId>blueprint-maven-plugin-spi</artifactId>
      <version>1.1.0</version>
  </dependency>

 Next add file (or files) to META-INF/services directory describing which interface implementation your artifact provides and add such artifact as plugin dependency

  <plugin>
      <groupId>org.apache.aries.blueprint</groupId>
      <artifactId>blueprint-maven-plugin</artifactId>
      <version>1.9.0</version>
      ...
      <dependencies>
          <dependency>
              <groupId>org.apache.aries.blueprint.example</groupId>
              <artifactId>blueprint-maven-plugin-my-extension</artifactId>
              <version>1.0.0</version>
          </dependency>
      </dependencies>
      ...
  </plugin>

 == Artifacts scanning configuration

 All artifacts are scaned for bean classes by default.
 It could be limited by includeArtifacts and excludeArtifacts parameters, e.
 g.

  <includeArtifacts>
      <includeArtifact>org.my.group.id:.*</includeArtifact>
      <includeArtifact>org.another.group.id:another.artifact.id:.*</includeArtifact>
  </includeArtifacts>
  <excludeArtifacts>
      <excludeArtifact>org.my.group.id:unwanted.artifact.id:.*</excludeArtifact>
  </excludeArtifacts>

 == Additional configuration

 Bean from factories are named by bean class nams or as defined in @Named or @Bean annotations.
 If you want to name such beans after producing method name then add configuration parameter:

  <configuration>
      <customParameters>
          <blueprint.beanFromFactory.nameFromFactoryMethodName>true</blueprint.beanFromFactory.nameFromFactoryMethodName>
      </customParameters>
  </configuration>

 == Example

 For a complete example see https://github.com/cschneider/Karaf-Tutorial/tree/master/tasklist-blueprint-cdi[tasklist-blueprint-cdi] on github or http://svn.apache.org/repos/asf/aries/trunk/blueprint/plugin/blueprint-maven-plugin/src/test/[tests of blueprint-maven-plugin].
	Title: blueprint-maven-plugin Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.
	See the NOTICE file distributed with this work for additional information regarding copyright ownership.
	The ASF licenses this file to you under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at . http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and limitations under the License.

	Writing blueprint xml is quite verbose and large blueprint xmls are difficult to keep in sync with code changes and especially refactorings.
	So you would like to do most declarations using annoations and ideally these annotations should be standardized.

	== blueprint-maven-plugin

	The blueprint-maven-plugin allows to configure blueprint using annotations.
	It scans one or more paths for annotated classes and creates a blueprint.xml in target/generated-sources/blueprint/OSGI-INF/blueprint.
	So at runtime the bundle behaves like a normal blueprint bundle.
	The generated blueprint can also be used together with a manually created blueprint file.
	So for example cxf services can be created in xml while most of the beans are automatically generated.

	Usage:

	<plugin>
	<groupId>org.apache.aries.blueprint</groupId>
	<artifactId>blueprint-maven-plugin</artifactId>
	<version>1.10.0</version>
	<configuration>
	<scanPaths>
	<scanPath>org.my.package</scanPath>
	</scanPaths>
	</configuration>
	<executions>
	<executions>
	<execution>
	<goals>
	<goal>add-resource-dir</goal>
	<goal>blueprint-generate</goal>
	</goals>
	</execution>
	</executions>
	</executions>
	</plugin>

	== Goals

	=== add-resource-dir

	Creates target/generated-sources/blueprint folder and register it as a maven resource directory in generate-resources phase, so IDEs like IntelliJ IDEA could find it automatically.

	=== blueprint-generate

	Creates blueprint xml from annotations in process-classes phase and put file in target/generated-sources/blueprint/OSGI-INF/blueprint/autowire.xml.
	Destination directory (OSGI-INF/blueprint) and file name (autowire.xml) could be change via configuration properties: generatedDir and generatedFileName.

	== Annotations

	=== javax.inject (JSR 330)

	* @Inject Inject a bean by type and optionally further qualifiers
	* @Singleton Mark a class as being a bean
	* @Named("Myname") Names a @Singleton and qualifies an @Inject to limit it to matches with the same bean id
	* @Qualifier Annotation on your own annotation

	=== javax.enterprise

	* @Produces Create bean using factory method

	=== javax.transaction

	* @Transactional mark the class as transactional.

	=== javax.transaction.cdi

	* @Transactional mark the class as transactional.

	=== javax.annotation (JSR 250)

	* @PostConstruct Marks a method to be called after DI is finished (init-method)
	* @PreDestroy Marks a method to be called before the bean is destroyed (destroy-method)

	=== javax.persistence

	* @PersistenceContext(unitName="tasklist") inject a managed EntityManager for the given persistence unit into a field
	* @PersistenceUnit(unitName="tasklist") inject an unmanaged EntityManagerFactory for the given persistence unit into a field

	=== Configuration annotations (org.apache.aries.blueprint.annotation.config)

	* @ConfigProperty Inject value as property from property-placeholder or constant
	* @Config Creates cm:property-placehoder
	* @DefaultProperty Configure default values for properties in property-placeholder

	=== Collection annotations (org.apache.aries.blueprint.annotation.collection)

	* @CollectionInject Inject list, set or array of existing beans of provided interface

	=== Bean annotations (org.apache.aries.blueprint.annotation.bean)

	* @Bean Mark a class as a bean or method as factory of bean

	=== Reference listener annotations (org.apache.aries.blueprint.annotation.referencelistener)

	* @ReferenceListener Marks bean as reference listener
	* @Bind Method of referenence listener to be called when service registers
	* @Unbind Method of referenence listener to be called when service unregisters

	=== Service annotations (org.apache.aries.blueprint.annotation.service)

	* @Service Publishes a bean as an OSGi service with the given interfaces
	* @ServiceProperty Defines a service property
	* @Reference Creates a reference to an OSGi service
	* @ReferenceList Creates a list of references of an OSGi services

	=== pax-cdi (supported in version 1.x, probably dropped in next major versions)

	* @OsgiServiceProvider(classes={TaskService.class}) Publishes a bean as an OSGi service with the given interfaces
	* @OsgiService creates a reference to an OSGi service.
	On optional filter is also possible
	* @Properties Defines service properties for OSGiServiceProvider
	* @Property Defines a service property

	=== Spring (supported in version 1.x, probably dropped in next major versions)

	* @Autowired Inject a bean by type and optionally further qualifiers
	* @Component Creates bean witd default or given name
	* @DependsOn Make bean depending on another bean
	* @Lazy Make bean lazy
	* @Qualifier Name injected bean
	* @Transactional mark the class as transactional
	* @Value Inject value or constant

	== Dependencies for annotations

	<dependency>
	<groupId>javax.inject</groupId>
	<artifactId>javax.inject</artifactId>
	<version>1</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>javax.enterprise</groupId>
	<artifactId>cdi-api</artifactId>
	<version>1.2</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>javax.persistence</groupId>
	<artifactId>persistence-api</artifactId>
	<version>1.0.2</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>javax.transaction</groupId>
	<artifactId>javax.transaction-api</artifactId>
	<version>1.2</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>org.apache.aries.blueprint</groupId>
	<artifactId>blueprint-maven-plugin-annotation</artifactId>
	<version>1.3.0</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>org.ops4j.pax.cdi</groupId>
	<artifactId>pax-cdi-api</artifactId>
	<version>0.8.0</version>
	<optional>true</optional>
	</dependency>
	<dependency>
	<groupId>org.apache.servicemix.bundles</groupId>
	<artifactId>org.apache.servicemix.bundles.spring-beans</artifactId>
	<version>3.2.11.RELEASE_1</version>
	<optional>true</optional>
	</dependency>

	Note that the annotations are needed only during build run, so you can exclude them or mark optional in Import-Package header of your bundle.

	== SPI

	Whole plugin is written using 'plugin architecture', so your own annotations could be configured for bleuprint generation.
	All you need to do, is to implement one of interfaces from blueprint-maven-plugin-spi:

	<dependency>
	<groupId>org.apache.aries.blueprint</groupId>
	<artifactId>blueprint-maven-plugin-spi</artifactId>
	<version>1.1.0</version>
	</dependency>

	Next add file (or files) to META-INF/services directory describing which interface implementation your artifact provides and add such artifact as plugin dependency

	<plugin>
	<groupId>org.apache.aries.blueprint</groupId>
	<artifactId>blueprint-maven-plugin</artifactId>
	<version>1.9.0</version>
	...
	<dependencies>
	<dependency>
	<groupId>org.apache.aries.blueprint.example</groupId>
	<artifactId>blueprint-maven-plugin-my-extension</artifactId>
	<version>1.0.0</version>
	</dependency>
	</dependencies>
	...
	</plugin>

	== Artifacts scanning configuration

	All artifacts are scaned for bean classes by default.
	It could be limited by includeArtifacts and excludeArtifacts parameters, e.
	g.

	<includeArtifacts>
	<includeArtifact>org.my.group.id:.*</includeArtifact>
	<includeArtifact>org.another.group.id:another.artifact.id:.*</includeArtifact>
	</includeArtifacts>
	<excludeArtifacts>
	<excludeArtifact>org.my.group.id:unwanted.artifact.id:.*</excludeArtifact>
	</excludeArtifacts>

	== Additional configuration

	Bean from factories are named by bean class nams or as defined in @Named or @Bean annotations.
	If you want to name such beans after producing method name then add configuration parameter:

	<configuration>
	<customParameters>
	<blueprint.beanFromFactory.nameFromFactoryMethodName>true</blueprint.beanFromFactory.nameFromFactoryMethodName>
	</customParameters>
	</configuration>

	== Example

	For a complete example see https://github.com/cschneider/Karaf-Tutorial/tree/master/tasklist-blueprint-cdi[tasklist-blueprint-cdi] on github or http://svn.apache.org/repos/asf/aries/trunk/blueprint/plugin/blueprint-maven-plugin/src/test/[tests of blueprint-maven-plugin].