# AMPS Module Reference

exception `AMPS.``AMPSException`

  Bases: `Exception`

  The base exception class for all exceptions in the AMPS Python Client.

exception `AMPS.``AlreadyConnected`

  Bases: `AMPS.ConnectionException`

  deprecated - use `AlreadyConnectedException`

exception `AMPS.``AlreadyConnectedException`

  Bases: `AMPS.AlreadyConnected`

  The AlreadyConnectedExcpetion is raised when a client attemptsmultiple connections to an AMPS instance after being successfullyconnected.

exception `AMPS.``AuthenticationError`

  Bases: `AMPS.ConnectionException`

  deprecated - use `AuthenticationException`

exception `AMPS.``AuthenticationException`

  Bases: `AMPS.AuthenticationError`

  The AuthenticationException is raised when the credentials provided to the client fail in AMPS authentication.

exception `AMPS.``BadFilter`

  Bases: `AMPS.CommandException`

  deprecated - use `BadFilterException`

exception `AMPS.``BadFilterException`

  Bases: `AMPS.BadFilter`

  The BadFilterException is raised when a query contains invalid content or is not used against a valid topic or field.

exception `AMPS.``BadRegexTopic`

  Bases: `AMPS.CommandException`

  deprecated - use `BadRegexTopicException`

exception `AMPS.``BadRegexTopicException`

  Bases: `AMPS.BadRegexTopic`

  The BadRegexTopicException is raised when a topic query containing a regular expression is unable to be compiled by the AMPS regular expression compiler.

exception `AMPS.``BadSowKeyException`

  Bases: `AMPS.CommandException`

  The BadSowKeyException is raised when command uses an invalid sow key

class `AMPS.``CMessageHandler`

  Bases: `object`

  Wraps a C/C++ message handler function for use as a higher-performance AMPS message handler. To use, create a shared library or DLL with an exported function of type AMPS::MessageHandlerFunc, for example:

  > extern “C” void my_message_handler(const AMPS::Message& message, void* userdata) { ... }

  and then use the python ctypes module to load and supply it:

  > import ctypes

  > client = AMPS.Client(...) ... my_dll = ctypes.CDLL(”./mymessagehandler.so”) # load my DLL client.subscribe( AMPS.CMessageHandler( my_dll.my_message_handler, “user data”), “my_amps_topic” )

  As messages arrive they are sent directly to my_message_handler, without passing through the python interpreter
    or taking the python global interpreter lock, resulting in potentially higher performance.
  NOTE: no checking is performed to make sure your C/C++ function is of the appropriate signature. Supplying
    a function of a different signature than that shown results in undefined behavior.

