felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Apache Felix SCR Ant Task Use
Date Wed, 13 Jun 2012 13:15:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+SCR+Ant+Task+Use">Apache
Felix SCR Ant Task Use</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~cziegeler@apache.org">Carsten
Ziegeler</a>
    </h4>
        <br/>
                         <h4>Changes (2)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >  &lt;taskdef <br>    resource=&quot;scrtask.properties&quot;
<br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">classpath=&quot;org.apache.felix.scr.ant-1.0.0-SNAPSHOT.jar&quot;</span>
<span class="diff-added-words"style="background-color: #dfd;">classpath=&quot;org.apache.felix.scr.ant-1.1.4.jar&quot;</span>
/&gt; <br></td></tr>
            <tr><td class="diff-unchanged" > <br>&lt;/project&gt;
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >| annotationTagProviders | No | --
| List of fully qualified class names providing more Annotation Tag Providers. As of version
1.4.0 of the SCR Annotations library this configuration element is optional if the SCR Annotations
library comes with a proper SPI setup (see [Extending SCR Annotations]) | <br>| specVersion
| No | Auto-Detected | The plugin will generate a descriptor for the Declarative Service version
(either 1.0 or 1.1). If no value is specified, the plugin will detect the version and only
use 1.1 if features from this version are used. | <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">|
strictMode | No | false | If set to true, a warning will be considered as an error and the
build will fail with warnings generated by this task. | <br>| parseJavadoc | No | true
| If set to true, javadoc based annotations will be processed. | <br>| processAnnotations
| No | true | If set to true, SCR annotations will be processed | <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        

<p>The SCR Ant Task is implemented in the <tt>org.apache.felix.scr.ant</tt>
library which must be registered as an Ant Task in the build file as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;project ...&gt;</span>

  &lt;taskdef
    resource=<span class="code-quote">"scrtask.properties"</span>
    classpath=<span class="code-quote">"org.apache.felix.scr.ant-1.1.4.jar"</span>
/&gt;

<span class="code-tag">&lt;/project&gt;</span>
</pre>
</div></div>

<p>Of course the value you set in the <tt>classpath</tt> attribute depends
on the actual location of the <tt>org.apache.felix.scr.ant</tt> JAR file.</p>

<p>The SCR Ant Task is available for download from the Apache Felix <a href="http://felix.apache.org/site/downloads.cgi"
class="external-link" rel="nofollow">Downloads</a> page.</p>

<p><b>Notes</b>:</p>
<ul>
	<li>The name of the task is <tt>scr</tt></li>
	<li>The task requires that the source files have already been compiled</li>
</ul>


<p>The task only generates the descriptor file(s). If you want to use the Declarative
Services descriptor &#8211; by default generated in the <tt>OSGI-INF/serviceComponents.xml</tt>
&#8211; you must make sure to add a <tt>Service-Components</tt> header to
your bundle manifest. Unlike Maven plugin the Ant task cannot automatically generate this
header.</p>


<h2><a name="ApacheFelixSCRAntTaskUse-TaskAttributes"></a>Task Attributes</h2>

