<commit_before><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="services">
  <title>Services</title>

  <section id="what-are-services">
    <title>What Are Services?</title>

    <para>Services are persistent background Ruby daemons deployed and
    managed by TorqueBox. Common uses for services include connecting
    to a remote service (IRC bot, Twitter Streaming API client) or
    starting a server to listen for incoming connections. A service
    may be deployed as part of a web application or as its own
    application without any web component. Services have full access
    to the entire Ruby environment. This means that a service deployed
    as part of a web application can interact with database models and
    other application functionality.</para>
  </section>

  <section id="service-classes">
    <title>Service Classes</title>

    <para>Each service maps to exactly one Ruby class that should
    optionally implement <methodname>initialize(Hash)</methodname>,
    <methodname>start()</methodname> and
    <methodname>stop()</methodname> methods which should each return
    quickly. Typically the <methodname>start</methodname> method will
    spawn a new thread to start an event loop or other long-running
    task.</para>

    <para><example>
      <title>Service implementation
      (<filename>my_service.rb</filename>)</title>

      <para><programlisting>class MyService
  def initialize(opts={})
    @name = opts['name']
  end

  def start
    Thread.new { run }
  end

  def stop
    @done = true
  end

  def run
    until @done
      puts "Hello #{@name}"
      sleep(1)
    end
  end