class `AMPS.``Client`

  Bases: `object`

  > The base AMPS Client object used in AMPS applications. Each Client object manages a single connection to AMPS. Each AMPS connection has a name, a specific transport (such as tcp), a protocol (used for framing messages to AMPS), and a message type (such as FIX or JSON).

  > The Client object creates and manages a background thread, and sends and receives messages on that thread. The object provides both a synchronous interface for processing messages on the calling thread, and an asynchronous interface suitable for populating a queue to be processed by worker threads.

  > Each Client has a name. The AMPS server uses this name for duplicate message detection, so the name of each instance of the client application should be unique.

  > > An example of a simple Python client publishing a JSON message is listed below:

  > >     c = Client("test_client")

  > >     try:
  > >         c.connect("tcp://127.0.0.1:9004/json")
  > >         cid = c.logon()
  > >         c.publish("topic_name",'{"a":1,"b":"2"}')
  > >     finally:
  > >         c.close()

  Constructor arguments:

  Parameters: | name – the unique name for this client. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoid using control characters, newline characters, or square brackets.

  class `Bookmarks`

    Bases: `object`

    This class provides special values for bookmark subscriptions:

    > - `EPOCH` begin the subscription at the beginning of the journal
    > - `MOST_RECENT` begin the subscription at the first undiscarded message in the bookmark store, or at the end of the bookmark store if all messages have been discarded
    > - `NOW` begin the subscription at the time that AMPS processes the subscription

    For example, to begin a bookmark subscription at the beginning of the journal, provide `AMPS.Client.Bookmarks.EPOCH` as the bookmark in the call to `AMPS.Client.bookmark_subscribe()`.

  class `Client.``ConnectionStateListener`

    Bases: `object`

    AMPS ConnectionStateListener type used to determine the new connection state.

  `Client.``ack`(message, options=None) OR ack(topic, bookmark, options=None)

    ACKs a message queue message.

    :param message an AMPS.Message object to ack, OR :param topic The topic of the message to ACK :param bookmark The bookmark of the message to ACK. :param options An optional string to include in the ACK such as ‘cancel’.

  `Client.``add_connection_state_listener`(listener_callable)

    Sets a function to be called when this client connects or disconnects from AMPS.

    Parameters: | listener_callable (A python function or other callable that takes a single value) – The function or callable to be called. This function will be passed True if a connection is established, False if a disconnect occurs. Notice that when a connection is established, the client has not yet logged in or completed any recovery steps. The application should not issue commands on the client until recovery is completed.

  `Client.``add_message_handler`(command_id, message_handler, acks, is_subscribe)

    > Add a message handler to the `Client` to handle messages and the requested acks sent in response to the given command_id.

    Parameters: | command_id (str) – The command, query, or sub id for messages and acks. message_handler (`MessageHandler`) – The message handler that will receive messages for the command_id. acks (int) – The acks requested to go to the message_handler. is_subscribe (int) – If the message_handler is for a subscribe command.

  `Client.``allocateMessage`()

    A legacy method name for `allocate_message()`.

  `Client.``allocate_message`()

    > Creates a new `Message` appropriate for this client.

    > > This function should be called rarely, since it does allocate a handful of small objects.

    Returns: | A new Message instance.

  `Client.``bookmark_subscribe`(on_message, topic, bookmark, filter=None, sub_id=None, options=None, timeout=0)

    > Places a bookmark subscription with AMPS. Starts replay at the most
    >   recent message reported by the bookmark parameter.

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with matching messages. topic (str) – The Topic to subscribe to. bookmark (str) – A bookmark identifier, or one of the constants from `Bookmarks` filter (str) – The filter. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the ‘replace’ option, this is the subscription to be replaced. With a bookmark store, this is the subscription ID used for recovery. So, when using a persistent bookmark store, provide an explicit subscription id that is consistent across application restarts. options (str) – A comma separated string of options. Default is None. timeout (int) – The maximum time to wait for the client to receive and and consume a processed ack for this subscription (in milliseconds). `0` indicates to wait indefinitely.
    Raises: | `SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`.

  `Client.``close`()

    Disconnect from the AMPS server.

  `Client.``connect`(uri)

    > Connects to the AMPS instance through the provided `URI`.

    > > The `URI` is a string with the format:
    > >   `transport://userId:password@host:port/protocol` where:
    > > - transport – The network transport used for the connection.
    > > - userId – If authentication is enabled, this is the unique user ID
    > >     used to authenticate the connection.
    > > - password – If authentication is enabled, this is the password used
    > >     to authenticate the connection.
    > > - host – The hostname or IP address of the host where AMPS is
    > >     installed.
    > > - port – The port to connect to the AMPS instance.
    > > - protocol – The protocol used by this connection.

    > > Note

    > > Authentication is optional, if the system is using the default authentication with AMPS which allows all users in without regard for their `userId` or `password`, then the `userId:password@` string can be omitted from the connect URI.

    Parameters: | uri (str) – The :class`URI` used to connect to AMPS.
    Raises: | `ConnectionException`

  `Client.``convert_version_to_number`()

    convert_version_to_number(version)Converts the provided version string to a number using 2 digits for each dot. A value such as 4.0 will become 4000000 while 3.8.1.7 will return 3080107.

    Parameters: | version (str) – The version string to convert.
    Returns: | The numeric value for the version string.

  `Client.``deltaPublish`(topic, data)

    This is a legacy method name for `delta_publish()`.

    > Deprecated since version 3.2.0.0: Use `delta_publish()` instead.

  `Client.``deltaSubscribe`(on_message, topic, filter=None, options=0, timeout=0)

    A legacy method name for `delta_subscribe()`.

    > Deprecated since version 3.2.0.0: Use `delta_subscribe()` instead.

  `Client.``delta_publish`(topic, data, expiration=None)

    Delta publish a message to an AMPS topic. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS.

    Parameters: | topic (str) – Topic to publish the data to. data (str) – Data to publish to the topic. expiration (int) – Number of seconds until published message should expire.
    Returns: | The sequence number assigned to this message by the publish store or 0 if there is no publish store and the server is assigning sequence numbers.
    Raises: | `DisconnectedException`

  `Client.``delta_subscribe`(on_message, topic, filter=None, options=0, timeout=0, sub_id=None)

    Places a delta subscription with AMPS.

    Parameters: | on_message (str) – The message handler to invoke with matching messages. topic (str) – The topic to subscribe to. filter (str) – The filter. options (str) – A comma separated list of values indicating additional processing options. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this subscription (in milliseconds). `0` indicates to wait indefinitely. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the ‘replace’ option, this is the subscription to be replaced.
    Returns: | The command identifier assigned to this command.
    Raises: | `SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``disconnect`()

    Disconnects and closes any active connections.

  `Client.``execute`()

    Executes a Command on self.

    Param: | An AMPS.Command to execute.
    Returns: | A MessageStream to iterate over.

  `Client.``execute_async`()

    Execute the provided command and process responses on the client receive thread using the provided handler.

    This method creates a `Message` based on the provided `Command`, sends the `Message` to AMPS, and invokes the provided handler to process messages returned in response to the command. Rather than providing messages on the calling thread, the AMPS Python client runs the handler directly on the client receive thread.

    When the provided handler is not `None`, this function blocks until AMPS acknowledges that the command has been processed. The results of the command after that acknowledgement are provided to the handler.

    Parameters: | command (AMPS.Command) – The command to execute. on_message (a function or other callable object.) – A handler for messages returned by this command execution.
    Returns: | The command ID assigned to the executed command.

  `Client.``flush`(timeout = 0)

    Another name for `publish_flush()`.

  `Client.``getName`()

    A legacy method name for `get_name()`.

  `Client.``get_ack_batch_size`()

    Returns the current batch size used for batching message queue ACK messages.

  `Client.``get_ack_timeout`()

    Returns the current time (milliseconds) before queued ack messages are sent.

  `Client.``get_auto_ack`()

    Returns True if auto-acknowledgement of message queue messages is enabled.

  `Client.``get_default_max_depth`()

    :returns The current maximum depth for new MessageStreams, 0 is no maximum.

  `Client.``get_duplicate_message_handler`()

    Returns the message handler object set with set_duplicate_message_handler.

  `Client.``get_error_on_publish_gap`()

    > Called to check if the Store will throw PublishStoreGapException.

    :returns If true, PublishStoreGapException can be thrown
      by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.
  `Client.``get_exception_listener`()

    Returns the exception listener callable set on self, or None.

  `Client.``get_logon_correlation_data`()

    Returns the data used to correlate the logon of this Client to the server.

    Returns: | logon correlation data

  `Client.``get_name`()

    Returns the name of the Client object.

    Returns: | name

  `Client.``get_name_hash`()

    Returns the string name hash of the Client object.

    Returns: | name hash string

  `Client.``get_name_hash_value`()

    Returns the numeric name hash of the Client object.

    Returns: | name hash int

  `Client.``get_retry_on_disconnect`()

    Returns True if automatic retry of a command to AMPS after a reconnect is enabled.

  `Client.``get_server_version`()

    Returns the connected server’s version as a numeric value.

    Returns: | The version converted to a number: server version 3.8.1.7 would be 3080107

  `Client.``get_server_version_info`()

    Returns the connected server’s version as a VersionInfo.

    Returns: | The version in a VersionInfo

  `Client.``get_unpersisted_count`()

    Returns the count of unpersisted publishes.

    Returns: | count of unpersisted publishes.

  `Client.``get_uri`()

    Returns the `URI` string passed into the `Client` during the `connect()` invocation.

    Returns: | uri

  `Client.``logon`(timeout=0, authenticator=AMPS.DefaultAuthenticator, options='')

    Logs into AMPS with the parameters provided in the `connect()` method.

    Parameters: | timeout (int) – The maximum time to wait for the command to receive a processed ack from AMPS for the logon command (in milliseconds). `0`` indicates to wait indefinitely. authenticator (Authenticator) – An Authenticator object used to negotiate logon. options (string) – An options string to pass to the server such as ack_conflation=10ms execute (milliseconds). `0` indicates to wait indefinitely.
    Returns: | The command identifier.
    Raises: | `ConnectionException`

  `Client.``name`()

    Returns the name of the Client object.

    Returns: | name

  `Client.``publish`(topic, data, expiration=None)

    Publish a mesage to an AMPS topic. This method does not wait for a response from the AMPS server. To detect failure, install a failed write handler. If the client was created with a persistent store on construction, then the client will store before forwarding the message to AMPS. If a DisconnectException occurs, the message is still stored in the publish store.

    Parameters: | topic (str) – The topic to publish to. data (str) – The data to publish. expiration (int) – Number of seconds until published message should expire.
    Returns: | The sequence number assigned to this message by the publish store or 0 if there is no publish store and the server is assigning sequence numbers.
    Raises: | `DisconnectedException` The client is not connected; the program needs to call connect()

  `Client.``publish_flush`(timeout = 0, ack_type = Message.AckType.ProcessedEnum)

    > Ensures that pending AMPS messages are sent and have been processed by the AMPS server. When the client has a publish store configured, waits until all messages that are in the store at the time the command is called have been acknowledged by AMPS. Otherwise, issues a `flush` command and waits for the server to acknowledge that command. This method blocks until messages have been processed or until the timeout expires, and is most useful when the application reaches a point at which it is acceptable to block to ensure that messages are delivered to the AMPS server. For example, an application might call publish_flush before exiting. One thing to note is that if AMPS is unavailable (HA Client), publish_flush needs to wait for a connection to come back up which may look like it’s hanging.

    Parameters: | timeout (int) – The maximum time to wait for the messages to be acknowledged as persisted, or for the flush command to be acknowledged by AMPS (in milliseconds), or 0 to wait indefinitely. ack_type (int) – Whether the command should wait for a Processed or a Persisted ack when sending the flush command.

  `Client.``remove_connection_state_listener`(listener_callable)

    Removes a listener function previously supplied to add_connection_state_listener.

  `Client.``remove_message_handler`(command_id)

    > Remove a message handler from the `Client.`

    Parameters: | command_id (str) – The command_id for the handler to remove.

  `Client.``send`(message, message_handler=None, timeout=None)

    > Send a `Message` to AMPS via the `Transport` used in
    >   the `Client`.

    Parameters: | message (`Message`) – The message to send. message_handler (`MessageHandler`) – The message handler that will receive messages for this command. timeout (int) – The maximum time to wait for the client to receive and consume a processed ack for this command (in milliseconds). `0` indicates to wait indefinitely.
    Returns: | The command identifier assigned to this command, or None if one is not assigned.

  `Client.``setDisconnectHandler`(client_disconnect_handler)
    A legacy method name for `set_disconnect_handler()`

      Deprecated since version 3.2.0.0: Use `set_disconnect_handler()` instead.

  `Client.``setExceptionListener`(exception_listener)
    A legacy method name for `set_exception_listener()`.

      Deprecated since version 3.2.0.0: Use `set_exception_listener()` instead.

  `Client.``setName`(name)
    A legacy method name for `set_name()`.

      Deprecated since version 3.2.0.0: Use `set_name()` instead.

  `Client.``setOnDisconnectHandler`(client_disconnect_handler)
    A legacy method name for `set_disconnect_handler()`

      Deprecated since version 3.2.0.0: Use `set_disconnect_handler()` instead.

  `Client.``setUnhandledMessageHandler`(message_handler)
    A legacy method name for `set_last_chance_message_handler()`.

      Deprecated since version 3.2.0.0: Use `set_last_chance_message_handler()` instead.

  `Client.``set_ack_batch_size`(batch_size)

    Sets the batch size used for batching message queue ACK messages.

    :param batch_size The number of ACK messages to batch before sending.

  `Client.``set_ack_timeout`(timeout)

    Sets the time before queued ack messages are sent.

    :param timeout The maximum amount of time to wait after adding the first message to an acknowledgement batch before sending the batch, in milliseconds. 0 indicates that the client will wait until the batch is full. A value of 0 is not recommended unless the batch size is set to 1.

  `Client.``set_auto_ack`(enabled)

    Enables or disables auto-acknowledgement of message queue messages.

    :param enabled True to enable auto-acknowledgement of message queue messages.

  `Client.``set_bookmark_store`(bookmarkStore)

    Sets a bookmark store on self.

    Parameters: | bookmarkStore – an `MMapBookmarkStore` or `MemoryBookmarkStore` instance, or a custom object that implements the required bookmark store methods.

  `Client.``set_default_max_depth`(depth)

    > Sets a default maximum depth for all new MessageStream objects
    >   that are returned from synchronous API calls such as execute().

    :param depth The new depth to use. A depth of 0 means no max and is the default. :type depth: int.

  `Client.``set_disconnect_handler`(client_disconnect_handler)

    > Sets the `DisconnectHandler` used by the `Client`. In
    >   the event that the Client is unintentionally disconnected from AMPS, the invoke method from the `ClientDisconnectHandler` will be invoked.

    Parameters: | client_disconnect_handler (`DisconnectHandler`) – The disconnect handler.

  `Client.``set_duplicate_message_handler`(message_handler)

    > Sets the `MessageHandler` instance used for messages that arrive from AMPS
    >   that are deemed to be duplicates of previous messages, according to the local bookmark store.

    Parameters: | message_handler (`MessageHandler`) – The message handler to invoke for duplicates messages.

  `Client.``set_error_on_publish_gap`(error_on_publish_gap)

    > Called to enable or disable throwing PublishStoreGapException.

    Parameters: | error_on_publish_gap (Boolean) – If true, PublishStoreGapException can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

  `Client.``set_exception_listener`(exception_listener)

    > Sets the exception listener instance used for communicating
    >   absorbed exceptions.

    Parameters: | exception_listener (`Exception`) – The exception listener instance to invoke for exceptions.

  `Client.``set_failed_write_handler`(failedWriteHandler)

    Sets a failed write handler on self.

    Parameters: | failedWriteHandler – a callable object to be invoked when AMPS indicates that a published message is not written. This could be because a duplicate message already exists in the transaction log, this client is not entitled to publish to the topic, the message failed to parse, or other similar reasons. Parameters to this callable are an AMPS message when the client has a message saved in the publish store, and a string that contains the reason the publish failed.

    For example, you might implement a function like:

        def PrintFailedWrites(message, reason):
            output = "Uh-oh, something went wrong writing to AMPS. (%s) " % reason
            if (message != None):
                  output += "Topic: %s, Data snippet: %s..." % \
                          (message.get_topic(), message.get_data()[0:20])
            print output

  `Client.``set_global_command_type_message_handler`(command, message_handler)

    > Add a message handler to the `Client` to handle messages from the server with the specified command.

    Parameters: | command (str) – The command to send to the handler. Valid values are ‘ack’ and ‘heartbeat’. message_handler (`MessageHandler`) – The message handler that will receive messages of the command specified.

  `Client.``set_heartbeat`(interval_seconds, timeout_seconds=None)
    Used to enable heartbeating between the client and the AMPS Server. When a

      > `Client` sends a heartbeat message to an AMPS instance, the AMPS instance will send back an acknowledgment message. From this point forward the `Client` and AMPS instance will each monitor that the other is still active. AMPS sends heartbeat messages to the client at the specified interval. If the `Client` does not receive a heartbeat message within the time interval specified in :timeout_seconds, then the Client will assume that the connection has ended, close the connection and invoke the `DisconnectHandler`. Likewise, if the server sends a heartbeat and does not receive a response within the timeout, the server will consider the client to be nonresponsive and close the connection.

      Heartbeats are processed in the client receive thread. If you use asynchronous message processing, your message handler must process messages within the timeout interval, or risk being disconnected by the server.

    Parameters: | interval_seconds (int) – The time between heartbeat messages being sent to AMPS. timeout – The maximum time to wait for AMPS to acknowledge the start of heartbeating (in seconds)

  `Client.``set_last_chance_message_handler`(message_handler)

    > Sets the `MessageHandler` instance called when no other incoming message handler matches.

    Parameters: | message_handler (`MessageHandler`) – The message handler to invoke when no other incoming message handler matches.

  `Client.``set_logon_correlation_data`()

    Sets the data used to correlate the logon of this Client in the server.

    Parameters: | logonCorrelationData – The base64 data string to send with the logon.

  `Client.``set_name`(name)

    A legacy method name for `set_name()`.

  `Client.``set_publish_store`(publishStore)

    Sets a publish store on self.

    Parameters: | publishStore – an `PublishStore` or `MemoryPublishStore` instance.

  `Client.``set_retry_on_disconnect`(enabled)

    > Enables or disables automatic retry of a command to AMPS after a
    >   reconnect. This behavior is enabled by default. NOTE: Clients using a publish store will have all publish messages sent, regardless of this setting. Also, Clients with a subscription manager, including all HAClients, will have all subscribe calls placed.

    :param enabled False to disable automatic retry of commands to AMPS. :type enabled: Boolean.

  `Client.``set_thread_created_callback`(thread_created_callable)

    Sets a function to be called when this client creates a thread used to receive data from the server.

    Parameters: | thread_created_callable (A python function or other callable that takes no parameters.) – The function or callable to be called. This function is called by the newly created thread.

  `Client.``set_transport_filter`(transport_filter_callable)

    Sets a function to be called when this client sends or receives data.

  `Client.``set_unhandled_message_handler`(message_handler)
    A legacy method name for `set_last_chance_message_handler()`.

      Deprecated since version 4.0.0.0: Use `set_last_chance_message_handler()` instead.

  `Client.``sow`(on_message, topic, filter=None, batch_size=10, timeout=0, top_n=None, order_by=None, bookmark=None, options=None)

    Executes a SOW query. There are two ways to use this method. First, you can provide a topic, filter, and options for the subscription. In this case, the method returns a message stream that you can iterate over. For example:

        c = Client("test_client")

        try:
            c.connect("tcp://127.0.0.1:9004/fix")
            cid = c.logon(timeout=0)
            for aMessage in c.sow("MySowTopic"):
                print aMessage.get_data()
        finally:
            c.close()

    Second, you can provide a message handler. In this case, the method creates a background thread and calls the message handler with each message received from AMPS, including the group_begin and group_end messages that indicate the beginning and end of the SOW query.

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with matching messages. If this parameter is not present, AMPS creates a :class: MessageStream and returns that message stream from the call to sow. topic (str) – The topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batching parameter to use for the results. timeout (int) – The maximum time to wait for the client to receive and consume a processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the sow. order_by (str) – To have the records ordered by the server. bookmark (int) – The bookmark for historical query of the sow. options (str) – A comma separated list of values indicating additional processing options.
    Returns: | If a message handler is provided, returns the command identifier assigned to this command. If no message handler is present, returns a MessageStream containing the results of the command.
    Raises: | `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``sowAndDeltaSubscribe`(on_message, topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, options=0, timeout=0, top_n=None)
    A legacy method name for `sow_and_delta_subscribe()`.

      Deprecated since version 3.2.0.0: Use `sow_and_delta_subscribe()` instead.

  `Client.``sowAndSubscribe`(on_message, topic, filter, batch_size=1, oof_enabled=False, options=0, timeout=0, top_n=None)
    A legacy method name for `sow_and_subscribe()`.

      Deprecated since version 3.2.0.0: Use `sow_and_subscribe()` instead.

  `Client.``sowDelete`(on_message, topic, filter=None, options=0, timeout=0)
    A legacy method name for `sow_delete()`.

      Deprecated since version 3.2.0.0: Use `sow_delete()` instead.

  `Client.``sow_and_delta_subscribe`(on_message, topic, filter=None, batch_size=1, oof_enabled=False, send_empties=False, options=0, timeout=0, top_n=None)

    Executes a SOW query and places a delta subscription.

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with matching messages. topic (str) – The Topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batch sizing parameter to use for the results. oof_enabled (boolean) – Specifies whether or not Out-of-Focus processing is enabled. send_empties (boolean) – Specifies whether or not unchanged records are received on the delta subscription. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the sow. order_by (str) – To have the records ordered by the server. options (str) – A comma separated list of values indicating additional processing options.
    Returns: | The command identifier assigned to this command.
    Raises: | `SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``sow_and_subscribe`(on_message, topic, filter, batch_size=1, oof_enabled=False, timeout=0, top_n=None, order_by=, bookmark=, options=)

    Executes a SOW query and places a subscription.

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with matching messages. topic (str) – The topic to execute the SOW query against. filter (str) – The filter. batch_size (int) – The batching parameter to use for the results. oof_enabled (boolean) – Specifies whether or not Out-of-Focus processing is enabled. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. top_n (int) – The maximum number of records to return from the sow. order_by (str) – To have the records ordered by the server. bookmark (str) – The bookmark for historical query of the sow. options (str) – A comma separated list of values indicating additional processing options.
    Returns: | The command identifier assigned to this command.
    Raises: | `SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``sow_delete`(on_message, topic, filter=None, options=0, timeout=0)

    Executes a SOW delete with a filter.

    There are two ways to use this method. When no message handler is provided, the method returns a `Message` that will receive the results of the delete command.

    When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.

    For example, to delete all messages that match a filter:

        ...
        ackMessage = client.sow_delete("sow_topic","/status = 'obsolete'")
        print "%s: %s" % (ackMessage.get_ack_type(), ackMessage.get_status())
        ...

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with stats and completed acknowledgments topic (str) – The topic to execute the SOW delete against. filter (str) – The filter. To delete all records, set a filter that is always true (‘1=1’) options (str) – A comma separated list of values indicating additional processing options. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely.
    Returns: | The command identifier assigned to this command.
    Raises: | `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``sow_delete_by_data`(on_message, topic, data, timeout=0)

    Delete a message from a SOW, using data supplied to locate a SOW entry with matching keys.

    There are two ways to use this method. When no message handler is provided, the method returns a `Message` that will receive the results of the delete command.

    When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.

    For example, to efficiently delete a message that your program has received from AMPS:

        ...
        topic= aMessage.get_topic()
        data = aMessage.get_data()
        ackMessage = client.sow_delete_by_data(topic,data)
        print "%s: %s" % (ackMessage.get_ack_type(), ackMessage.get_status())
        ...

    In addition to deleting a message from AMPS, this method allows deletion of a message whose keys match one that is already stored, for example:

        ...
        data = orders[orderId]
        ackMessage = client.sow_delete_by_data('orders', data)
        del orders[orderId]
        ...

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with stats and completed acknowledgments topic (str) – The topic to execute the SOW delete against. data (str) – A message whose keys match the message to be deleted in the server’s SOW. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely.
    Returns: | The command identifier assigned to this command.

  `Client.``sow_delete_by_keys`(on_message, topic, keys, timeout=0)

    Executes a SOW delete with sow keys.

    There are two ways to use this method. When no message handler is provided, the method returns a `Message` that will receive the results of the delete command.

    When a message handler is provided, this method submits the SOW delete on a background thread and calls the message handler with the results of the delete.

    Parameters: | on_message (`MessageHandler`) – The message handler to invoke with stats and completed acknowledgments topic (str) – The topic to execute the SOW delete against. keys (str) – A comma separated list of SOW keys to be deleted timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in millseconds). `0` indicates to wait indefinitely.
    Returns: | The command identifier assigned to this command.

  `Client.``start_timer`()

    Deprecated in version 5.3.2.0. Used to start a timer on an AMPS Server for the client.

  `Client.``stop_timer`(handler)

    Deprecated in version 5.3.2.0. Used to stop a timer on an AMPS Server previously started for the client. :param handler: The handler to be invoked with the timer response.

  `Client.``subscribe`(on_message, topic, filter=None, options=None, timeout=0, sub_id=None)

    Places a subscription with AMPS.

    Parameters: | on_message (str) – The message handler to invoke with matching messages. topic (str) – The topic to subscribe to. filter (str) – The filter. options (str) – A comma separated list of values indicating additional processing options. timeout (int) – The maximum time to wait for the client to receive and consume the processed ack for this command (in milliseconds). `0` indicates to wait indefinitely. sub_id (str) – The subscription ID. You may optionally provide a subscription ID to ease recovery scenarios, instead of having the system automatically generate one for you. When used with the ‘replace’ option, this is the subscription to be replaced.
    Returns: | The command identifier assigned to this command.
    Raises: | `SubscriptionAlreadyExistsException`, `BadFilterException`, `BadRegexTopicException`, `TimedOutException`, `DisconnectedException`

  `Client.``unsubscribe`(sub_id=None)

    > Remove a subscription from AMPS.

    Parameters: | sub_id – The subscription id to remove.

exception `AMPS.``ClientNameInUse`

  Bases: `AMPS.ConnectionException`

  deprecated - use `NameInUseException`

class `AMPS.``Command`

  Bases: `object`

  AMPS.Command represents a single message (or command) sent to the AMPS server. The class provides methods for headers that are used for commands to the server. Applications typically use this class to create outgoing requests to AMPS. The responses to requests, whether acknowledgements or messages that contain data, are returned as instances of the `AMPS.Message` class.

  The `AMPS.Client` provides named convenience methods that support a subset of the options available via a Command. For most applications, the recommended approach is to use the `publish()` methods for sending data to AMPS (unless the application needs to set options not available through that method) and use the Command class for queries, subscriptions, and to remove data.

  To use the Command class to run a command on the server, you create the Command, set options as described in the Command Cookbook in the Python Developer Guide or the AMPS Command Reference, and then use `AMPS.Client.execute_async()` to process messages asynchronously, or `AMPS.Client.execute()` to process messages synchronously.

  `add_ack_type`()

    Adds an ack type to this command, in addition to any other ack types that have been previously set or that will be set by the Client.

    Parameters: | value – The ack type to add
    Returns: | this command

  `get_ack_type`()

    Gets the ack type enum for this command

    Returns: | the ack type as a string

  `get_ack_type_enum`()

    Gets the ack type enum for this command

    Returns: | the ack type as an enum

  `get_sequence`()

    Gets the sequence of self for publish, delta_publish, or sow_delete commands. This can be checked after calling execute or executeAsync to query the sequence number that was used, if any.

  `reset`()

    > Resets this command with a new Command type and re-initializes all other fields.

    Param: | A string indicating the AMPS command.

  `set_ack_type`()

    Sets the ack type for this command, replacing any other ack types that have been previously set or that will be set by the Client.

    Parameters: | value – The ack type to set
    Returns: | this command

  `set_ack_type_enum`()

    Sets the ack type enum for this command, replacing any other ack types that have been previously set or that will be set by the Client.

    Parameters: | value – The ack type to set
    Returns: | this command

  `set_batch_size`()

    Sets the batch size header, which is used to control the number of records that AMPS will send in each batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_bookmark`()

    Sets the value of the bookmark header. For a subscription, this identifies the point in the transaction log at which to begin the replay. For a sow delete (queue acknowledgement), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_command_id`()

    Sets the value of the command id header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

    If not set, the AMPS Client will automatically fill in a command id when the client needs one to be present (for example, when the client needs a `processed` acknowledgement to be able to tell if a `subscribe` command succeeded or failed).

    Parameters: | value – the new value for this header
    Returns: | this command

  `set_correlation_id`()

    Sets the value of the correlation ID header. The AMPS server does not process or interpret this value; however, the value must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Command.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_data`()

    Sets the data for this command. This is used for `publish` commands and for `sow_delete` commands.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_expiration`()

    Sets the expiration of self. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_filter`()

    Sets the value of the filter header.

    > Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    > param value: | The new value to set for the header
    > returns: | this command

  `set_options`()

    Sets the value of the options header. The options available, and how AMPS interprets the options, depend on the command being sent. The `AMPS.Message.Options` class contains constants and helper methods for building an options string. See the AMPS Command Reference for details on the options available for a given command.

    Parameters: | value – The value to set
    Returns: | this command

  `set_order_by`()

    Sets the value of the order by header. This header is only used for SOW query results, and must contain one or more XPath identifiers and an optional `ASC` or `DESC` order specifier (for example, `/orderTimestamp DESC`).

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_query_id`()

    Sets the query id of self.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_sequence`()

    Sets the sequence of self for publish, delta_publish, or sow_delete commands. A publish store on the client may replace this value.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_sow_key`()

    Sets the SOW key for this command. This is useful for `publish` commands.

    For a `publish` command, sets the SOW key for a message when the SOW is configured so that the publisher is responsible for determining and providing the SOW key. This option is ignored on a `publish` when the topic is configured with a `Key` field in the SOW file.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_sow_keys`()

    The sow keys for a command are a comma-separated list of the keys that AMPS assigns to SOW messages. The SOW key for a message is available through the `Message.get_sow_key()` method on a message.

    For a `sow_delete` command, this list indicates the set of messages to be deleted.

    For a query or subscription, this list indicates the set of messages to include in the query or subscription.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_sub_id`()

    Sets the subscription id of self.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_timeout`()

    Sets the amount of time that the Client will wait for a `processed` acknowledgement from the server to be received and consumed before abandoning the request; this option is only used by the Client and is not sent to the server. The acknowledgement is processed on the client receive thread, This option is expressed in milliseconds, where a value of `0` means to wait indefinitely.

    Parameters: | value – the value to set
    Returns: | this command

  `set_top_n`()

    Sets the top N header of this command. Although AMPS accepts a top N value in the header of a command, most AMPS applications pass the value in the `top_n` option for clarity.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

  `set_topic`()

    Sets the value of the topic header, which specifies the topic that the command applies to. For a `publish` command, this field is interpreted as the literal topic to publish to. For commands such as `sow` or `subscribe`, the topic is interpreted as a literal topic unless there are regular expression characters present in the topic name. For those commands, if regular expression characters are present, the command will be interpreted as applying to all topics with names that match the regular expression.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value to set for the header
    Returns: | this command