<p>Like the standard <tt>javac</tt> Ant Task, the SCR Ant Task defines an
implicit fileset which defines the source files to be scanned for Java 5 Annotations or JavaDoc
Tags. In addition to the child elements available to Ant Fileset as defined for <a href="http://ant.apache.org/manual/dirtasks.html#directorybasedtasks"
class="external-link" rel="nofollow">directory-based tasks</a> the following task
attributes:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Attribute </th>
<th class='confluenceTh'> Required </th>
<th class='confluenceTh'> Default </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> scrdir </td>
<td class='confluenceTd'> Yes </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> The root directory of the implicitly defined fileset denoting
the files to consider for annotation and/or JavaDoc tag processing. </td>
</tr>
<tr>
<td class='confluenceTd'> destdir </td>
<td class='confluenceTd'> Yes </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> The name of the directory where the descriptor files are generated
into. This is also used as the directory where the compiled classes from the <tt>srcdir</tt>
may be located. This directory is actually added as another element to the classpath as defined
by <tt>classpath</tt> and <tt>classpathRef</tt>. </td>
</tr>
<tr>
<td class='confluenceTd'> classpath </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> The class path used to load classes from to analyse for the
descriptor file generation. Generally this will be the same class path as the one used to
compile the sources. </td>
</tr>
<tr>
<td class='confluenceTd'> classpathRef </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> A reference to a class path used to load classes from to analyse
for the descriptor file generation. Generally this will be the same class path as the one
used to compile the sources. </td>
</tr>
<tr>
<td class='confluenceTd'> finalName </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> <tt>serviceComponents.xml</tt> </td>
<td class='confluenceTd'> The name of the descriptor file to create. This file is always
located inside the <tt>OSGI-INF</tt> folder in the <tt>destdir</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> metaTypeName </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> <tt>metatype.xml</tt> </td>
<td class='confluenceTd'> The name of the descriptor file to create. This file is always
located inside the <tt>OSGI-INF/metatype</tt> folder in the <tt>destdir</tt>.
</td>
</tr>
<tr>
<td class='confluenceTd'> generateAccessors </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> <tt>true</tt> </td>
<td class='confluenceTd'> If this switch is turned on, the bind and unbind methods for
unary references are automatically generated by the plugin. </td>
</tr>
<tr>
<td class='confluenceTd'> annotationTagProviders </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> &#8211; </td>
<td class='confluenceTd'> List of fully qualified class names providing more Annotation
Tag Providers. As of version 1.4.0 of the SCR Annotations library this configuration element
is optional if the SCR Annotations library comes with a proper SPI setup (see <a href="/confluence/display/FELIX/Extending+SCR+Annotations"
title="Extending SCR Annotations">Extending SCR Annotations</a>) </td>
</tr>
<tr>
<td class='confluenceTd'> specVersion </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> Auto-Detected </td>
<td class='confluenceTd'> The plugin will generate a descriptor for the Declarative
Service version (either 1.0 or 1.1). If no value is specified, the plugin will detect the
version and only use 1.1 if features from this version are used. </td>
</tr>
<tr>
<td class='confluenceTd'> strictMode </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> false </td>
<td class='confluenceTd'> If set to true, a warning will be considered as an error and
the build will fail with warnings generated by this task. </td>
</tr>
<tr>
<td class='confluenceTd'> parseJavadoc </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> true </td>
<td class='confluenceTd'> If set to true, javadoc based annotations will be processed.
</td>
</tr>
<tr>
<td class='confluenceTd'> processAnnotations </td>
<td class='confluenceTd'> No </td>
<td class='confluenceTd'> true </td>
<td class='confluenceTd'> If set to true, SCR annotations will be processed </td>
</tr>
</tbody></table>
</div>



<p>The <tt>scr</tt> task must be provided with the same class path as was
used to compile the sources. The classes in the class path are used by the task to be able
to load compiled classes (mostly for Java 5 annotation processing) and any base classes, which
may be extended. The easiest way to share the class path is to define a class path property
and refer to it with the <tt>classpathref</tt> attribute of the <tt>scr</tt>
task.</p>


<h2><a name="ApacheFelixSCRAntTaskUse-UsingJavaDocTags"></a>Using JavaDoc
Tags</h2>

<p>JavaDoc tags are supported natively by the SCR Ant Task. No further configuration
and/or libraries are needed.</p>


<h2><a name="ApacheFelixSCRAntTaskUse-Java5Annotations"></a>Java 5 Annotations</h2>

<p>To use Java 5 Annotations make sure the library defining the annotations is available
on the class path for both the compilation in the <tt>javac</tt> task and for
generating the descriptor in the <tt>scr</tt> task.</p>

<p>No further configuration is required as the SCR Ant Task automatically recognizes
SCR Annotation definitions from libraries in the class path provided the annotations are provided
in a JAR library with properly setup SPI configuration as documented in <a href="/confluence/display/FELIX/Extending+SCR+Annotations"
title="Extending SCR Annotations">Extending SCR Annotations</a>.</p>


