How to create a new signal
==========================

This document will help you implementing a new signal in your configuration.  

Use case
--------
You have one target named **custom-action** which
should generate an artifact in some know location, and you would like the build to continue as far 
as possible even if that artifact is missing, but being informed during the build it is not going as expected. 


Base configuration
------------------

The following code snippet will be the base configuration for this exercise.   

build.xml

.. code-block:: xml

   <?xml version="1.0" ?>
   <project name="config" default="test" xmlns:hlm="http://www.nokia.com/helium"> 
      <property environment="env"/>
      <import file="${helium.dir}/helium_preinclude.ant.xml"/>

      <!-- Location of the artifact -->    
      <property name="artifact" location="artifact.txt"/>
            
      <import file="${helium.dir}/helium.ant.xml"/>

      <!-- The target -->
      <target name="custom-action">
         <delete failonerror="false" file="${artifact}"/>
         <if>
            <istrue value="${create.artifact}"/>
            <then>
               <echo file="${artifact}">My artifact</echo>
            </then>
         </if>
      </target>
      
      <target name="custom-dummy">
        <echo message="Dummy action"/>
      </target>
   
   </project>   



To declare a new signal to the framework you need to define a new signalListenerConfig reference.
You also need to create a signalInput configuration to define your signal behaviour.

.. code-block:: xml
 
   <hlm:signalInput id="customActionSignalInput" failbuild="defer"/>
   
   <hlm:signalListenerConfig id="customActionSignal" target="custom-action" message="custom-action target ended.">
      <signalNotifierInput>
          <signalInput refid="customActionSignalInput" />
          <notifierInput file="${artifact}" />
      </signalNotifierInput>
      <hlm:targetCondition>
         <not><available file="${artifact}"/></not>            
      </hlm:targetCondition>
   </hlm:signalListenerConfig>


The signalListenerConfig defines which target to listen and raise signal for. The target name is defined through the **target** attribute.
Then the nested **targetCondition** element is used to configure how the signal should be triggered.
This element accepts any nested `Ant conditions <http://ant.apache.org/manual/CoreTasks/conditions.html>`_.
In this case the signal will get raised only if the file is not present after the execution of the **custom-action** target.

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
simply keep running and fail the build at the end. Then files defined by the nested notifierInput will be passed to the notifier.

The execution of the **custom-action custom-dummy** build sequence will happen entirely even if the artifact is not 
created properly, then fail the build mentioning the faulty target::

   > hlm custom-action custom-dummy
   Internal data listening enabled.
   Buildfile: build.xml
        [echo]  Using build drive X:
   
   custom-action:
   18:21:14,503  INFO - Signal customActionSignal will be deferred.
   
   custom-dummy:
        [echo] Dummy action
   
   BUILD FAILED
   customActionSignal: custom-action target ended. : custom-action
   
   
   Total time: 2 seconds


If you enable the artifact creation then the build will proceed successfully::

   >hlm custom-action custom-dummy -Dcreate.artifact=true
   Internal data listening enabled.
   Buildfile: build.xml
        [echo]  Using build drive X:
   
   custom-action:
   
   custom-dummy:
        [echo] Dummy action
   
   BUILD SUCCESSFUL
   Total time: 2 seconds