<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2009</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights and limitations
      under the License.
    
    </legalnotice>

    <title>Installing cosNotification</title>
    <prepared>Niclas Eklund</prepared>
    <docno></docno>
    <date>2000-01-31</date>
    <rev></rev>
    <file>ch-install.xml</file>
  </header>

  <section>
    <title>Installation Process </title>
    <p>This chapter describes how to install <seealso marker="cosNotificationApp">cosNotificationApp</seealso>  
      in an Erlang Environment.
      </p>

    <section>
      <title>Preparation</title>
      <p>Before starting the installation process for cosNotification,
        the application Orber must be running.</p>
    </section>

    <section>
      <title>Configuration</title>
      <p>When using the Notification Service the <c>cosNotification</c> application 
        first must be installed using <c>cosNotificationApp:install()</c> or 
        <c>cosNotificationApp:install(Seconds)</c>, followed by <c>cosNotificationApp:start()</c>.</p>
      <p>Then the <seealso marker="CosNotifyChannelAdmin_EventChannelFactory">Event Channel Factory</seealso>
        must be started:</p>
      <list type="bulleted">
        <item><c>cosNotificationApp:start_global_factory()</c> - starts and returns a reference to a factory using default configuration parameters.
         This operation should be used for a multi-node Orber.</item>
        <item><c>cosNotificationApp:start_global_factory(Options)</c> - starts and returns a reference to a factory using given configuration parameters.
         This operation should be used for a multi-node Orber.</item>
        <item><c>cosNotificationApp:start_factory()</c> - starts and returns a reference to a factory using default configuration parameters.</item>
        <item><c>cosNotificationApp:start_factory(Options)</c> - starts and returns a reference to a factory using given configuration parameters.</item>
      </list>
      <p>The following options exist:</p>
      <list type="bulleted">
        <item><c>{pullInterval, Seconds}</c> - determine how often Proxy Pull 
         Consumers will check for new events with the client application. The
         default value is 20 seconds.</item>
        <item><c>{filterOp, OperationType}</c> - determine which type of Administrator
         objects should be started, i.e., <c>'OR_OP'</c> or <c>'AND_OP'</c>.
         The default value is <c>'OR_OP'</c>.</item>
        <item><c>{timeService, TimeServiceObj | 'undefined'}</c> - to be able to use
         Start and/or Stop QoS this option must be used. See the function <c>start_time_service/2</c>
         in the <c>cosTime</c> application. The default value is <c>'undefined'</c>.</item>
        <item><c>{filterOp, OperationType}</c> - determine which type of Administrator
         objects should be started, i.e., <c>'OR_OP'</c> or <c>'AND_OP'</c>.
         The default value is <c>'OR_OP'</c>.</item>
        <item><c>{gcTime, Seconds}</c> - this option determines how often, for example, proxies
         will garbage collect expired events. The default value is 60.</item>
        <item><c>{gcLimit, Amount}</c> - determines how many events will be stored before, for
         example, proxies will garbage collect expired events. The default value is 50. This
         option is tightly coupled with the QoS property <c>MaxEventsPerConsumer</c>, i.e.,
         the <c>gcLimit</c> should be less than <c>MaxEventsPerConsumer</c> and greater than 0.</item>
      </list>
      <p>It is possible to define a set of global configuration parameters:</p>
      <table>
        <row>
          <cell align="center" valign="middle"><em>Key</em></cell>
          <cell align="center" valign="middle"><em>Range</em></cell>
          <cell align="center" valign="middle"><em>Default</em></cell>
        </row>
        <row>
          <cell align="left" valign="middle">type_check</cell>
          <cell align="left" valign="middle">true | false</cell>
          <cell align="left" valign="middle">true</cell>
        </row>
        <row>
          <cell align="left" valign="middle">notify</cell>
          <cell align="left" valign="middle">atom() | false</cell>
          <cell align="left" valign="middle">false</cell>
        </row>
        <row>
          <cell align="left" valign="middle">max_events</cell>
          <cell align="left" valign="middle">integer() > 0</cell>
          <cell align="left" valign="middle">50</cell>
        </row>
        <row>
          <cell align="left" valign="middle">interval_events</cell>
          <cell align="left" valign="middle">integer() > 0</cell>
          <cell align="left" valign="middle">10000 milliseconds</cell>
        </row>
        <row>
          <cell align="left" valign="middle">timeout_events</cell>
          <cell align="left" valign="middle">integer() > interval_events</cell>
          <cell align="left" valign="middle">3000000 milliseconds</cell>
        </row>
        <tcaption>Global Configuration Parameters</tcaption>
      </table>
      <p><em>Comments on the table 'Global Configuration Parameters':</em></p>
      <taglist>
        <tag><em>type_check</em></tag>
        <item>Determine if supplied IOR:s shall be type checked, i.e. invoking 
         corba_object:is_a/2, or not.</item>
        <tag><em>notify</em></tag>
        <item>The given value shall point to an existing module exporting
         a function (arity 1) called <em>terminated</em>. This operation
         is invoked when a proxy terminates and the argument is a list
         containing <c>{proxy, IOR}</c>, <c>{client, IOR}</c> and 
        <c>{reason, term()}</c>. The return value is ignored.</item>
        <tag><em>max_events</em></tag>
        <item>If a supplier proxy has not been able to push events to a
         consumer and the queue exceeds this limit, then the proxy will
         terminate. For this option to have any effect, the
        <c>EventReliability</c> and <c>ConnectionReliability</c> QoS
         parameters must be set to <c>Persistent</c>. For more information,
         see also the <seealso marker="ch_QoS">QoS</seealso> chapter.</item>
        <tag><em>interval_events</em></tag>
        <item>The same requirements as for <c>max_events</c>. When a supplier
         proxy detects problems when trying to push events, this parameter
         determines how often it should try to call the consumer.</item>
        <tag><em>timeout_events</em></tag>
        <item>The same requirements as for <c>max_events</c>. If the
         proxy has not been able to contact the consumer and this
         time-limit is reached, then the proxy will terminate.</item>
      </taglist>
      <p>The Factory is now ready to use. For a more detailed description see 
        <seealso marker="ch_example">Examples</seealso>.</p>
    </section>
  </section>
</chapter>

