The R13B03 release.OTP_R13B03

1 files changed, 251 insertions, 0 deletions

diff --git a/lib/cosNotification/doc/src/ch_QoS.xml b/lib/cosNotification/doc/src/ch_QoS.xml
new file mode 100644
index 0000000000..fbc8622a62
--- /dev/null
+++ b/lib/cosNotification/doc/src/ch_QoS.xml
@@ -0,0 +1,251 @@
+<?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>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>
+