exception `AMPS.``CommandError`

  Bases: `AMPS.AMPSException`

  deprecated - use `CommandException`

exception `AMPS.``CommandException`

  Bases: `AMPS.CommandError`

  The CommandException is raised when a Command is used in an improper or unrecognized manner.

exception `AMPS.``CommandTimedOut`

  Bases: `AMPS.CommandException`

  deprecated - legacy exception

exception `AMPS.``CommandTypeError`

  Bases: `AMPS.CommandException`

  deprecated - use `CommandException`

class `AMPS.``CompositeMessageBuilder`

  Bases: `object`

  AMPS CompositeMessageBuilder Object

  `append`(value)

    Appends a message part to this object.

  `clear`()

    Clears this object. Does not resize or free internal buffer.

  `get_data`()

    Returns the composite message’s data.

class `AMPS.``CompositeMessageParser`

  Bases: `object`

  AMPS CompositeMessageParser Object

  `get_part`(index)

    Returns the index’th composite message part, or None if index is invalid.

  `get_part_raw`(index)

    Returns the index’th composite message part as a python bytes object, or None if index is invalid.

  `parse`(str_or_Message)

    Parse a composite message body or composite AMPS.Message. Returns the number of valid parts parsed.

  `size`()

    Returns the number of message parts last parsed.