<h2><a name="ApacheFelixSCRAntTaskUse-Example"></a>Example</h2>

<p>The following is very simple example build file based on the <a href="http://svn.apache.org/repos/asf/sling/trunk/bundles/jcr/webconsole"
class="external-link" rel="nofollow">Apache Sling JCR WebConsole</a> bundle:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;project default=<span class="code-quote">"scr"</span>
basedir=<span class="code-quote">"."</span>&gt;</span>

  &lt;taskdef resource=<span class="code-quote">"scrtask.properties"</span>
      classpath=<span class="code-quote">"org.apache.felix.scr.ant-1.0.0-SNAPSHOT.jar"</span>
/&gt;

  <span class="code-tag">&lt;target name=<span class="code-quote">"init"</span>&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"src"</span>
value=<span class="code-quote">"src/main/java"</span> /&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"classes"</span>
value=<span class="code-quote">"target/classes"</span> /&gt;</span>
    <span class="code-tag">&lt;property name=<span class="code-quote">"m2Repo"</span>
value=<span class="code-quote">"${user.home}/.m2/repository"</span> /&gt;</span>
    <span class="code-tag">&lt;path id=<span class="code-quote">"dependencies"</span>&gt;</span>
      <span class="code-tag">&lt;fileset dir=<span class="code-quote">"${m2Repo}"</span>&gt;</span>
        <span class="code-tag">&lt;include name=<span class="code-quote">"javax/jcr/jcr/1.0/jcr-1.0.jar"</span>
/&gt;</span>
        <span class="code-tag">&lt;include name=<span class="code-quote">"org/apache/sling/org.apache.sling.jcr.api/2.0.6/org.apache.sling.jcr.api-2.0.6.jar"</span>
/&gt;</span>
        <span class="code-tag">&lt;include name=<span class="code-quote">"org/apache/felix/org.apache.felix.webconsole/3.0.0/org.apache.felix.webconsole-3.0.0.jar"</span>
/&gt;</span>
        <span class="code-tag">&lt;include name=<span class="code-quote">"javax/servlet/servlet-api/2.4/servlet-api-2.4.jar"</span>
/&gt;</span>
        <span class="code-tag">&lt;include name=<span class="code-quote">"org/apache/felix/org.apache.felix.scr.annotations/1.4.0/org.apache.felix.scr.annotations-1.4.0.jar"</span>
/&gt;</span>
      <span class="code-tag">&lt;/fileset&gt;</span>
    <span class="code-tag">&lt;/path&gt;</span>
  <span class="code-tag">&lt;/target&gt;</span>

  <span class="code-tag">&lt;target name=<span class="code-quote">"compile"</span>
depends=<span class="code-quote">"init"</span>&gt;</span>
      <span class="code-tag">&lt;mkdir dir=<span class="code-quote">"${classes}"</span>
/&gt;</span>
      <span class="code-tag">&lt;javac srcdir=<span class="code-quote">"${src}"</span>
destdir=<span class="code-quote">"${classes}"</span> classpathref=<span class="code-quote">"dependencies"</span>
/&gt;</span>
  <span class="code-tag">&lt;/target&gt;</span>

  <span class="code-tag">&lt;target name=<span class="code-quote">"scr"</span>
depends=<span class="code-quote">"compile"</span>&gt;</span>
    <span class="code-tag">&lt;scr srcdir=<span class="code-quote">"${src}"</span>
destdir=<span class="code-quote">"${classes}"</span> classpathref=<span class="code-quote">"dependencies"</span>
/&gt;</span>
  <span class="code-tag">&lt;/target&gt;</span>

  <span class="code-tag">&lt;target name=<span class="code-quote">"clean"</span>&gt;</span>
    <span class="code-tag">&lt;delete dir=<span class="code-quote">"target"</span>
/&gt;</span>
  <span class="code-tag">&lt;/target&gt;</span>

<span class="code-tag">&lt;/project&gt;</span>
</pre>
</div></div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+SCR+Ant+Task+Use">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=24183588&revisedVersion=9&originalVersion=8">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+SCR+Ant+Task+Use?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message