<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2000</year><year>2013</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>Quality Of Service and Admin Properties</title>
    <prepared></prepared>
    <docno></docno>
    <date>2000-05-29</date>
    <rev></rev>
    <file>ch_QoS.xml</file>
  </header>

  <section>
    <title>Quality Of Service and Admin Properties</title>
    <p>This chapter explains the allowed properties for 
      <seealso marker="CosNotification_QoSAdmin">CosNotification_QoSAdmin</seealso> and
      <seealso marker="CosNotification_AdminPropertiesAdmin">CosNotification_AdminPropertiesAdmin</seealso>.
      </p>

    <section>
      <title>Quality Of Service</title>
      <p>The cosNotification application supports the following QoS settings:</p>
      <table>
        <row>
          <cell align="center" valign="middle"><em>QoS</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">EventReliability</cell>
          <cell align="left" valign="middle">BestEffort/Persistent</cell>
          <cell align="left" valign="middle">BestEffort</cell>
        </row>
        <row>
          <cell align="left" valign="middle">ConnectionReliability</cell>
          <cell align="left" valign="middle">BestEffort/Persistent</cell>
          <cell align="left" valign="middle">BestEffort</cell>
        </row>
        <row>
          <cell align="left" valign="middle">Priority</cell>
          <cell align="left" valign="middle">+/-32767</cell>
          <cell align="left" valign="middle">0</cell>
        </row>
        <row>
          <cell align="left" valign="middle">OrderPolicy</cell>
          <cell align="left" valign="middle">Any-, Fifo-, Priority- and Deadline-Order</cell>
          <cell align="left" valign="middle">PriorityOrder</cell>
        </row>
        <row>
          <cell align="left" valign="middle">DiscardPolicy</cell>
          <cell align="left" valign="middle">RejectNewEvents, Any-, Fifo-, Lifo-, Priority- and Deadline-Order</cell>
          <cell align="left" valign="middle">RejectNewEvents</cell>
        </row>
        <row>
          <cell align="left" valign="middle">MaximumBatchSize</cell>
          <cell align="left" valign="middle">long() > 0</cell>
          <cell align="left" valign="middle">1</cell>
        </row>
        <row>
          <cell align="left" valign="middle">PacingInterval</cell>
          <cell align="left" valign="middle">TimeBase::TimeT (see cosTime)</cell>
          <cell align="left" valign="middle">0</cell>
        </row>
        <row>
          <cell align="left" valign="middle">StartTimeSupported</cell>
          <cell align="left" valign="middle">boolean</cell>
          <cell align="left" valign="middle">false</cell>
        </row>
        <row>
          <cell align="left" valign="middle">StopTimeSupported</cell>
          <cell align="left" valign="middle">boolean</cell>
          <cell align="left" valign="middle">false</cell>
        </row>
        <row>
          <cell align="left" valign="middle">MaxEventsPerConsumer</cell>
          <cell align="left" valign="middle">long() > 0</cell>
          <cell align="left" valign="middle">100</cell>
        </row>
        <row>
          <cell align="left" valign="middle">Timeout</cell>
          <cell align="left" valign="middle">TimeBase::TimeT (see cosTime)</cell>
          <cell align="left" valign="middle">No timeout</cell>
        </row>
        <tcaption>Table 1: Supported QoS Settings</tcaption>
      </table>
      <br></br>
      <br></br>
      <br></br>
      <br></br>
      <p><em>Comments on the table 'Supported QoS Settings':</em></p>
      <taglist>
        <tag><em>EventReliability</em></tag>
        <item>To allow full Persistent EventReliability, every event must
         be stored in a stable storage which would create a relatively
         huge overhead. Hence, only lightweight version of the Persistent 
         QoS is supported. The configuration parameters <c>max_events</c>,
        <c>interval_events</c> and <c>timeout_events</c> determine
         the behavior of this setting.</item>
        <tag><em>ConnectionReliability</em></tag>
        <item>If this QoS is set to BestEffort and a client object returns anything
         other than <c>ok</c> to its associated Proxy, the Proxy will discard
         all events and terminate. Using Persistent and anything other than <c>ok</c> 
         is returned, events will be dropped but the proxy will retry later when
         next delivery is due. A child may not have Persistent while its parent
         has BestEffort QoS set, e.g., Proxy vs. Admin. If <c>OBJECT_NOT_EXIST</c>,
        <c>NO_PERMISSION</c> or <c>CosEventComm_Disconnected</c> is thrown,
         the associated object will terminate even if this parameter is
         set to Persistent.</item>
        <tag><em>Priority</em></tag>
        <item>This QoS will treat all events as if they have the Priority equal to
         current value, unless the event itself contains a Priority setting, 
         this event will be treated accordingly. Note: for this property to
         have any effect, the DiscardPolicy and/or OrderPolicy must be set
         to PriorityOrder.</item>
        <tag><em>OrderPolicy</em></tag>
        <item>If set to PriorityOrder, events with the highest Priority will be
         delivered first. Deadline order will forward events with shortest
         expiry time first. If two events have the same priority, they will be
         delivered in FIFO-order.</item>
        <tag><em>DiscardPolicy</em></tag>
        <item>If set to PriorityOrder and MaxEventsPerConsumer limit is 
         reached, events
         with the lowest Priority will be discarded first. Deadline order will
         discard events with shortest expiry time first.</item>
        <tag><em>MaximumBatchSize</em></tag>
        <item>Only valid if the object is supposed to handle a sequence of structured
         events and determines the largest amount of events that may be passed
         each time.</item>
        <tag><em>PacingInterval</em></tag>
        <item>Determines how long an object will wait before forwarding a structured 
         event sequence of length equal to, or less than MaximumBatchSize.
         If set to 0, which is the default behavior, no timeout is used and
         the events are forwarded when the MaximumBatchSize is reached.</item>
        <tag><em>StartTimeSupported</em></tag>
        <item>If set to true events which contains the QoS Property <c>StartTime</c> 
         (TimeBase::UtcT - absolute time) will not be delivered until the 
         StartTime value have been exceeded. See also the <c>cosTime</c> application.</item>
        <tag><em>StopTimeSupported</em></tag>
        <item>If set to true, events which contain the QoS Properties <c>StopTime</c>
         (TimeBase::UtcT - absolute time) or <c>Timeout</c> (TimeBase::TimeT - 
         relative time) will be discarded if the object has not been able to
         deliver the event in time. See also the <c>cosTime</c> application.</item>
        <tag><em>MaxEventsPerConsumer</em></tag>
        <item>The maximum number of events the associated object may store before discarding
         events in the way described by the DiscardPolicy.</item>
        <tag><em>Timeout</em></tag>
        <item>If this QoS property is not included in the event, and the Property
        <c>StopTimeSupported</c> equals true, this setting will be applied
         if events cannot be delivered within its time limit.</item>
      </taglist>
      <warning>
        <p>Several of the above QoS Properties can be changed during run-time but we strongly advice
          not to since, if a relatively large amount of events are waiting for delivery, some of the
          QoS settings would require a total reorder of the events. The QoS property <c>ConnectioReliability</c>
          may <em>never</em> be updated during run-time since it may cause deadlock. Run-time, in this case,
          means activating the Channel by sending the first event.</p>
      </warning>
    </section>

    <section>
      <title>Setting Quality Of Service</title>
      <p>Assume we have a Consumer Admin object which we want to change
        the current Quality of Service. Typical usage:</p>
      <code type="none">