class `AMPS.``ConflatingRecoveryPointAdapter`

  Bases: `object`

  This class can be used as an adapter on an AMPS.MemoryBookmarkStore. It is a pass-through to another adapter type that provides conflation of updates to help reduce the load on the underlying adapter. Conflation can be on an interval, a set number of updates or both.

  `close`(subid, bookmark)

    Close the delegate.

  `next`()
    Returns the next RecoveryPoint from the delegate or an empty one if
      recovery has completed.
  `prune`()

    Tell the delegate to prune.

  `purge`(sub_id)

    If sub_id is provided, remove all records related to sub_id. If no sub_id is provided, remove all records for this client. :param sub_id: The optional sub_id to remove or all if none

  `update`(recoveryPoint)

    Conflate the new information in recoveryPoint. :param recovery_point: The new recovery information to save. :type recovery_point: :ampspy:recoveryPoint

exception `AMPS.``ConnectionError`

  Bases: `AMPS.AMPSException`

  deprecated - use `ConnectionException`

exception `AMPS.``ConnectionException`

  Bases: `AMPS.ConnectionError`

  The ConnectionException is raised when the client is unable to connect to AMPS.

exception `AMPS.``ConnectionRefused`

  Bases: `AMPS.ConnectionException`

  deprecated - use `ConnectionRefusedException`

exception `AMPS.``ConnectionRefusedException`

  Bases: `AMPS.ConnectionRefused`

  The ConnectionRefusedException is raised when the connection to AMPS is refused due to a socket error.

exception `AMPS.``CorruptedRecord`

  Bases: `AMPS.LocalStorageError`

  deprecated - legacy exception

class `AMPS.``DefaultAuthenticator`

  Bases: `object`

  AMPS Authenticator Object

  `authenticate`(username, password)

    Authenticates self to an external system.

    Parameters: | username (str) – The current username supplied in a URI. password (str) – The current password supplied in a URI.
    Returns: | The new password to be sent to the server in the logon request.

  `completed`(username, password, reason)

    Called when authentication is completed, with the username and password returned by the server in the final acknowledgement for the logon sequence.

    Parameters: | username (str) – The username returned by the server password (str) – The password or authentication token returned by the server in the last logon request. reason (str) – The reason the server provided for finishing the logon sequence. (For example, the logon might have succeeded, authentication might be disabled, and so on.)

  `retry`(username, password)

    Called when the server indicates a retry is necessary to complete authentication.

    Parameters: | username (str) – The username supplied to the server. password (str) – The password or authentication token returned by the server in the last logon request.
    Returns: | The new password or authentication token to be sent to the server.

class `AMPS.``DefaultServerChooser`

  Bases: `object`

  A simple ServerChooser that keeps a list of AMPS instances and Authenticators, and advances to the next one when failure occurs.

  To use the DefaultServerChooser, you add the URIs for the server to choose from, then set the server for the HAClient as shown below:

      client = AMPS.HAClient("showchooser")
      chooser = AMPS.DefaultServerChooser()
      chooser.add("tcp://server:9005/nvfix")
      chooser.add("tcp://server-two:9005/nvfix")
      client.set_server_chooser(chooser)
      client.connect_and_logon()

  You can add any number of URIs to the DefaultServerChooser.

  `add`(uri)

    Adds a URI to this server chooser.

    Parameters: | uri (str) – The URI of an AMPS instance that may be chosen.

  `add_all`(uris)

    Adds a list of URIs to this server chooser.

    Parameters: | uris – The list of URIs of AMPS instances that may be chosen.

  `get_current_authenticator`()

    Called by `HAClient` to retrieve an `Authenticator` to use for authentication with the current server.

    Returns: | The current `Authenticator`.

  `get_current_uri`()

    Called by the `HAClient` to retrieve the current URI to connect to.

    Returns: | A URI to connect to, or None if no server should be connected to.

  `get_error`()

    Provides additional detail to be included in an exception thrown by when the AMPS instance(s) are not available. Called by the `HAClient` when creating an exception.

    Returns: | A string with information about the connection that failed and the reason for the failure. When no further information is available, returns an empty string.

  `next`()

    Invoked to advance to the next server.

  `report_failure`(exception, connectionInfo)

    Invoked by `HAClient` to indicate a connection failure occurred.

    Parameters: | exception (`Exception`) – An exception object containing an error message. connectionInfo (dict(str, str)) – A dictionary of properties associated with the failed connection.

  `report_success`(connectionInfo)

    Invoked by `HAClient` to indicate a connection attempt was successful.

    Parameters: | connectionInfo (dict(str, str)) – A dictionary of properties associated with the successful connection.

exception `AMPS.``Disconnected`

  Bases: `AMPS.ConnectionException`

  deprecated - use `DisconnectedException`

exception `AMPS.``DisconnectedException`

  Bases: `AMPS.Disconnected`

  The DisconnectedException is raised when an operation is requested by the client, but either a connection has yet to be established or the client was disconnected.

exception `AMPS.``DuplicateLogonException`

  Bases: `AMPS.CommandException`

  The DuplicateLogonException is raised when a client is trying to logon after already logging on.

class `AMPS.``ExponentialDelayStrategy`

  Bases: `object`

  ExponentialDelayStrategy is an implementation that exponentially backs off when reconnecting to the same server, with a maximum time to retry before it gives up entirely.

  By default, an ExponentialDelayStrategy has an initial delay of 200 ms, a maximum delay of 20 seconds, a backoff exponent of 2.0, and has no limit to the amount of time to retry the connection.

  Constructor parameters:

  Parameters: | initial_delay – The time (in milliseconds) to wait before reconnecting to a server for the first time after a failed connection. maximum_delay – The maximum time to wait for any reconnect attempt (milliseconds). Exponential backoff will not exceed this maximum. backoff_exponent – The exponent to use for calculating the next delay time. For example, if the initial time is 200ms and the exponent is 2.0, the next delay will be 400ms, then 800ms, etc. maximum_retry_time – The maximum time (milliseconds) to allow reconnect attempts to continue without a successful connection, before “giving up” and abandoning the connection attempt. jitter – The amount of ‘jitter’ to apply when calculating a delay time, measured in multiples of the initial delay. Jitter is used to reduce the number of simultaneous reconnects that may be issued from multiple clients.

  `get_connect_wait_duration`()

    Returns the time that the client should delay before connecting to the given server URI.

  `reset`()

    Reset the state of this reconnect delay. AMPS calls this method when a connection is established.

class `AMPS.``FIXBuilder`

  Bases: `object`

  AMPS FIXBuilder Object

  `append`(tag, value, (optional)offset, (optional)length)

    Appends tag=value to self. :param tag: The numeric tag to use. :type tag: int :param value: The value for the given tag. :type value: str :param offset: Optional. The offset into value at which the value actually starts. :type offset: int :param length: Optional. The length of the actual value within value. Only valid and required if offset is also provided :type tag: int

  `get_string`()

    Called to get the string FIX message.

    Returns: | The FIX message as a string.

  `reset`()

    Called to clear the state of the FIXBuilder to create a new FIX message

class `AMPS.``FIXShredder`

  Bases: `object`

  Convenience class for easily processing FIX strings. Constructor arguments:

  Parameters: | separator – The delimiter to expect between FIX fields. Defaults to chr(1) if no delimiter is provided.

  `to_map`(message)

    Parse the provided FIX message and return a map that contains the fields in the message.

    Parameters: | message – The FIX message to parse.

class `AMPS.``FixedDelayStrategy`

  Bases: `object`

  FixedDelayStrategy is a reconnect delay strategy implementation that waits a fixed amount of time before retrying a connection.

  By default, a FixedDelayStrategy waits for 200ms between connection attempts and does not have a maximum timeout.

  Constructor parameters:

  Parameters: | initial_delay – The time (in milliseconds) to wait before reconnecting to a server for the first time after a failed connection. maximum – The maximum time (in milliseconds) to keep retrying before giving up.

  `get_connect_wait_duration`()

    Returns the time that the client should delay before connecting to the given server URI.

  `reset`()

    Reset the state of this reconnect delay. AMPS calls this method when a connection is established.

