amps-python-client 5.3.4.1__zip

amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/distribution.rst.txt

@@ -0,0 +1,186 @@
+.. index:: ampServer, distribution layout, AMPS binaries,
+
+.. _distribution:
+
+AMPS Distribution Layout
+=============================
+
+This appendix lists the layout of the AMPS distribution, with special focus
+on the binaries present in the layout. Use this appendix to plan your
+AMPS deployment.
+
+60East recommends that all AMPS deployments contain the full contents of
+the ``/bin`` and ``/lib`` directories. For development installations
+that are extending the AMPS server, your installation should contain the
+``/api`` and ``/sdk`` directories (as well as the *AMPS Server SDK*,
+available through 60East support).
+
+The AMPS distribution contains the following items at the top level:
+
+.. list-table:: *AMPS distribution contents*
+     :header-rows: 1
+
+     * - Item
+
+       - Description
+
+     * - ``/bin``
+         
+
+       - AMPS binaries: the AMPS server,
+         daemon deployment scripts, AMPS
+         utilities, and ``spark``.
+
+     * - ``/docs``
+         
+
+       - AMPS base documentation. Current
+         versions of the documentation and
+         additional guides are available from
+         the 60East website.
+
+     * - HISTORY
+         
+
+       - Information on the AMPS revision
+         history. In current distributions,
+         this provides a link to the entry
+         for this release of AMPS within
+         the full revision history on the
+         60East web site.
+
+     * - ``/lib``
+
+       - Libraries used by the AMPS binary.
+
+     * - LICENSE
+
+       - The AMPS license.
+
+     * - README
+
+       - The README file for AMPS.
+
+     * - ``/sdk``
+         
+
+       - Headers used for modules that extend
+         AMPS.
+
+
+
+/bin directory
+-------------------
+
+.. list-table:: *AMPS ``/bin`` directory contents*
+     :header-rows: 1
+
+     * - Item
+
+       - Description
+
+     * - ``amps_bio_perf_test``
+         
+
+       - Diagnostic tool for testing the
+         performance of I/O systems.
+
+     * - ``amps_client_ack_dump``
+         
+
+       - Utility for showing the contents of
+         the AMPS client.ack file, containing
+         persistent per-client information.
+
+     * - ``ampserr``
+         
+
+       - Utility for looking up details on
+         AMPS log file items.
+
+     * - ``ampServer``
+
+       - The AMPS server binary.
+
+     * - ``ampServer-compat``
+         
+
+       - The downward compatible version of
+         the AMPS server binary. This version
+         avoids using some of the hardware
+         capabilities present in newer CPU
+         architectures.
+
+     * - ``amps_file``
+         
+
+       - A utility for identifying the type
+         of AMPS files and the file format
+         that the file uses.
+
+     * - ``amps-init-script``
+         
+
+       - Part of the AMPS service
+         installation. This script is
+         installed into the init.d directory
+         when the AMPS service is installed.
+
+     * - ``amps_journal_dump``
+         
+
+       - Utility for extracting the contents
+         of AMPS transaction log journal
+         files.
+
+     * - ``amps_mt_perf_test``
+         
+
+       - Diagnostic tool for performance
+         testing of the AMPS engine parsing
+         infrastructure.
+
+     * - ``amps_sow_dump``
+         
+
+       - Utility for extracting the contents
+         of AMPS SOW files.
+
+     * - ``amps-sqlite3``
+         
+
+       - Convenience wrapper for querying an
+         AMPS statistics database.
+
+     * - ``amps_upgrade``
+         
+
+       - Utility for upgrading data files
+         from previous versions of AMPS to
+         the current version.
+
+     * - ``install-amps-daemon.sh``
+         
+
+       - Installation script for installing
+         AMPS as a Linux service.
+
+     * - ``/lib``
+         
+
+       - Directory containing the libraries
+         used by the ``spark`` utility.
+
+     * - ``spark``
+         
+
+       - Utility that provides a command-line
+         interface to AMPS.
+
+     * - ``uninstall-amps-daemon.sh``
+         
+
+       - Installation script for removing the
+         AMPS Linux service from the system.
+
+

amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/enrichment.rst.txt

@@ -0,0 +1,191 @@
+.. index:: message enrichment, SOW; message enrichment,
+
+.. _enrichment:
+
+State of the World Message Enrichment
+=====================================
+
+Topics recorded to the State of the World (SOW) can provide inline message
+enrichment for messages published to the topic. This capability is
+especially useful for applications that do consistent, simple
+transformations on incoming data. For example, you can use this
+capability to automatically add a calculated price to an incoming order,
+to map abbreviated data such as status codes to easier-to-understand
+values, or even to compute the value of a field used for a SOW key.
+
+AMPS provides two distinct stages of message enrichment: *preprocessing* and 
+*enrichment*. The *preprocessing* stage occurs before AMPS calculates the SOW 
+key for the message. Fields that are added or updated in the preprocessing 
+stage can be used as the SOW key for the message. Given that this stage occurs 
+before the SOW key is generated, this stage does not have access to the
+previous state of the message in the SOW. The enrichment stage occurs
+after AMPS calculates the SOW key. *Enrichment* performed at this stage
+has access to the previous state of the SOW.
+
+If entitlement for the instance uses content filters for publish
+entitlements, these filters are applied to the incoming message *before*
+either enrichment stage runs. For more details on the steps involved in
+enrichment, see :ref:`SOW Update and Enrichment<#ug-sow-update-sequence>`.
+
+Message enrichment only affects the message data, not the metadata on
+the message. In other words, while enrichment can change any field in
+the data, you cannot change metadata properties such as the topic the
+message was published to, the acknowledgments requested on the message,
+or the authenticated username for the publish command.
+
+Message enrichment rewrites the message before the messages are stored
+in AMPS or delivered to publishers. AMPS also provides the ability to
+aggregate or analyze messages while preserving the original state of the
+message, as described in the chapter on :ref:`Aggregating and Analyzing Data in AMPS <#ug-views>`.
+If a subscriber only needs a subset of data in a message, AMPS provides the
+ability for that subscriber to provide a *select list* to retrieve only the
+needed data.
+
+Preprocessing Messages
+-----------------------
+
+The preprocessing stage of AMPS enrichment allows you to alter a message
+before the SOW key is calculated. This gives you the ability to easily
+add or transform fields that are used in the SOW key. Use this stage to
+enrich messages when the enriched field should be used as part of the
+SOW key. To specify preprocessing for a topic, you add a
+``Preprocessing`` directive to the ``Topic`` configuration for the SOW
+topic.
+
+
+.. tip::
+
+   Use ``Preprocessing`` when you need to change the value of
+   a field that is part of the ``Key`` for the topic. Otherwise,
+   use ``Enrichment``.
+
+Preprocessing field directives operate on a single message and construct
+fields based on that message. The results of the preprocessing
+expression are merged into the incoming message. Any field in the source
+message that is not changed or removed during preprocessing is left
+unchanged, so it is not necessary to include all fields in the message
+in the ``Preprocessing`` block.
+
+Since preprocessing fields apply to a specific message, preprocessing
+fields cannot specify the topic or message type in an XPath identifier.
+
+By default, AMPS serializes fields with a NULL value in the preprocessing 
+result. Preprocessing fields can include a directive that specifies that 
+if a field contains a NULL value, it should be removed from the set of 
+fields rather than serialized. The directive ``HINT OPTIONAL`` applied 
+to the XPath identifier specifies that if the result of the source 
+expression is ``NULL``, AMPS does not provide the value for the message 
+type to serialize. For example, use the following directive to remove a 
+``/source`` field if the value provided is not in a specific list of values:
+
+.. code-block:: xml
+
+    <Field>IF(/source IN ('a','e','f'), /source, NULL)
+           AS /source HINT OPTIONAL</Field>
+
+For more information on constructing preprocessing fields, see
+:ref:`#construct-preprocessing-fields`.
+
+Enriching Messages
+--------------------
+
+AMPS enrichment operates on a message after the SOW key is computed, but
+before an incoming delta publish is merged to an existing message, or
+the incoming message is written to the transaction log, stored to the
+SOW, used to update views, or delivered to subscribers. Use this
+enrichment stage when the enrichment process depends on the previous
+values of the message, or when the updated fields will not be used in
+the SOW key. To specify enrichment for a topic, you add an
+``Enrichment`` directive to the configuration for the SOW topic.
+
+Enrichment field directives operate on a single message and construct
+fields based on that message. Enrichment expressions operate on the
+current message and change the current message. The results of the
+enrichment directives are merged into the incoming message. Any field in
+the source message that is not changed or removed during enrichment
+is left unchanged, so it is not necessary to include all fields in the
+message in the ``Enrichment`` directive.
+
+Since enrichment fields apply to a specific message, enrichment fields
+cannot specify the topic or message type in an XPath identifier.
+
+Within an enrichment expression, AMPS provides two special modifiers for
+XPath identifiers that specify whether an XPath identifier refers to the
+current incoming message or the previous state of the message. These
+modifiers apply only to the source expression, and cannot be used in
+special modifiers. They are:
+
+.. list-table:: *XPath Identifier Modifiers for Enrichment*
+     :header-rows: 1
+
+     * - Modifier
+
+       - Description
+
+     * - ``OF CURRENT``
+         
+
+       - Specify that the XPath identifier refers to the
+         incoming message.
+
+     * - ``OF PREVIOUS``
+         
+
+       - Specify that the XPath identifier refers to the
+         previous state of the message in the SOW. If there
+         is no record in the SOW for this message, all
+         identifiers that specify ``OF PREVIOUS`` return
+         ``NULL``.
+
+By default, AMPS serializes fields with a NULL value during enrichment.
+Enrichment fields can include a directive that specifies that if a field 
+contains a NULL value, it should be removed from the set of fields
+rather than serialized. The directive ``HINT OPTIONAL`` applied to the
+XPath identifier specifies that if the result of the source expression
+is ``NULL``, AMPS does not include the value in the set of XPath
+identifiers for the message type to serialize. For example, use the
+following directive to use remove a ``/source`` field if the value
+provided is not in a specific list of values:
+
+.. code-block:: xml
+
+    <Field>IF(/source IN ('a','e','f'), /source, NULL)
+           AS /source HINT OPTIONAL</Field>
+
+For more information on constructing enrichment fields, see
+:ref:`#construct-enrichment-fields` 
+and :ref:`#construct-preprocessing-fields`.
+
+.. _#ug-sow-update-sequence:
+
+SOW Update and Enrichment Processing
+-------------------------------------
+
+The following diagram presents a simplified, high-level view of the
+update process for an individual message. For the purposes of this
+diagram, views and conflated topics can be considered listeners on the
+SOW topic, while applications that connect to AMPS and the
+``on-publish`` and ``on-deliver`` actions can be considered subscribers.
+
+.. image:: ../../common/chapters/sow/svg/sow_update_sequence.svg
+   :width: 30.0%
+
+It's important to keep in mind the following aspects of the SOW update
+sequence:
+
+-  If the publish is disallowed due to topic-based entitlements or the
+   publish filter specified for entitlements, there is no change to the
+   state of the SOW. The entitlement filter (if one exists), is applied
+   to the incoming message *before* preprocessing, enrichment, or delta
+   merge occurs.
+
+-  AMPS records the enriched message in the transaction log and SOW
+   file. When AMPS is configured for enrichment or your application
+   performs a delta publish, the transaction log and SOW do *not*
+   preserve a record of the original message received by AMPS. Instead,
+   they record the enriched and merged message.
+
+-  Content filtering for subscriptions, views, and so forth is done on
+   the final enriched and merged message, not on the original message as
+   published.
+

amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/events.rst.txt

@@ -0,0 +1,39 @@
+.. index:: Events, AMPS; events, Client events, SOW events, State of the
+   World (SOW); events, AMPS; internal topics, Event topics, Internal event
+   topics, AMPS; topics,
+
+.. include:: ../macros.inc
+
+.. _#ug-event-topics:
+
+.. _events:
+
+Event Topics
+================
+
+AMPS publishes specific events to internal topics that begin with the
+``/AMPS/`` prefix, which is reserved for AMPS only. For example, all
+client connectivity events are published to the internal
+``/AMPS/ClientStatus`` topic. This allows all clients to monitor for
+events that may be of interest.
+
+.. tip::
+
+   You can subscribe to an event topic using a content filter,
+   just like any other topic within AMPS.
+
+
+A client may subscribe to event topics on any connection with a message
+type that supports views. This includes all of the default message types
+and ``bson``, but does not include the ``binary`` message type.
+
+Messages are delivered as the message type for the connection. For
+example, if the connection uses JSON messages, the event topic messages
+will be JSON. A connection that uses FIX will receive FIX messages from
+an event topic.
+
+.. include:: ./event_topics/client_status.inc
+
+.. include:: ./event_topics/sow_stats.inc
+
+.. include:: ./event_topics/persisting.inc