end</programlisting>This example service prints a message every second until stopped. By
      convention the long-running task is executed in a
      <methodname>run</methodname> method but could also reside inside the
      block passed to Thread.new in the <methodname>start</methodname>
      method.</para>
    </example></para>

    <para></para>
  </section>

  <section id="deploying-services">
    <title>Deploying Services</title>

    <para>Services are deployed by creating a services section inside
    your application's deployment descriptor.</para>

    <section id="services-format">
      <title>Configuration Format</title>

      <para>Within the internal <filename>torquebox.yml</filename> descriptor 
      (or through an external <filename><replaceable>*</replaceable>-knob.yml</filename> 
      descriptor), services reside under a <code>services</code> key of
      <filename>torquebox.yml</filename>. Each key underneath
      <code>services</code> is either a unique name for the service or
      the name of the Ruby class implementing the service. Providing a
      unique name allows the reuse of the same Ruby class to provide
      multiple services. If the Ruby class name is not used as the key, 
      it must be provided using the <code>service</code> key in the 
      key/value pairs nested underneath the service entry as 
      options for the service. Any value assigned to the <code>config</code>
      key underneath the service entry will be passed in as
      the parameter to the service's <methodname>initialize</methodname>
      method.</para>

      <para>If you are using the DSL (via <filename>torquebox.rb</filename>) in
      your internal descriptor, each service is defined using the 
      <methodname>service</methodname> directive, with very similar options to 
      the YAML syntax described above. The DSL does not require a name for 
      each job, unless you intend to share a job class across multiple jobs.</para>

      <para><example>
        <title>Example deployment descriptor</title>

        <para>Using the YAML syntax:<programlisting>services:
  MyService:
    config:
      name: TorqueBox User

  AnotherService:

  ham-machine:
    service: FoodMachine
    config: 
      food: ham
  
  biscuit-machine:
    service: FoodMachine
    config:
      food: biscuit</programlisting>This deploys four services;
        the first two using the class name as the key:
        <classname>MyService</classname> which corresponds to the
        example above and <classname>AnotherService</classname>
        which doesn't take any initialization parameters. The
        latter two services reuse the same class, and use a
        unique name as the key.</para>
        
       <para>And using the DSL:<programlisting>TorqueBox.configure do 
  ...
  service MyService do 
    config do
      name 'TorqueBox User'
    end
  end

  service AnotherService

  service FoodMachine do
    name 'ham-machine'
    config do
      food 'ham'
    end
  end

  service FoodMachine do
    name 'biscuit-machine'
    config do
      food 'biscuit'
    end
  end</programlisting></para>
      </example></para>

      <para>Service classes should be available in Ruby's load path. For
      Rails applications, the convention is to put your service
      classes in <filename>$RAILS_ROOT/app/services/</filename> and
      ensure this directory is on your load path.</para>

      <para><informalexample>
        <para><programlisting>config.autoload_paths += %W(#{config.root}/app/services)</programlisting></para>
      </informalexample></para>
    </section>
  </section>

  <section id="clustered-services">
    <title>Clustered Services</title>

    <section id="services-running-on-every-node">
      <title>Services Running on Every Node</title>

      <para>By default, if a service is deployed to every node in a
      cluster it will run on each node. This is useful for stateless
      services.</para>
    </section>

    <section id="ha-singleton-services">
      <title>High Availability Singleton Services</title>

      <para>TorqueBox also supports high availability singleton
      services. In this scenario, the service only runs on one node in
      the cluster and if that node goes down it automatically starts
      on a new node.</para>

      <para>To use high availability singleton services, you must
      start TorqueBox with a JBoss profile that supports
      clustering. In our binary distribution, this is the
      <code>all</code> profile.</para>

      <para><screen><prompt>$</prompt> JBOSS_CONF=all <command>jruby</command> <parameter>-S rake torquebox:run</parameter></screen></para>

      <para>You also need to add a special <code>singleton</code> key
      with a value of <code>true</code> to your services section of
      <filename>torquebox.yml</filename>. If no <code>singleton</code>
      key is defined or it has a value of <code>false</code> the
      service will run on every node in the cluster.</para>

      <para><example>
        <title>Example deployment descriptor</title>

        <para>Using the YAML syntax:<programlisting>services:
  MyService:
    singleton: true
    config:
      name: TorqueBox User

  AnotherService:

  ham-machine:
    service: FoodMachine
    config: 
      food: ham
  
  biscuit-machine:
    service: FoodMachine
    config:
      food: biscuit</programlisting></para>
        
       <para>And using the DSL:<programlisting>TorqueBox.configure do 
  ...
  service MyService do 
    singleton true
    config do
      name 'TorqueBox User'
    end
  end

  service AnotherService

  service FoodMachine do
    name 'ham-machine'
    config do
      food 'ham'
    end
  end

  service FoodMachine do
    name 'biscuit-machine'
    config do
      food 'biscuit'
    end
  end</programlisting>This is the same
        deployment descriptor from the example above but
        this time <classname>MyService</classname> is marked as a
        singleton and will only run on one node in the cluster.
        The remaining jobs will run on all nodes
        in the cluster since a <code>singleton</code> key isn't
        specified.</para>
      </example></para>
    </section>
  </section>

  <section id="resouce-injection-with-services">
    <title>Resource Injection with Services</title>

    <para>If a service requires access to other resources, such as messaging
    topics and queues, or Java CDI components these should be injected using
    the resource injection facilities provided by TorqueBox (see <xref
    linkend="resource-injection" />).</para>

    <para>In order for resource injection to function with services,
    they must reside either at the root of your application directory (typical
    for simple Rack applications), or underneath an
    <filename>app/services/</filename> directory. If you place the service anywhere
    else, it may still function, but resources injection will not be
    available.</para>
  </section>
</chapter>
<commit_msg>Update example of starting TB for HA singleton services to work with 2.x<commit_after><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="services">
  <title>Services</title>

  <section id="what-are-services">
    <title>What Are Services?</title>

    <para>Services are persistent background Ruby daemons deployed and
    managed by TorqueBox. Common uses for services include connecting
    to a remote service (IRC bot, Twitter Streaming API client) or
    starting a server to listen for incoming connections. A service
    may be deployed as part of a web application or as its own
    application without any web component. Services have full access
    to the entire Ruby environment. This means that a service deployed
    as part of a web application can interact with database models and
    other application functionality.</para>
  </section>

  <section id="service-classes">
    <title>Service Classes</title>

    <para>Each service maps to exactly one Ruby class that should
    optionally implement <methodname>initialize(Hash)</methodname>,
    <methodname>start()</methodname> and
    <methodname>stop()</methodname> methods which should each return
    quickly. Typically the <methodname>start</methodname> method will
    spawn a new thread to start an event loop or other long-running
    task.</para>

    <para><example>
      <title>Service implementation
      (<filename>my_service.rb</filename>)</title>

      <para><programlisting>class MyService
  def initialize(opts={})
    @name = opts['name']
  end

  def start
    Thread.new { run }
  end

  def stop
    @done = true
  end

  def run
    until @done
      puts "Hello #{@name}"
      sleep(1)
    end
  end
end</programlisting>This example service prints a message every second until stopped. By
      convention the long-running task is executed in a
      <methodname>run</methodname> method but could also reside inside the
      block passed to Thread.new in the <methodname>start</methodname>
      method.</para>
    </example></para>

    <para></para>
  </section>

  <section id="deploying-services">
    <title>Deploying Services</title>

    <para>Services are deployed by creating a services section inside
    your application's deployment descriptor.</para>

    <section id="services-format">
      <title>Configuration Format</title>

      <para>Within the internal <filename>torquebox.yml</filename> descriptor 
      (or through an external <filename><replaceable>*</replaceable>-knob.yml</filename> 
      descriptor), services reside under a <code>services</code> key of
      <filename>torquebox.yml</filename>. Each key underneath
      <code>services</code> is either a unique name for the service or
      the name of the Ruby class implementing the service. Providing a
      unique name allows the reuse of the same Ruby class to provide
      multiple services. If the Ruby class name is not used as the key, 
      it must be provided using the <code>service</code> key in the 
      key/value pairs nested underneath the service entry as 
      options for the service. Any value assigned to the <code>config</code>
      key underneath the service entry will be passed in as
      the parameter to the service's <methodname>initialize</methodname>
      method.</para>

      <para>If you are using the DSL (via <filename>torquebox.rb</filename>) in
      your internal descriptor, each service is defined using the 
      <methodname>service</methodname> directive, with very similar options to 
      the YAML syntax described above. The DSL does not require a name for 
      each job, unless you intend to share a job class across multiple jobs.</para>

      <para><example>
        <title>Example deployment descriptor</title>

        <para>Using the YAML syntax:<programlisting>services:
  MyService:
    config:
      name: TorqueBox User

  AnotherService:

  ham-machine:
    service: FoodMachine
    config: 
      food: ham
  
  biscuit-machine:
    service: FoodMachine
    config:
      food: biscuit</programlisting>This deploys four services;
        the first two using the class name as the key:
        <classname>MyService</classname> which corresponds to the
        example above and <classname>AnotherService</classname>
        which doesn't take any initialization parameters. The
        latter two services reuse the same class, and use a
        unique name as the key.</para>
        
       <para>And using the DSL:<programlisting>TorqueBox.configure do 
  ...
  service MyService do 
    config do
      name 'TorqueBox User'
    end
  end

  service AnotherService

  service FoodMachine do
    name 'ham-machine'
    config do
      food 'ham'
    end
  end

  service FoodMachine do
    name 'biscuit-machine'
    config do
      food 'biscuit'
    end
  end</programlisting></para>
      </example></para>

      <para>Service classes should be available in Ruby's load path. For
      Rails applications, the convention is to put your service
      classes in <filename>$RAILS_ROOT/app/services/</filename> and
      ensure this directory is on your load path.</para>

      <para><informalexample>
        <para><programlisting>config.autoload_paths += %W(#{config.root}/app/services)</programlisting></para>
      </informalexample></para>
    </section>
  </section>

  <section id="clustered-services">
    <title>Clustered Services</title>

    <section id="services-running-on-every-node">
      <title>Services Running on Every Node</title>

      <para>By default, if a service is deployed to every node in a
      cluster it will run on each node. This is useful for stateless
      services.</para>
    </section>

    <section id="ha-singleton-services">
      <title>High Availability Singleton Services</title>

      <para>TorqueBox also supports high availability singleton
      services. In this scenario, the service only runs on one node in
      the cluster and if that node goes down it automatically starts
      on a new node.</para>

      <para>To use high availability singleton services, you must
      start TorqueBox with a clustered configuration. For example:</para>

      <para><screen> <prompt>$</prompt> <command>$JBOSS_HOME/bin/standalone.sh --server-config=standalone-ha.xml</command></screen></para>

      <para>You also need to add a special <code>singleton</code> key
      with a value of <code>true</code> to your services section of
      <filename>torquebox.yml</filename>. If no <code>singleton</code>
      key is defined or it has a value of <code>false</code> the
      service will run on every node in the cluster.</para>

      <para><example>
        <title>Example deployment descriptor</title>

        <para>Using the YAML syntax:<programlisting>services:
  MyService:
    singleton: true
    config:
      name: TorqueBox User

  AnotherService:

  ham-machine:
    service: FoodMachine
    config: 
      food: ham
  
  biscuit-machine:
    service: FoodMachine
    config:
      food: biscuit</programlisting></para>
        
       <para>And using the DSL:<programlisting>TorqueBox.configure do 
  ...
  service MyService do 
    singleton true
    config do
      name 'TorqueBox User'
    end
  end

  service AnotherService

  service FoodMachine do
    name 'ham-machine'
    config do
      food 'ham'
    end
  end

  service FoodMachine do
    name 'biscuit-machine'
    config do
      food 'biscuit'
    end
  end</programlisting>This is the same
        deployment descriptor from the example above but
        this time <classname>MyService</classname> is marked as a
        singleton and will only run on one node in the cluster.
        The remaining jobs will run on all nodes
        in the cluster since a <code>singleton</code> key isn't
        specified.</para>
      </example></para>
    </section>
  </section>

  <section id="resouce-injection-with-services">
    <title>Resource Injection with Services</title>

    <para>If a service requires access to other resources, such as messaging
    topics and queues, or Java CDI components these should be injected using
    the resource injection facilities provided by TorqueBox (see <xref
    linkend="resource-injection" />).</para>

    <para>In order for resource injection to function with services,
    they must reside either at the root of your application directory (typical
    for simple Rack applications), or underneath an
    <filename>app/services/</filename> directory. If you place the service anywhere
    else, it may still function, but resources injection will not be
    available.</para>
  </section>
</chapter>

{'fraction_non_alphanumeric': 0.08445637277295569, 'fraction_numerical': 0.0009707629054362723, 'mean_word_length': 3.0765828677839853, 'pattern_counts': {'":': 0, '<': 361, '<?xml version=': 2, '>': 361, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 5}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6188574', 'n_tokens_mistral': 4845, 'n_tokens_neox': 4601, 'n_words': 1818}