class `AMPS.``HAClient`

  Bases: `AMPS.Client`

  AMPS HAClient Object used for highly-available client connections. Derives from `Client`. Constructor arguments:

  Parameters: | name – the unique name for this client. AMPS does not enforce specific restrictions on the character set used, however some protocols (for example, XML) may not allow specific characters. 60East recommends that the client name be meaningful, short, human readable, and avoid using control characters, newline characters, or square brackets. publish_store – an optional file name for the client’s local publish store. If not supplied a memory-backed publish store is used. bookmark_store – an optional file name for the client’s local bookmark store. If not supplied a memory-backed bookmark store is used. no_store – pass no_store=True to indicate that a memory bookmark and/or publish store should not be used.

  `connect`()

    Connects and logs on using the ServerChooser you’ve supplied via `set_server_chooser()`. Will continue attempting to connect and logon to each URI returned by the ServerChooser until the connection succeeds or the ServerChooser returns an empty URI.

  `connect_and_logon`()

    Connects and logs on using the ServerChooser you’ve supplied via `set_server_chooser()`. Will continue attempting to connect and logon to each URI returned by the ServerChooser until the connection succeeds or the ServerChooser returns an empty URI.

  `discard`(message)

    Discards a message from the local bookmark store.

    Parameters: | message (AMPS.Message) – an AMPS.Message instance that was received from a bookmark subscription.

  `get_default_resubscription_timeout`()

    Gets the default timeout in milliseconds used when attempting to resubscribe each subscription after a re-connect.

  `get_logon_options`()

    Gets self’s logon options string and returns it.

  `get_most_recent`(sub_id)

    Gets the most recent bookmark from the local bookmark store for the given subscription id.

    Parameters: | sub_id (string) – The subscription id for which to retrieve the most recent bookmark.

  `get_reconnect_delay_strategy`()

    Returns the reconnect delay strategy object used to control delay behavior when connecting and reconnecting to servers.

    Returns: | The reconnect delay strategy object.

  `get_resubscription_timeout`()

    Gets the timeout in milliseconds used when attempting to resubscribe each subscription after a re-connect.

  `get_server_chooser`()

    Gets selfs server chooser and returns it.

  `logon`()

    Not used in the HAClient; call `connect_and_logon()` to connect and log on to AMPS once a server chooser is set.

  `prune_store`(tmp_file_name)

    Prunes the local bookmark store. If it’s file-based, it will remove unnecessary entries from the file.

    Parameters: | tmp_file_name (string) – Optional file name to use for temporary storage during prune operation.

  `set_default_resubscription_timeout`(timeout)

    Sets the default timeout in milliseconds used when attempting to resubscribe each subscription after a re-connect. Default value is 0 (no timeout). :param timeout: The number of milliseconds to wait for a server response. 0 indicates no timeout.

  `set_failed_resubscribe_handler`(handler)

    Sets the handler that is called if a resubscribe after failover fails to complete successfully. The subscribe Message, requested acktypes, and exception are passed to the handler. The handler should return False to force a new attempt at connect_and_logon or True to ignore the failure and remove the subscription from the subscription manager. :param handler: The callable handler to invoke.

  `set_logon_options`(options)

    Sets a logon options on self.

    Parameters: | options (string) – an options string to be passed to the server during logon, such as ack_conflation=100us.

  `set_reconnect_delay`(reconnectDelay)

    Sets the delay in milliseconds used when reconnecting, after a disconnect occurs. Calling this method creates and installs a new FixedDelayStrategy in this client. Default value is 200 (0.2 seconds). :param reconnectDelay: The number of milliseconds to wait before reconnecting, after a disconnect occurs.

  `set_reconnect_delay_strategy`(reconnectDelayStrategy)

    Sets the reconnect delay strategy object used to control delay behavior when connecting and reconnecting to servers.

    Parameters: | strategy – The reconnect delay strategy object to use when connecting and reconnecting to AMPS instances. The object must have the following two methods defined: get_connect_wait_duration(uri): uri A string containing the next URI AMPS will connect with. returns An integer representing the time in milliseconds to wait before connecting to that URI. reset(): resets the state of self after a successful connection.

  `set_resubscription_timeout`(timeout)

    Sets the timeout in milliseconds used when attempting to resubscribe each subscription after a re-connect. Default value is 0 (no timeout) but can be changed using set_default_resubscription_timeout. :param timeout: The number of milliseconds to wait for a server response. 0 indicates no timeout.

  `set_server_chooser`(serverChooser)

    Sets a server chooser on self.

    Parameters: | serverChooser (ServerChooser) – a ServerChooser instance, such as a `DefaultServerChooser`.

  `set_timeout`(timeout)

    Sets the timeout in milliseconds used when sending a logon command to the server. Default value is 10000 (10 seconds). :param timeout: The number of milliseconds to wait for a server response to logon. 0 indicates no timeout.

class `AMPS.``HybridPublishStore`

  Bases: `object`

  A publish store that keeps messages on disk as well as in memory. When used with an HAClient, the HAClient manages storing messages in the publish store, replaying messages to the server after failover, and removing messages from the store. With this publish store, an application can recover messages from disk after exiting and restarting.

  `get_unpersisted_count`()

    Returns the number of messages published which have not been ACK’ed by the server.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

exception `AMPS.``InvalidBookmarkException`

  Bases: `AMPS.CommandException`

  The InvalidBookmarkException is raised when a client uses an invalid bookmark.

exception `AMPS.``InvalidMessageTypeOptions`

  Bases: `AMPS.MessageTypeException`

  deprecated - use `MessageTypeException`

exception `AMPS.``InvalidOptionsException`

  Bases: `AMPS.CommandException`

  The InvalidOptionsException is raised when a client uses an invalid options.

exception `AMPS.``InvalidOrderByException`

  Bases: `AMPS.CommandException`

  The InvalidOrderByException is raised when a client uses an invalid orderby clause.

exception `AMPS.``InvalidSubIdException`

  Bases: `AMPS.CommandException`

  The InvalidSubIdException is raised when a client uses an invalid subid.

exception `AMPS.``InvalidTopicError`

  Bases: `AMPS.CommandException`

  deprecated - use `InvalidTopicException`

exception `AMPS.``InvalidTopicException`

  Bases: `AMPS.InvalidTopicError`

  The InvalidTopicException is raised when a query is performed against a topic that does not exist.

exception `AMPS.``InvalidTransportOptions`

  Bases: `AMPS.TransportException`

  deprecated - use `InvalidTransportOptionsException`

exception `AMPS.``InvalidTransportOptionsException`

  Bases: `AMPS.InvalidTransportOptions`

  InvalidTransportOptionsException is raised when a `URI` string contains invalid options for a given transport.

exception `AMPS.``InvalidUriException`

  Bases: `AMPS.InvalidUriFormat`

  InvalidUriException is raised when the format of the `URI` is invalid.

exception `AMPS.``InvalidUriFormat`

  Bases: `AMPS.ConnectionException`

  deprecated - use `InvalidUriException`

exception `AMPS.``LocalStorageError`

  Bases: `AMPS.AMPSException`

  deprecated - legacy exception

exception `AMPS.``LogonRequiredException`

  Bases: `AMPS.CommandException`

  The LogonRequiredException is raised when a client attempts to execute a command before calling logon.

class `AMPS.``MMapBookmarkStore`

  Bases: `object`

  AMPS MMapBookmarkStore Object

  Stores bookmarks in a local file. Construct with the filename to use or recover from. Optional second bool argument to request that the last modified timestamp of the file is included in the initial most recent bookmark. Optional third argument of a RecoveryPointAdapter.

  `discard`(subid, sequence)

    Log a discard-bookmark entry to the persisted log.

  `discard_message`(message)

    Log a message as discarded from the store.

  `get_most_recent`(subid)

    Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

  `get_oldest_bookmark_seq`(subid)

    Called to find the oldest bookmark sequence in the store.

  `is_discarded`(message)

    Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

  `log`(message)

    Log a bookmark to the log and return the corresponding sequence number.

  `persisted`(subid, bookmark)

    Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

  `persisted_index`()

    persisted(subid, bookmark_index)

    Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

  `prune`([temp_file_name])

    Used to trim the size of a store’s storage. Implemented for file based stores to remove items no longer necessary to create the current state.

  `purge`()

    Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `purge_sub_id`()

    Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

  `set_server_version`(version)

    Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class `AMPS.``MemoryBookmarkStore`

  Bases: `object`

  > > A bookmark store that maintains information about the recovery point for bookmark subscriptions in memory.

  > When the bookmark store is set on a Client or HAClient, the AMPS client library manages adding subscriptions to the store and tracking bookmarks as they arrive. The AMPS HAClient uses the bookmark store on failover to recover bookmark subscriptions at the appropriate point.

  > For a bookmark subscription, an application must discard() messages when they have been processed. The other methods on this class are not typically called by the application during normal use.

  A RecoveryPointAdapter may optionally be specified when created to add something such as storage in a SOW using SOWRecoveryPointAdapter to prevent any message loss if the client application dies.

  `discard`(subid, sequence)

    Log a discard-bookmark entry to the persisted log.

  `discard_message`(message)

    Log a message as discarded from the store.

  `get_most_recent`(subid)

    Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

  `get_oldest_bookmark_seq`(subid)

    Called to find the oldest bookmark sequence in the store.

  `is_discarded`(message)

    Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

  `log`(message)

    Log a bookmark to the log and return the corresponding sequence number.

  `persisted`(subid, bookmark)

    Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

  `persisted_index`()

    persisted(subid, bookmark_index)

    Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

  `purge`()

    Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `purge_sub_id`()

    Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

  `set_server_version`(version)

    Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class `AMPS.``MemoryPublishStore`

  Bases: `object`

  A publish store that keeps messages in memory. This class is the default publish store for a python HAClient. The HAClient manages storing messages in the publish store, replaying messages to the server after failover, and removing messages from the store. With this publish store, an application typically checks to be sure that the publish store is empty (that is, all messages have been persisted in the AMPS server) before exiting.

  `get_error_on_publish_gap`()
    Returns If true, PublishStoreGapException can be thrown
      by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.
  `get_unpersisted_count`()

    Returns the number of messages published which have not been ACK’ed by the server.

  `set_error_on_publish_gap`()

    Called to enable or disable throwing PublishStoreGapException.

    Parameters: | error_on_publish_gap (Boolean) – If true, PublishStoreGapException can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