QoSPersistent = 
   [#'CosNotification_Property'
    {name='CosNotification':'ConnectionReliability'(), 
     value=any:create(orber_tc:short(), 
     'CosNotification':'Persistent'())}],
'CosNotification_QoSAdmin':set_qos(Ch, QoSPersistent),
      </code>
      <p>If it is not possible to set the requested QoS the <c>UnsupportedQoS</c>
        exception is raised, which includes a sequence of <c>PropertyError</c>'s
        describing which QoS, possible range and why is not allowed. The error
        codes are:</p>
      <list type="bulleted">
        <item>UNSUPPORTED_PROPERTY - QoS not supported for this type of target object.</item>
        <item>UNAVAILABLE_PROPERTY - due to current QoS settings the given property
         is not allowed.</item>
        <item>UNSUPPORTED_VALUE - property value out of range; valid range is returned.</item>
        <item>UNAVAILABLE_VALUE - due to current QoS settings the given value is
         not allowed; valid range is returned.</item>
        <item>BAD_PROPERTY - unrecognized property.</item>
        <item>BAD_TYPE - type of supplied property is incorrect.</item>
        <item>BAD_VALUE - illegal value.</item>
      </list>
      <p>The CosNotification_QoSAdmin interface also supports an operation
        called <c>validate_qos/2</c>. The purpose of this operations is to check
        if a QoS setting is supported by the target object and if so, the operation
        returns additional properties which could be optionally added as well.</p>
    </section>

    <section>
      <title>Admin Properties</title>
      <p>The cosNotification application supports the following Admin Properties:</p>
      <table>
        <row>
          <cell align="center" valign="middle"><em>Property</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">MaxQueueLength</cell>
          <cell align="left" valign="middle">0</cell>
          <cell align="left" valign="middle">0</cell>
        </row>
        <row>
          <cell align="left" valign="middle">MaxConsumers</cell>
          <cell align="left" valign="middle">long() >= 0</cell>
          <cell align="left" valign="middle">0</cell>
        </row>
        <row>
          <cell align="left" valign="middle">MaxSuppliers</cell>
          <cell align="left" valign="middle">long() >= 0</cell>
          <cell align="left" valign="middle">0</cell>
        </row>
        <tcaption>Table 2: Supported Admin Properties</tcaption>
      </table>
      <p>According to the OMG specification the default values for Admin Properties
        is supposed to be <c>0</c>, which means that no limit applies to these
        properties.</p>
      <note>
        <p>Admin Properties can only be set on a Channel Object level, i.e.,
          they will not have an impact on any Admin or Proxy Objects. Currently,
          setting the Admin Property <c>MaxQueueLength</c> have no effect since
          we cannot discard events accordingly to the Quality of Service Property
          <c>DiscardPolicy</c>.</p>
      </note>
    </section>
  </section>
</chapter>

