buildframework/helium/sf/java/signaling/signalingCreateANewSignal.rst
author Jon Chatten
Fri, 12 Nov 2010 14:49:36 +0000
changeset 674 37ee82a83d43
parent 645 b8d81fa19e7d
permissions -rw-r--r--
sbs version 2.15.3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     1
==========================================
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     2
Configuring Signaling: Create a new signal
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     3
==========================================
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     4
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     5
This document will help you implementing a new signal in your configuration.  
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     6
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     7
Use case
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     8
--------
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
     9
You have one target named **custom-action** which
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    10
should generate an artifact in some know location, and you would like the build to continue as far 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    11
as possible even if that artifact is missing, but being informed during the build it is not going as expected. 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    12
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    13
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    14
Base configuration
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    15
------------------
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    16
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    17
The following code snippet will be the base configuration for this exercise.   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    18
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    19
build.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    20
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    21
.. code-block:: xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    22
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    23
   <?xml version="1.0" ?>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    24
   <project name="config" default="test" xmlns:hlm="http://www.nokia.com/helium"> 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    25
      <property environment="env"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    26
      <import file="${helium.dir}/helium_preinclude.ant.xml"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    27
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    28
      <!-- Location of the artifact -->    
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    29
      <property name="artifact" location="artifact.txt"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    30
            
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    31
      <import file="${helium.dir}/helium.ant.xml"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    32
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    33
      <!-- The target -->
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    34
      <target name="custom-action">
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    35
         <delete failonerror="false" file="${artifact}"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    36
         <if>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    37
            <istrue value="${create.artifact}"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    38
            <then>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    39
               <echo file="${artifact}">My artifact</echo>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    40
            </then>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    41
         </if>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    42
      </target>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    43
      
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    44
      <target name="custom-dummy">
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    45
        <echo message="Dummy action"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    46
      </target>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    47
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    48
   </project>   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    49
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    50
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    51
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    52
To declare a new signal to the framework you need to define a new signalListenerConfig reference.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    53
You also need to create a signalInput configuration to define your signal behaviour.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    54
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    55
.. code-block:: xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    56
 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    57
   <hlm:signalInput id="customActionSignalInput" failbuild="defer"/>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    58
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    59
   <hlm:signalListenerConfig id="customActionSignal" target="custom-action" message="custom-action target ended.">
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    60
      <signalNotifierInput>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    61
          <signalInput refid="customActionSignalInput" />
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    62
          <notifierInput file="${artifact}" />
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    63
      </signalNotifierInput>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    64
      <hlm:targetCondition>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    65
         <not><available file="${artifact}"/></not>            
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    66
      </hlm:targetCondition>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    67
   </hlm:signalListenerConfig>
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    68
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    69
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    70
The signalListenerConfig defines which target to listen and raise signal for. The target name is defined through the **target** attribute.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    71
Then the nested **targetCondition** element is used to configure how the signal should be triggered.
645
b8d81fa19e7d helium_12.0.0-63b64366f9cf
wbernard
parents: 587
diff changeset
    72
This element accepts any nested `Ant conditions <http://ant.apache.org/manual/Tasks/condition.html>`_.
587
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    73
In this case the signal will get raised only if the file is not present after the execution of the **custom-action** target.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    74
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    75
The framework then uses the defined signalInput from the signalNotifierInput configuration to know how to behave when the signal is raised. In the previous example it will
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    76
simply keep running and fail the build at the end. Then files defined by the nested notifierInput will be passed to the notifier.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    77
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    78
The execution of the **custom-action custom-dummy** build sequence will happen entirely even if the artifact is not 
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    79
created properly, then fail the build mentioning the faulty target::
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    80
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    81
   > hlm custom-action custom-dummy
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    82
   Internal data listening enabled.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    83
   Buildfile: build.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    84
        [echo]  Using build drive X:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    85
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    86
   custom-action:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    87
   18:21:14,503  INFO - Signal customActionSignal will be deferred.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    88
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    89
   custom-dummy:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    90
        [echo] Dummy action
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    91
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    92
   BUILD FAILED
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    93
   customActionSignal: custom-action target ended. : custom-action
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    94
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    95
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    96
   Total time: 2 seconds
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    97
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    98
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
    99
If you enable the artifact creation then the build will proceed successfully::
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   100
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   101
   >hlm custom-action custom-dummy -Dcreate.artifact=true
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   102
   Internal data listening enabled.
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   103
   Buildfile: build.xml
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   104
        [echo]  Using build drive X:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   105
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   106
   custom-action:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   107
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   108
   custom-dummy:
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   109
        [echo] Dummy action
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   110
   
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   111
   BUILD SUCCESSFUL
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   112
   Total time: 2 seconds
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   113
85df38eb4012 helium_9.0-a7879c935424
wbernard
parents:
diff changeset
   114