class `AMPS.``Message`

  Bases: `object`

  AMPS.Message represents a single message sent to or received from the AMPS server. The class provides methods for every header that can be present, whether or not that header will be populated or used in a particular context.

  Applications typically use an `AMPS.Command` to create outgoing requests to AMPS, and receive instances of `AMPS.Message` in response.

  The AMPS Command Reference provides details on which headers are used by AMPS and which will be populated on messages received from AMPS, depending on the command the `AMPS.Message` responds to, the optionsand headers set on that command, and the type of the response message.

  `AMPS.Message` has been designed to minimize unnecessary memory allocation. Copying a Message does not copy the underlying content of the message. When the AMPS client provides a Message to a message handler function, the data in that Message is a region in the buffer that the AMPS client uses to read from the socket. If your application will use the Message after the message handler returns, you should use the `__deepcopy__()` function to copy the underlying data as well as the Message, since in this case the AMPS client will reuse the underlying buffer once the MessageHandler returns. See the AMPS Python Developer Guide section on asynchronous message processing for more details.

  If your application has the need to bypass most of the `AMPS.Client` infrastructure for some reason when sending commands to AMPS, the `AMPS.Message` / `AMPS.Client.send()` interface provides the flexibility to do so. In return, your application must provide functionality that is normally provided automatically by the `AMPS.Client` (for example, tracking subscriptions for failover, recording the message in the publish store and managing success or failure of the publish, and so on). Although this functionality is available for flexibility, it is rarely needed in practice. 60East recommends using `AMPS.Command` objects with `AMPS.Client.execute()` and `AMPS.Client.execute_async()` for sending commands to AMPS.

  class `Options`

    Bases: `object`

    AMPS.Message.Options is a class that provides convenience methods for constructing an options string for use in a command to AMPS. This class is intended to help in formatting the options. It does not validate the values provided, that the options apply to any particular command,or that the options have a particular result. The AMPS Python client (and the AMPS server itself) accept options as a string, so there is no requirement to use this class to format options.

        cmd = AMPS.Command("sow_and_subscribe").set_topic("my_cool_topic") \
                  .set_options(str(AMPS.Message.Options().set_OOF().set_conflation("5s") ))

    Note

    Not every option applies to every command. See the AMPS User Guide and AMPS Command Reference for details on what options are available on a given command, and what effect the option has.

    `set_OOF`()

      Adds the `oof` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_cancel`()

      Adds the `cancel` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_conflation`()

      Sets the `conflation` option as a time interval such as `250ms` or `1m`. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the conflation interval to set

    `set_conflation_key`()

      Sets the `conflation_key` for a subscription, as one or more XPath identifiers to use to determine which messages are identical and should be conflated. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the key or keys for the command to conflate on

    `set_fully_durable`()

      Adds the `fully_durable` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_grouping`()

      Sets the `grouping` option, which defines how to group messages from the original topic into result messages in an aggregated subscription or aggregated query. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the grouping definition for the command

    `set_live`()

      Adds the `live` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_max_backlog`()

      Sets the `max_backlog` option, the maximum number of unacknowledged queue messages that a subscription is willing to accept at a given time. (The actual number of messages allowed will be either this setting, or the per subscription maximum set for the queue, whichever is smaller). See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the maximum backlog for the subscription

    `set_no_empties`()

      Adds the `no_empties` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_no_sowkey`()

      Adds the `no_sowkey` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_none`()

      Clears options set on self.

    `set_pause`()

      Adds the `pause` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_projection`()

      Sets the `projection` option, which defines the fields produced by an aggregated subscription or aggregated query. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the projection definition for the command

    `set_rate`()

      Sets the `rate` option, which optionally controls the maximum rate at which a transaction log replay will produce messages. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the rate value as a message number, number of data bytes, or multiplier of the original message rate

    `set_rate_max_gap`()

      Sets the `rate_max_gap` option, which controls the amount of time AMPS will go without producing a message from a transaction log replay when the `rate` option is specified. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the maximum gap as an interval (such as `30s`)

    `set_replace`()

      Adds the `replace` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_resume`()

      Adds the `resume` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_send_keys`()

      Adds the `send_keys` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_skip_n`()

      Sets the `skip_n` value for a command. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the skip_n value as an integer

    `set_timestamp`()

      Adds the `timestamp` option to the current set of options. See the AMPS Command Reference and AMPS User Guide for details.

    `set_top_n`()

      Sets the top_n value for a command. See the AMPS Command Reference and AMPS User Guide for details.

      Parameters: | value – the top_n value, as an integer

  `Message.``ack`()

    Acknowledges the current message queue message.

  `Message.``getAckType`()

    Gets the value of ack_type for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of ack_type on this message.

  `Message.``getBatchSize`()

    Gets the value of the BatchSize header.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of batch_size on this message.

  `Message.``getBookmark`()

    Gets the value of the Bookmark header. For messages returned from AMPS, this is an opaque identifier that AMPS can use to locate the message in the transaction log, and is returned on messages that are produced from the transaction log (for example, messages delivered from queues or returned in response to a bookmark subscribe command).

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of bookmark on this message.

  `Message.``getClientName`()

    Gets the value of client_name for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of client_name on this message.

  `Message.``getCommand`()

    Gets the value of the command header, which specifies what type of message this is. Every message from AMPS has the Command header set, and should interpret the message based on the Command. See the AMPS Command reference for details on what Command values will be returned in response to a given command to AMPS, what header fields are provided on Messages with a given Command value, and how an application should interpret those header fields.

    Returns: | The value of the Command set on this message.

  `Message.``getCommandId`()

    Gets the value of command_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of command_id on this message.

  `Message.``getCorrelationId`()

    Gets the value of the correlation_id header. The correlation ID is set when a command is provided to AMPS. The AMPS server does not process or interpret this value: the correlation ID is returned verbatim, as it was submitted with the command.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of correlation_id on this message.

  `Message.``getData`()

    Gets the value of data for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of data on this message.

  `Message.``getExpiration`()

    Gets the value of expiration for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of expiration on this message.

  `Message.``getFilter`()

    Gets the value of filter for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of filter on this message.

  `Message.``getGroupSequenceNumber`()

    Gets the value of group_seq_no for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of group_seq_no on this message.

  `Message.``getHeartbeat`()

    Gets the value of heartbeat for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of heartbeat on this message.

  `Message.``getLeasePeriod`()

    Gets the value of lease_period for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of lease_period on this message.

  `Message.``getMatches`()

    Gets the value of matches for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of matches on this message.

  `Message.``getMessageLength`()

    Gets the value of message_size for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of message_size on this message.

  `Message.``getMessageType`()

    Gets the value of message_type for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of message_type on this message.

  `Message.``getOptions`()

    Gets the value of options for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of options on this message.

  `Message.``getOrderBy`()

    Gets the value of order_by for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of order_by on this message.

  `Message.``getPassword`()

    Gets the value of password for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of password on this message.

  `Message.``getQueryID`()

    Gets the value of query_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of query_id on this message.

  `Message.``getReason`()

    Gets the value of reason for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of reason on this message.

  `Message.``getRecordsInserted`()

    Gets the value of records_inserted for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_inserted on this message.

  `Message.``getRecordsReturned`()

    Gets the value of records_returned for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_returned on this message.

  `Message.``getRecordsUpdated`()

    Gets the value of records_updated for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_updated on this message.

  `Message.``getSequence`()

    Gets the value of sequence for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sequence on this message.

  `Message.``getSowDelete`()

    Gets the value of sow_deleted for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_deleted on this message.

  `Message.``getSowKey`()

    Gets the value of the sow_key header. When a message is returned from a Topic in the State of the World, this header provides the key that the AMPS server uses to identify the message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_key on this message.

  `Message.``getSowKeys`()

    Gets the value of sow_keys for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_keys on this message.

  `Message.``getStatus`()

    Gets the value of status for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of status on this message.

  `Message.``getSubscriptionId`()

    Gets the value of sub_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sub_id on this message.

  `Message.``getSubscriptionIds`()

    Gets the value of sub_ids for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sub_ids on this message.

  `Message.``getTimeoutInterval`()

    Gets the value of timeout_interval for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of timeout_interval on this message.

  `Message.``getTimestamp`()

    Gets the value of the timestamp header. When the `timestamp` option is specified on a command, `publish` and `sow` messages returned will have the time at which the AMPS server processed the message returned in this field.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of timestamp on this message.

  `Message.``getTopNRecordsReturned`()

    Gets the value of top_n for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of top_n on this message.

  `Message.``getTopic`()

    Gets the value of topic for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of topic on this message.

  `Message.``getTopicMatches`()

    Gets the value of topic_matches for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of topic_matches on this message.

  `Message.``getUserId`()

    Gets the value of user_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of user_id on this message.

  `Message.``getVersion`()

    Gets the value of version for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of version on this message.

  `Message.``get_ack_type`()

    Gets the value of ack_type for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of ack_type on this message.

  `Message.``get_batch_size`()

    Gets the value of the BatchSize header.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of batch_size on this message.

  `Message.``get_bookmark`()

    Gets the value of the Bookmark header. For messages returned from AMPS, this is an opaque identifier that AMPS can use to locate the message in the transaction log, and is returned on messages that are produced from the transaction log (for example, messages delivered from queues or returned in response to a bookmark subscribe command).

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of bookmark on this message.

  `Message.``get_bookmark_seq_no`()

    Gets the bookmark sequence number of this message.

  `Message.``get_client_name`()

    Gets the value of client_name for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of client_name on this message.

  `Message.``get_command`()

    Gets the value of the command header, which specifies what type of message this is. Every message from AMPS has the Command header set, and should interpret the message based on the Command. See the AMPS Command reference for details on what Command values will be returned in response to a given command to AMPS, what header fields are provided on Messages with a given Command value, and how an application should interpret those header fields.

    Returns: | The value of the Command set on this message.

  `Message.``get_command_id`()

    Gets the value of command_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of command_id on this message.

  `Message.``get_correlation_id`()

    Gets the value of the correlation_id header. The correlation ID is set when a command is provided to AMPS. The AMPS server does not process or interpret this value: the correlation ID is returned verbatim, as it was submitted with the command.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of correlation_id on this message.

  `Message.``get_data`()

    Gets the value of data for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of data on this message.

  `Message.``get_data_raw`()

    Returns: | the data of this message as a python bytes object

  `Message.``get_expiration`()

    Gets the value of expiration for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of expiration on this message.

  `Message.``get_filter`()

    Gets the value of filter for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of filter on this message.

  `Message.``get_group_seq_no`()

    Gets the value of group_seq_no for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of group_seq_no on this message.

  `Message.``get_heartbeat`()

    Gets the value of heartbeat for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of heartbeat on this message.

  `Message.``get_lease_period`()

    Gets the value of lease_period for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of lease_period on this message.

  `Message.``get_matches`()

    Gets the value of matches for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of matches on this message.

  `Message.``get_message_size`()

    Gets the value of message_size for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of message_size on this message.

  `Message.``get_message_type`()

    Gets the value of message_type for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of message_type on this message.

  `Message.``get_options`()

    Gets the value of options for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of options on this message.

  `Message.``get_order_by`()

    Gets the value of order_by for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of order_by on this message.

  `Message.``get_password`()

    Gets the value of password for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of password on this message.

  `Message.``get_query_id`()

    Gets the value of query_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of query_id on this message.

  `Message.``get_reason`()

    Gets the value of reason for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of reason on this message.

  `Message.``get_records_inserted`()

    Gets the value of records_inserted for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_inserted on this message.

  `Message.``get_records_returned`()

    Gets the value of records_returned for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_returned on this message.

  `Message.``get_records_updated`()

    Gets the value of records_updated for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of records_updated on this message.

  `Message.``get_sequence`()

    Gets the value of sequence for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sequence on this message.

  `Message.``get_sow_deleted`()

    Gets the value of sow_deleted for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_deleted on this message.

  `Message.``get_sow_key`()

    Gets the value of the sow_key header. When a message is returned from a Topic in the State of the World, this header provides the key that the AMPS server uses to identify the message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_key on this message.

  `Message.``get_sow_keys`()

    Gets the value of sow_keys for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sow_keys on this message.

  `Message.``get_status`()

    Gets the value of status for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of status on this message.

  `Message.``get_sub_id`()

    Gets the value of sub_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sub_id on this message.

  `Message.``get_sub_ids`()

    Gets the value of sub_ids for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of sub_ids on this message.

  `Message.``get_timeout_interval`()

    Gets the value of timeout_interval for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of timeout_interval on this message.

  `Message.``get_timestamp`()

    Gets the value of the timestamp header. When the `timestamp` option is specified on a command, `publish` and `sow` messages returned will have the time at which the AMPS server processed the message returned in this field.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of timestamp on this message.

  `Message.``get_top_n`()

    Gets the value of top_n for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of top_n on this message.

  `Message.``get_topic`()

    Gets the value of topic for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of topic on this message.

  `Message.``get_topic_matches`()

    Gets the value of topic_matches for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of topic_matches on this message.

  `Message.``get_user_id`()

    Gets the value of user_id for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of user_id on this message.

  `Message.``get_version`()

    Gets the value of version for this message.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of version on this message.

  `Message.``reset`()

    Resets the contents of this message.

  `Message.``setAckType`()

    Sets the value of ack_type for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for ack_type.
    Returns: | this message

  `Message.``setBatchSize`()

    Sets the value of the BatchSize header, which is used to control the number of records that AMPS will send in a batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for batch_size.
    Returns: | this message

  `Message.``setBookmark`()

    Sets the value of the Bookmark header. For a subscription, this identifies the point at which to begin the replay. For a sow_delete (queue acknowledgement), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for bookmark.
    Returns: | this message

  `Message.``setClientName`()

    Sets the value of the ClientName header. In a `logon` command, this header sets the client name for the connection.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for client_name.
    Returns: | this message

  `Message.``setCommand`()

    Sets the value of the command header. Every message sent to AMPS is required to have a command header set, which specifies how the message is to be intrepreted. It is an error to send a message to AMPS without setting this field.

    See the AMPS Command Reference for details on the values that AMPS accepts for this header, how those commands are interpreted, and what headers and options can be set for a given command.

    Note

    If you are building a command to be sent to AMPS, using the AMPS.Command class rather than Message is recommended for most purposes.

    Param: | The new value for the Command.

  `Message.``setCommandId`()

    Sets the value of the command_id header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of command_id on this message.

  `Message.``setCorrelationId`()

    Sets the value of the correlation_id header. The AMPS server does not process or interpret this value; however, the value set must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for correlation_id.
    Returns: | this message

  `Message.``setData`()

    Sets the value of data for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for data.
    Returns: | this message

  `Message.``setExpiration`()

    Sets the value of the expiration header. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for expiration.
    Returns: | this message

  `Message.``setFilter`()

    Sets the value of filter for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for filter.
    Returns: | this message

  `Message.``setGroupSequenceNumber`()

    Sets the value of group_seq_no for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for group_seq_no.
    Returns: | this message

  `Message.``setHeartbeat`()

    Sets the value of heartbeat for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for heartbeat.
    Returns: | this message

  `Message.``setLeasePeriod`()

    Sets the value of lease_period for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for lease_period.
    Returns: | this message

  `Message.``setMatches`()

    Sets the value of matches for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for matches.
    Returns: | this message

  `Message.``setMessageLength`()

    Sets the value of message_size for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for message_size.
    Returns: | this message

  `Message.``setMessageType`()

    Sets the value of the message_type header. This header is used during logon to set the message type for the connection, and is ignored on other commands.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for message_type.
    Returns: | this message

  `Message.``setOptions`()

    Sets the value of options for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for options.
    Returns: | this message

  `Message.``setOrderBy`()

    Sets the value of order_by for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for order_by.
    Returns: | this message

  `Message.``setPassword`()

    Sets the value of password for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for password.
    Returns: | this message

  `Message.``setQueryID`()

    Sets the value of query_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for query_id.
    Returns: | this message

  `Message.``setReason`()

    Sets the value of reason for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for reason.
    Returns: | this message

  `Message.``setRecordsInserted`()

    Sets the value of records_inserted for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_inserted.
    Returns: | this message

  `Message.``setRecordsReturned`()

    Sets the value of records_returned for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_returned.
    Returns: | this message

  `Message.``setRecordsUpdated`()

    Sets the value of records_updated for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_updated.
    Returns: | this message

  `Message.``setSequence`()

    Sets the value of sequence for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sequence.
    Returns: | this message

  `Message.``setSowDelete`()

    Sets the value of sow_deleted for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_deleted.
    Returns: | this message

  `Message.``setSowKey`()

    Sets the value of the sow_key header. When publishing a message to a topic in the State of the World that is configured to require the publisher to set an explicit key (rather than having AMPS calculate the key based on the message contents), the publisher uses this header to set the key to be used.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_key.
    Returns: | this message

  `Message.``setSowKeys`()

    Sets the value of the sow_keys header. When sending a command to AMPS that should only apply to specific items in a State of the World topic, the sow_keys header can restrict the effects of the command to just the items that have a SowKey that appears in this header.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_key.
    Returns: | this message

  `Message.``setStatus`()

    Sets the value of status for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for status.
    Returns: | this message

  `Message.``setSubscriptionId`()

    Sets the value of sub_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sub_id.
    Returns: | this message

  `Message.``setSubscriptionIds`()

    Sets the value of sub_ids for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sub_ids.
    Returns: | this message

  `Message.``setTimeoutInterval`()

    Sets the value of timeout_interval for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for timeout_interval.
    Returns: | this message

  `Message.``setTimestamp`()

    Sets the value of the timestamp header. This option is provided for use by the AMPS Client when constructing a message. No commands to the AMPS server use this header.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for timestamp.
    Returns: | this message

  `Message.``setTopNRecordsReturned`()

    Sets the value of top_n for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for top_n.
    Returns: | this message

  `Message.``setTopic`()

    Sets the value of topic for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for topic.
    Returns: | this message

  `Message.``setTopicMatches`()

    Sets the value of topic_matches for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for topic_matches.
    Returns: | this message

  `Message.``setUserId`()

    Sets the value of user_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for user_id.
    Returns: | this message

  `Message.``setVersion`()

    Sets the value of version for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for version.
    Returns: | this message

  `Message.``set_ack_type`()

    Sets the value of ack_type for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for ack_type.
    Returns: | this message

  `Message.``set_batch_size`()

    Sets the value of the BatchSize header, which is used to control the number of records that AMPS will send in a batch when returning the results of a SOW query. See the AMPS User Guide for details on SOW query batches.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for batch_size.
    Returns: | this message

  `Message.``set_bookmark`()

    Sets the value of the Bookmark header. For a subscription, this identifies the point at which to begin the replay. For a sow_delete (queue acknowledgement), this indicates the message or messages to acknowledge. For a query on a SOW topic with History configured, this indicates the point at which to query the topic.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for bookmark.
    Returns: | this message

  `Message.``set_client_name`()

    Sets the value of the ClientName header. In a `logon` command, this header sets the client name for the connection.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for client_name.
    Returns: | this message

  `Message.``set_command`()

    Sets the value of the command header. Every message sent to AMPS is required to have a command header set, which specifies how the message is to be intrepreted. It is an error to send a message to AMPS without setting this field.

    See the AMPS Command Reference for details on the values that AMPS accepts for this header, how those commands are interpreted, and what headers and options can be set for a given command.

    Note

    If you are building a command to be sent to AMPS, using the AMPS.Command class rather than Message is recommended for most purposes.

    Param: | The new value for the Command.

  `Message.``set_command_id`()

    Sets the value of the command_id header. This header is used to identify responses to the command. The AMPS FAQ has details on the relationship between command ID, subscription ID, and query ID.

    Not all headers are populated by AMPS for all commands. See the AMPS Command Reference for which headers are returned by AMPS in response to a specific command

    Returns: | The value of command_id on this message.

  `Message.``set_correlation_id`()

    Sets the value of the correlation_id header. The AMPS server does not process or interpret this value; however, the value set must contain only characters that are valid in Base64 encoding for the server to be guaranteed to process the Message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for correlation_id.
    Returns: | this message

  `Message.``set_data`()

    Sets the value of data for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for data.
    Returns: | this message

  `Message.``set_expiration`()

    Sets the value of the expiration header. For a publish to a SOW topic or queue, this sets the number of seconds the message will be active before expiring.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for expiration.
    Returns: | this message

  `Message.``set_filter`()

    Sets the value of filter for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for filter.
    Returns: | this message

  `Message.``set_group_seq_no`()

    Sets the value of group_seq_no for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for group_seq_no.
    Returns: | this message

  `Message.``set_heartbeat`()

    Sets the value of heartbeat for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for heartbeat.
    Returns: | this message

  `Message.``set_lease_period`()

    Sets the value of lease_period for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for lease_period.
    Returns: | this message

  `Message.``set_matches`()

    Sets the value of matches for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for matches.
    Returns: | this message

  `Message.``set_message_size`()

    Sets the value of message_size for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for message_size.
    Returns: | this message

  `Message.``set_message_type`()

    Sets the value of the message_type header. This header is used during logon to set the message type for the connection, and is ignored on other commands.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for message_type.
    Returns: | this message

  `Message.``set_options`()

    Sets the value of options for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for options.
    Returns: | this message

  `Message.``set_order_by`()

    Sets the value of order_by for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for order_by.
    Returns: | this message

  `Message.``set_password`()

    Sets the value of password for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for password.
    Returns: | this message

  `Message.``set_query_id`()

    Sets the value of query_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for query_id.
    Returns: | this message

  `Message.``set_reason`()

    Sets the value of reason for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for reason.
    Returns: | this message

  `Message.``set_records_inserted`()

    Sets the value of records_inserted for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_inserted.
    Returns: | this message

  `Message.``set_records_returned`()

    Sets the value of records_returned for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_returned.
    Returns: | this message

  `Message.``set_records_updated`()

    Sets the value of records_updated for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for records_updated.
    Returns: | this message

  `Message.``set_sequence`()

    Sets the value of sequence for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sequence.
    Returns: | this message

  `Message.``set_sow_deleted`()

    Sets the value of sow_deleted for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_deleted.
    Returns: | this message

  `Message.``set_sow_key`()

    Sets the value of the sow_key header. When publishing a message to a topic in the State of the World that is configured to require the publisher to set an explicit key (rather than having AMPS calculate the key based on the message contents), the publisher uses this header to set the key to be used.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_key.
    Returns: | this message

  `Message.``set_sow_keys`()

    Sets the value of the sow_keys header. When sending a command to AMPS that should only apply to specific items in a State of the World topic, the sow_keys header can restrict the effects of the command to just the items that have a SowKey that appears in this header.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sow_key.
    Returns: | this message

  `Message.``set_status`()

    Sets the value of status for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for status.
    Returns: | this message

  `Message.``set_sub_id`()

    Sets the value of sub_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sub_id.
    Returns: | this message

  `Message.``set_sub_ids`()

    Sets the value of sub_ids for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for sub_ids.
    Returns: | this message

  `Message.``set_timeout_interval`()

    Sets the value of timeout_interval for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for timeout_interval.
    Returns: | this message

  `Message.``set_timestamp`()

    Sets the value of the timestamp header. This option is provided for use by the AMPS Client when constructing a message. No commands to the AMPS server use this header.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for timestamp.
    Returns: | this message

  `Message.``set_top_n`()

    Sets the value of top_n for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for top_n.
    Returns: | this message

  `Message.``set_topic`()

    Sets the value of topic for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for topic.
    Returns: | this message

  `Message.``set_topic_matches`()

    Sets the value of topic_matches for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for topic_matches.
    Returns: | this message

  `Message.``set_user_id`()

    Sets the value of user_id for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for user_id.
    Returns: | this message

  `Message.``set_version`()

    Sets the value of version for this message.

    Not all headers are processed by AMPS for all commands. See the AMPS Command Reference for which headers are used by AMPS for a specific command.

    Parameters: | value – The new value for version.
    Returns: | this message