amps-python-client-5.3.4.1/docs/user-guide/html/_sources/chapters/file_format_versions.rst.txt

@@ -0,0 +1,203 @@
+.. include:: ../macros.inc
+
+.. _#ug-appendix-file-format-versions:
+
+.. _file_format_versions:
+
+File Format Versions
+=========================================
+
+This chapter includes a simple cross-reference to the file format versions in
+recent AMPS releases. Using this guide, you can quickly determine whether your
+installation will need to run ``amps_upgrade`` when changing versions.
+
+.. list-table:: *AMPS file format versions*
+     :header-rows: 1
+
+     * - AMPS version
+
+       - SOW version
+
+       - Journal version
+
+       - Acks version
+
+       - Queue Metadata version
+
+     * - 3.8
+
+       - v1.0
+
+       - v3
+
+       - v1.0
+
+       - 
+
+     * - 3.9
+
+       - v1.0
+
+       - v3
+
+       - v1.0
+
+       - 
+
+     * - 4.0
+
+       - v3.0
+
+       - v7
+
+       - v1.0
+
+       - 
+
+     * - 4.3
+
+       - v3.0
+
+       - v7
+
+       - v1.0
+
+       - 
+
+     * - 5.0
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.2
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.2.1
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.2.2
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.2.3
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.2.4
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.3.0
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.3.1
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.3.2
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.3.3
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - 
+
+     * - 5.3.4
+
+       - v3.0
+
+       - v8
+
+       - v1.0
+
+       - v001
+
+
+The ``amps_upgrade`` tool is provided for versions of AMPS 5.0 and earlier.
+The ``amps_upgrade`` tool updates the format of the data in the files that
+AMPS maintains. If there has been no version change to the format of the data,
+it is not necessary to run the tool to upgrade an AMPS instance.
+
+Notice that, while this chart describes the format of the files, AMPS versions
+may also change or extend the content of the files. In these cases, AMPS
+is guaranteed to be forward-compatible. That is, a given version of AMPS can
+process a file of the same file format version created on an earlier version
+of AMPS. However, later versions of AMPS may include changes in the content
+of the file that are not recognized by earlier versions of AMPS. This means
+that downgrading a file between major/minor versions of AMPS is not
+supported.
+
+.. caution::
+
+    The contents of AMPS files are not guaranteed to be backward
+    compatible across changes to the major or minor version number.
+    That is, while an AMPS instance of version X.4 can successfully
+    load a SOW file created by version X.3, the version X.3 instance
+    may not be able to process a file created or updated by the
+    X.4 version.
+
+    Contact 60East support for guidance if you intend to downgrade
+    an instance of AMPS to an earlier version.
+