class `AMPS.``MessageStream`

  Bases: `object`

  A message handler used to create an in-thread iterator interface over the Messages that are returned from a command.

  `close`()

    Closes this message stream.

  `conflate`()

    Enables message conflation by SOW key.

  `get_depth`()

    Gets the current depth of this message stream.

  `get_max_depth`()

    Gets the maximum depth allowed for this message stream.

  `max_depth`(maxDepth)

    Sets the maximum depth allowed for this message stream (that is, the maximum number of messages stored in this object at a given time). When this limit is exceeded, the Client will stop receiving messages from the socket until messages are removed from the MessageStream.

    Parameters: | maxDepth – The maximum number of messages that are buffered in this stream before pushback on the network connection.

  `timeout`(millis)

    Sets the timeout on this message stream.

    > If no message is received in this timeout, None is returned to the caller of next(), and the stream remains open.

exception `AMPS.``MessageTypeError`

  Bases: `AMPS.ConnectionException`

  deprecated - use `MessageTypeException`

exception `AMPS.``MessageTypeException`

  Bases: `AMPS.MessageTypeError`

  MessageTypeException is raised when the message type requested by the client is unsupported.

exception `AMPS.``MessageTypeNotFound`

  Bases: `AMPS.MessageTypeException`

  deprecated - use `MessageTypeException`

exception `AMPS.``MissingFieldsException`

  Bases: `AMPS.CommandException`

  The MissingFieldsException is raised when a client attempts to execute a command and required fields are missing.

class `AMPS.``NVFIXBuilder`

  Bases: `object`

  Convenience class for easily creating NVFIX strings. Constructor arguments:

  Parameters: | delimiter – The delimiter to use between NVFIX fields. Defaults to \x01 if no delimiter is provided.

  `append`(tag, value, (optional)offset, (optional)length)

    Appends tag=value to self.

    Parameters: | tag (int) – The tag to use. value (str) – The value for the given tag. offset (int) – Optional. The offset into value at which the value actually starts. length – Optional. The length of the actual value within value. Only valid and required if offset is also provided

  `get_string`()

    Called to get the string NVFIX message.

    Returns: | The NVFIX message as a string.

  `reset`()

    Called to clear the state of the NVFIXBuilder to create a new NVFIX message

class `AMPS.``NVFIXShredder`

  Bases: `object`

  Convenience class for easily processing NVFIX strings. Constructor arguments:

  Parameters: | separator – The delimiter to expect between NVFIX fields. Defaults to \x01 if no delimiter is provided.

  `to_map`(message)

    Parse the provided NVFIX message and return a map that contains the fields in the message.

    Parameters: | message – The NVFIX message to parse.

exception `AMPS.``NameInUseException`

  Bases: `AMPS.ClientNameInUse`

  NameInUseException is raised when a client attempts to connect and uses the same client name as a currently connected client.

exception `AMPS.``NotEntitledError`

  Bases: `AMPS.ConnectionException`

  deprecated - use `NotEntitledException`

exception `AMPS.``NotEntitledException`

  Bases: `AMPS.NotEntitledError`

  NotEntitledException is raised when an authenticated client attempts to access a resource to which the user has not been granted proper entitlements.

exception `AMPS.``PublishException`

  Bases: `AMPS.CommandException`

  The PublishException is raised when a client attempts to publish an invalid message or some other error occurs with the message.

class `AMPS.``PublishStore`

  Bases: `object`

  AMPS PublishStore Object

  Stores published records in a file while awaiting an ACK from the server. Construct with the name of the file to use for record storage and optionally, a Boolean to specify if the store should throw an exception if logging onto a server that might be missing messages not in the store.

  `get_error_on_publish_gap`()
    Returns If true, PublishStoreGapException can be thrown
      by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.
  `get_unpersisted_count`()

    Returns the number of messages published which have not been ACK’ed by the server.

  `set_error_on_publish_gap`()

    Called to enable or disable throwing PublishStoreGapException.

    Parameters: | error_on_publish_gap (Boolean) – If true, PublishStoreGapException can be thrown by the client publish store if the client logs onto a server that appears to be missing messages no longer held in the store.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

  `truncate_on_close`()

    Sets if the PublishStore should truncate the file to initial capacity when it closes if it is empty.

exception `AMPS.``PublishStoreGapException`

  Bases: `AMPS.StoreException`

  An exception was thrown by the underlying publish store because the client is attempting to logon to a server that appears to be missing messages from this client that are no longer in the publish store.

class `AMPS.``Reason`

  Bases: `object`

  AMPS Reason Object

class `AMPS.``RecoveryPoint`

  Bases: `object`

  This class represents a subscription’s recovery point. It consists of a sub_id and a bookmark, which is opaque.

  `get_bookmark`()

    returns the bookmark for this RecoveryPoint

  `get_sub_id`()

    returns the subId of this RecoveryPoint

exception `AMPS.``RetryOperation`

  Bases: `AMPS.ConnectionException`

  deprecated - use `RetryOperationException`

exception `AMPS.``RetryOperationException`

  Bases: `AMPS.RetryOperation`

  RetryOperationException is raised when sending of a message has failed two consecutive attempts. Any send which receives this can assume that the message was not delivered to AMPS.

class `AMPS.``RingBookmarkStore`

  Bases: `object`

  AMPS RingBookmarkStore Object

  `discard`(subid, sequence)

    Log a discard-bookmark entry to the persisted log.

  `discard_message`(message)

    Log a message as discarded from the store.

  `get_most_recent`(subid)

    Returns the most recent bookmark from the log that ought to be used for (re-)subscriptions.

  `get_oldest_bookmark_seq`(subid)

    Called to find the oldest bookmark sequence in the store.

  `is_discarded`(message)

    Called for each arriving message to determine if the application has already seen this bookmark and should not be reprocessed. Returns True if the bookmark is in the log and should not be re-processed, False otherwise.

  `log`(message)

    Log a bookmark to the log and return the corresponding sequence number.

  `persisted`(subid, bookmark)

    Mark all bookmarks up to the provided one as replicated to all replication destinations for the given subscription.

  `persisted_index`()

    persisted(subid, bookmark_index)

    Mark all bookmarks up to the provided index as replicated to all replication destinations for the given subscription.

  `purge`()

    Called to purge the contents of this store. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `purge_sub_id`()

    Called to purge the contents of this store for a given subscription id. Removes any tracking history associated with publishers and received messages, and may delete or truncate on-disk representations as well.

  `set_resize_handler`()

    Sets the object to call when the store needs to resize.

  `set_server_version`(version)

    Internally used to set the server version so the store knows how to deal with persisted acks and calls to get_most_recent().

class `AMPS.``SOWRecoveryPointAdapter`

  Bases: `object`

  This class can be used as an adapter on an AMPS.MemoryBookmarkStore to save enough recovery state information to guarantee no missed messages. It must be constructed with a client using json message type, connected and logged on to a server on which the chosen topic is defined as a SOW topic with key fields equivalent to the chosen client name field and sub id field. It also must not be the same client that is being tracked, whose name is provided as the tracked client name.

  `close`(subid, bookmark)

    Close the store so it can no longer be used. May close the store client if that option was true when constructed.

  `get_exception_listener`()

    Returns the exception listener callable set on self, or None.

  `next`()
    Returns the next RecoveryPoint from the SOW or an empty one if
      recovery has completed.
  `prune`()

    This has no affect on a SOWRecoveryPointAdapter.

  `purge`(sub_id)

    If sub_id is provided, remove all records related to sub_id. If no sub_id is provided, remove all records for this client. :param sub_id: The optional sub_id to remove or all if none

  `set_exception_listener`(listener)

    set_exception_listener(exception_listener)

    > Sets the exception listener instance used for communicating
    >   absorbed exceptions.

    Parameters: | exception_listener (`Exception`) – The exception listener instance to invoke for exceptions.

  `update`(recoveryPoint)

    Updates the SOW with the new information in recoveryPoint. :param recovery_point: The new recovery information to save. :type recovery_point: :ampspy:recoveryPoint

class `AMPS.``Store`

  Bases: `object`

  AMPS Store Object

exception `AMPS.``StoreException`

  Bases: `AMPS.StoreError`

  An exception was thrown by the underlying publish store.

exception `AMPS.``StreamError`

  Bases: `AMPS.ConnectionException`

  deprecated - use `StreamException`

exception `AMPS.``StreamException`

  Bases: `AMPS.StreamError`

  StreamException is raised when an incoming message is improperly formatted.

exception `AMPS.``SubidInUseException`

  Bases: `AMPS.CommandException`

  The SubidInUseException is raised when a subscription is place with the same subscription id.

exception `AMPS.``SubscriptionAlreadyExists`

  Bases: `AMPS.CommandException`

  deprecated - use `SubscriptionAlreadyExistsException`

exception `AMPS.``SubscriptionAlreadyExistsException`

  Bases: `AMPS.SubscriptionAlreadyExists`

  The SubscriptionAlreadyExistsException is raised when a subscription is place which matches a subscription that already exists.

exception `AMPS.``TimedOut`

  Bases: `AMPS.ConnectionException`

  deprecated - use `TimedOutException`

exception `AMPS.``TimedOutException`

  Bases: `AMPS.TimedOut`

  The TimedOutException is raised when an operation times out.

exception `AMPS.``TransportError`

  Bases: `AMPS.ConnectionException`

  deprecated - use `TransportException`

exception `AMPS.``TransportException`

  Bases: `AMPS.TransportError`

  TransportException is raised when an AMPS Client transport has an error.

exception `AMPS.``TransportNotFound`

  Bases: `AMPS.TransportException`

  deprecated - use `TransportException`

exception `AMPS.``TransportTypeException`

  Bases: `AMPS.ConnectionException`

  TransportTypeException is raised when an unknown or invalid transport is attempted.

exception `AMPS.``UnknownError`

  Bases: `AMPS.CommandException`

  deprecated - use `UnknownException`

exception `AMPS.``UnknownException`

  Bases: `AMPS.UnknownError`

  The UnknownException is raised when the AMPS Python Client is in an unrecoverable state.

class `AMPS.``VersionInfo`

  Bases: `object`

  AMPS VersionInfo Object

  `get_old_style_version`()

    Returns the version as number with 2 digits for major version, 2 digits for minor version, 2 digits for maintenance version and 2 digits for patch version. Any values greater than 99 are represented as 99.

  `get_version_number`()

    Returns the version as number with 4 digits for major version, 4 digits for minor version, 5 digits for maintenance version and 5 digits for patch version.

  `get_version_string`()

    Returns the version string.

  `set_version`(version)

    Sets the string version to represent.

`AMPS.``ssl_init`()

  Initializes SSL support in the AMPS module.

  Parameters: | dllpath – The path to the OpenSSL DLL or shared library to use for SSL functionality.

`AMPS.``ssl_load_verify_locations`()

  Override default CA certificate locations for AMPS SSL connections.

  Parameters: | ca_file – Path to a PEM file containing CA certificates. ca_path – Path to a directory containing multiple CA certificates as PEM files. See OpenSSL’s SSL_CTX_load_verify_locations for more information.

`AMPS.``ssl_set_verify`()

  Enables or disables peer certificate validation for SSL connections.

  Parameters: | enabled – True to enable, False to disable. Default: False (disabled).