zeroc-ice 3.7.9.1 → 3.8.0

data/dist/ice/slice/Ice/Metrics.ice

@@ -0,0 +1,201 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["js:module:@zeroc/ice"]]
+
+#include "BuiltinSequences.ice"
+
+/// The Ice Management eXtension facility.
+["java:identifier:com.zeroc.IceMX"]
+["swift:identifier:Ice"]
+module IceMX
+{
+    /// A dictionary of strings to integers.
+    dictionary<string, int> StringIntDict;
+
+    /// The base class for metrics. A metrics object represents a collection of measurements associated to a given a
+    /// system.
+    class Metrics
+    {
+        /// The metrics identifier.
+        string id;
+
+        /// The total number of objects observed by this metrics. This includes the number of currently observed objects
+        /// and the number of objects observed in the past.
+        long total = 0;
+
+        /// The number of objects currently observed by this metrics.
+        int current = 0;
+
+        /// The sum of the lifetime of each observed objects. This does not include the lifetime of objects which are
+        /// currently observed, only the objects observed in the past.
+        long totalLifetime = 0;
+
+        /// The number of failures observed.
+        int failures = 0;
+    }
+
+    /// Keeps track of metrics failures.
+    struct MetricsFailures
+    {
+        /// The identifier of the metrics object associated to the failures.
+        string id;
+
+        /// The failures observed for this metrics.
+        StringIntDict failures;
+    }
+
+    /// A sequence of {@link MetricsFailures}.
+    sequence<MetricsFailures> MetricsFailuresSeq;
+
+    /// A sequence of metrics.
+    /// @remark We use a sequence here instead of a map because the ID of the metrics is already included in the Metrics
+    /// class and using sequences of metrics objects is more efficient than using dictionaries since lookups are not
+    /// necessary.
+    sequence<Metrics> MetricsMap;
+
+    /// A metrics view is a dictionary of metrics maps. The key of the dictionary is the name of the metrics map.
+    dictionary<string, MetricsMap> MetricsView;
+
+    /// The exception that is thrown when a metrics view cannot be found.
+    exception UnknownMetricsView
+    {
+    }
+
+    /// The metrics administrative facet interface. This interface allows remote administrative clients to access the
+    /// metrics of an application that enabled the Ice administrative facility and configured one or more metrics views.
+    interface MetricsAdmin
+    {
+        /// Gets the names of enabled and disabled metrics.
+        /// @param disabledViews The names of the disabled views.
+        /// @return The names of the enabled views.
+        Ice::StringSeq getMetricsViewNames(out Ice::StringSeq disabledViews);
+
+        /// Enables a metrics view.
+        /// @param name The metrics view name.
+        /// @throws UnknownMetricsView Thrown when the metrics view cannot be found.
+        void enableMetricsView(string name)
+            throws UnknownMetricsView;
+
+        /// Disables a metrics view.
+        /// @param name The metrics view name.
+        /// @throws UnknownMetricsView Thrown when the metrics view cannot be found.
+        void disableMetricsView(string name)
+            throws UnknownMetricsView;
+
+        /// Gets the metrics objects for the given metrics view.
+        /// @param view The name of the metrics view.
+        /// @param timestamp The local time of the process when the metrics objects were retrieved.
+        /// @return The metrics view data, a dictionary of metric maps for each metrics class configured with the view.
+        /// The @p timestamp allows the client to compute averages which are not dependent of the invocation latency for
+        /// this operation.
+        /// @throws UnknownMetricsView Thrown when the metrics view cannot be found.
+        ["format:sliced"]
+        MetricsView getMetricsView(string view, out long timestamp)
+            throws UnknownMetricsView;
+
+        /// Gets the metrics failures associated with the given @p view and @p map.
+        /// @param view The name of the metrics view.
+        /// @param map The name of the metrics map.
+        /// @return The metrics failures associated with the map.
+        /// @throws UnknownMetricsView Thrown when the metrics view cannot be found.
+        MetricsFailuresSeq getMapMetricsFailures(string view, string map)
+            throws UnknownMetricsView;
+
+        /// Gets the metrics failure associated for the given metrics.
+        /// @param view The name of the metrics view.
+        /// @param map The name of the metrics map.
+        /// @param id The ID of the metrics.
+        /// @return The metrics failures associated with the metrics.
+        /// @throws UnknownMetricsView Thrown when the metrics view cannot be found.
+        MetricsFailures getMetricsFailures(string view, string map, string id)
+            throws UnknownMetricsView;
+    }
+
+    /// Provides information on the number of threads currently in use and their activity.
+    class ThreadMetrics extends Metrics
+    {
+        /// The number of threads which are currently performing socket reads or writes.
+        int inUseForIO = 0;
+
+        /// The number of threads which are currently calling user code (servant dispatch, AMI callbacks, etc).
+        int inUseForUser = 0;
+
+        /// The number of threads which are currently performing other activities such as DNS lookups, garbage
+        /// collection, etc. These are all the other threads created by the Ice runtime that are not counted in
+        /// {@link #inUseForUser} or {@link #inUseForIO}.
+        int inUseForOther = 0;
+    }
+
+    /// Provides information on servant dispatches.
+    class DispatchMetrics extends Metrics
+    {
+        /// The number of dispatches that failed with a user exception.
+        int userException = 0;
+
+        /// The size of the incoming requests. This corresponds to the size of the marshaled input parameters.
+        long size = 0;
+
+        /// The size of the replies. This corresponds to the size of the marshaled output and return parameters.
+        long replySize = 0;
+    }
+
+    /// Provides information on child invocations. A child invocation is either remote (sent over an Ice connection) or
+    /// collocated. An invocation can have multiple child invocations if it is retried. Child invocation metrics are
+    /// embedded within {@link InvocationMetrics}.
+    class ChildInvocationMetrics extends Metrics
+    {
+        /// The size of the invocation. This corresponds to the size of the marshaled input parameters.
+        long size = 0;
+
+        /// The size of the invocation reply. This corresponds to the size of the marshaled output and return
+        /// parameters.
+        long replySize = 0;
+    }
+
+    /// Provides information on invocations that are collocated. Collocated metrics are embedded within
+    /// {@link InvocationMetrics}.
+    class CollocatedMetrics extends ChildInvocationMetrics
+    {
+    }
+
+    /// Provides information on invocations that are specifically sent over Ice connections. Remote metrics are embedded
+    /// within {@link InvocationMetrics}.
+    class RemoteMetrics extends ChildInvocationMetrics
+    {
+    }
+
+    /// Provide measurements for proxy invocations. Proxy invocations can either be sent over the wire or be collocated.
+    class InvocationMetrics extends Metrics
+    {
+        /// The number of retries for the invocations.
+        ["ruby:identifier:retryCount"]
+        int retry = 0;
+
+        /// The number of invocations that failed with a user exception.
+        int userException = 0;
+
+        /// The remote invocation metrics map.
+        /// @see RemoteMetrics
+        MetricsMap remotes;
+
+        /// The collocated invocation metrics map.
+        /// @see CollocatedMetrics
+        MetricsMap collocated;
+    }
+
+    /// Provides information on the data sent and received over Ice connections.
+    class ConnectionMetrics extends Metrics
+    {
+        /// The number of bytes received by the connection.
+        long receivedBytes = 0;
+
+        /// The number of bytes sent by the connection.
+        long sentBytes = 0;
+    }
+}

data/dist/ice/slice/Ice/OperationMode.ice

@@ -0,0 +1,38 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["cpp:no-default-include"]]
+[["cpp:include:Ice/Config.h"]]
+[["cpp:include:Ice/StreamHelpers.h"]]
+
+[["js:module:@zeroc/ice"]]
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Specifies if an operation is idempotent, which affects the retry behavior of the Ice client runtime.
+    enum OperationMode
+    {
+        /// A non-idempotent operation (the default). The Ice client runtime guarantees that it will not violate
+        /// at-most-once semantics for operations with this mode.
+        ["swift:identifier:normal"]
+        Normal,
+
+        /// Equivalent to {@link #Idempotent}, but deprecated.
+        ["deprecated:Use Idempotent instead."]
+        ["swift:identifier:nonmutating"]
+        Nonmutating,
+
+        /// An idempotent operation. The Ice client runtime does not guarantee at-most-once semantics for such an
+        /// operation.
+        /// @remark When an operation is idempotent, the Ice runtime will attempt to transparently recover from certain
+        /// runtime errors by re-issuing a failed request transparently.
+        ["swift:identifier:idempotent"]
+        Idempotent
+    }
+}

data/dist/ice/slice/Ice/Process.ice

@@ -0,0 +1,28 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["js:module:@zeroc/ice"]]
+
+#include "LocatorRegistry.ice"
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// A server application managed by a locator implementation such as IceGrid hosts a Process object and registers a
+    /// proxy to this object with the locator registry. See {@link LocatorRegistry::setServerProcessProxy}.
+    interface Process
+    {
+        /// Initiates a graceful shutdown of the server application.
+        void shutdown();
+
+        /// Writes a message on the server application's stdout or stderr.
+        /// @param message The message to write.
+        /// @param fd 1 for stdout, 2 for stderr.
+        void writeMessage(string message, int fd);
+    }
+}

data/dist/ice/slice/Ice/PropertiesAdmin.ice

@@ -0,0 +1,37 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["js:module:@zeroc/ice"]]
+
+#include "PropertyDict.ice"
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Provides remote access to the properties of a communicator.
+    interface PropertiesAdmin
+    {
+        /// Gets a property by key.
+        /// @param key The property key.
+        /// @return The property value. This value is empty if the property is not set.
+        string getProperty(string key);
+
+        /// Gets all properties whose keys begin with @p prefix. If @p prefix is the empty string then all properties
+        /// are returned.
+        /// @param prefix The prefix to search for. May be empty.
+        /// @return The matching property set.
+        ["java:type:java.util.TreeMap<String, String>"] PropertyDict getPropertiesForPrefix(string prefix);
+
+        /// Updates the communicator's properties with the given property set. If an entry in @p newProperties matches
+        /// the name of an existing property, that property's value is replaced with the new value. If the new value is
+        /// the empty string, the property is removed. Existing properties that are not modified or removed by the
+        /// entries in @p newProperties are not affected by this update.
+        /// @param newProperties Properties to add, change, or remove.
+        void setProperties(PropertyDict newProperties);
+    }
+}

data/dist/ice/slice/Ice/PropertyDict.ice

@@ -0,0 +1,23 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["cpp:no-default-include"]]
+[["cpp:include:Ice/Config.h"]]
+[["cpp:include:map"]]
+[["cpp:include:string"]]
+
+[["js:module:@zeroc/ice"]]
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// A simple collection of properties, represented as a dictionary of key/value pairs. Both key and value are
+    /// strings.
+    ["cpp:type:std::map<std::string, std::string, std::less<>>"]
+    dictionary<string, string> PropertyDict;
+}

data/dist/ice/slice/Ice/RemoteLogger.ice

@@ -0,0 +1,126 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["cpp:include:list"]]
+
+[["js:module:@zeroc/ice"]]
+
+#include "BuiltinSequences.ice"
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Represents the different types of log messages.
+    enum LogMessageType
+    {
+        /// The {@link RemoteLogger} received a print message.
+        ["swift:identifier:printMessage"]
+        PrintMessage,
+
+        /// The {@link RemoteLogger} received a trace message.
+        ["swift:identifier:traceMessage"]
+        TraceMessage,
+
+        /// The {@link RemoteLogger} received a warning message.
+        ["swift:identifier:warningMessage"]
+        WarningMessage,
+
+        /// The {@link RemoteLogger} received an error message.
+        ["swift:identifier:errorMessage"]
+        ErrorMessage
+    }
+
+    /// A sequence of {@link LogMessageType}.
+    sequence<LogMessageType> LogMessageTypeSeq;
+
+    /// Represents a full log message.
+    struct LogMessage
+    {
+        /// The type of message sent to the {@link RemoteLogger}.
+        LogMessageType type;
+
+        /// The date and time when the {@link RemoteLogger} received this message, expressed as the number of
+        /// microseconds since the Unix Epoch (00:00:00 UTC on 1 January 1970).
+        long timestamp;
+
+        /// For a message of type 'trace', the trace category of this log message; otherwise, the empty string.
+        string traceCategory;
+
+        /// The log message itself.
+        string message;
+    }
+
+    /// A sequence of {@link LogMessage}.
+    ["cpp:type:std::list<LogMessage>"]
+    sequence<LogMessage> LogMessageSeq;
+
+    /// Represents an Ice object that accepts log messages. It's called by the implementation of {@link LoggerAdmin}.
+    interface RemoteLogger
+    {
+        /// Attaches a remote logger to the local logger.
+        /// @param prefix The prefix of the associated local Logger.
+        /// @param logMessages Old log messages generated before "now".
+        ["swift:identifier:initialize"]
+        void init(string prefix, LogMessageSeq logMessages);
+
+        /// Logs a LogMessage.
+        /// @param message The message to log.
+        /// @remark {@link log} may be called by {@link LoggerAdmin} before {@link init}.
+        void log(LogMessage message);
+    }
+
+    /// Thrown when the provided {@link RemoteLogger} was previously attached to a {@link LoggerAdmin}.
+    exception RemoteLoggerAlreadyAttachedException
+    {
+    }
+
+    /// Represents the admin facet that allows an Ice application to attach its {@link RemoteLogger} to the local
+    /// logger of an Ice communicator.
+    interface LoggerAdmin
+    {
+        /// Attaches a {@link RemoteLogger} object to the local logger. This operation calls {@link RemoteLogger::init}
+        /// on @p prx.
+        /// @param prx A proxy to the remote logger.
+        /// @param messageTypes The list of message types that the remote logger wishes to receive. An empty list means
+        /// no filtering (send all message types).
+        /// @param traceCategories The categories of traces that the remote logger wishes to receive. This parameter is
+        /// ignored if @p messageTypes is not empty and does not include trace. An empty list means no filtering
+        /// (send all trace categories).
+        /// @param messageMax The maximum number of log messages (of all types) to be provided to
+        /// {@link RemoteLogger::init}. A negative value requests all messages available.
+        /// @throws RemoteLoggerAlreadyAttachedException Thrown if this remote logger is already attached to this admin
+        /// object.
+        void attachRemoteLogger(
+            RemoteLogger* prx,
+            LogMessageTypeSeq messageTypes,
+            StringSeq traceCategories,
+            int messageMax)
+            throws RemoteLoggerAlreadyAttachedException;
+
+        /// Detaches a {@link RemoteLogger} object from the local logger.
+        /// @param prx A proxy to the remote logger.
+        /// @return `true` if the provided remote logger proxy was detached, and `false` otherwise.
+        bool detachRemoteLogger(RemoteLogger* prx);
+
+        /// Retrieves recently logged log messages.
+        /// @param messageTypes The list of message types that the caller wishes to receive. An empty list means no
+        /// filtering (send all message types).
+        /// @param traceCategories The categories of traces that caller wish to receive. This parameter is ignored if
+        /// @p messageTypes is not empty and does not include trace. An empty list means no filtering (send all trace
+        /// categories).
+        /// @param messageMax The maximum number of log messages (of all types) to be returned. A negative value
+        /// requests all messages available.
+        /// @param prefix The prefix of the associated local logger.
+        /// @return The Log messages.
+        LogMessageSeq getLog(
+            LogMessageTypeSeq messageTypes,
+            StringSeq traceCategories,
+            int messageMax,
+            out string prefix);
+    }
+}

data/dist/ice/slice/Ice/ReplyStatus.ice

@@ -0,0 +1,65 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["cpp:no-default-include"]]
+[["cpp:include:Ice/Config.h"]]
+[["cpp:include:Ice/StreamHelpers.h"]]
+
+[["js:module:@zeroc/ice"]]
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Represents the status of a reply.
+    /// A reply status can have any value in the range 0..255. Do not use this enum to marshal or unmarshal a reply
+    /// status unless you know its value corresponds to one of the enumerators defined below.
+    enum ReplyStatus
+    {
+        /// The dispatch completed successfully.
+        ["swift:identifier:ok"]
+        Ok = 0,
+
+        /// The dispatch completed with a Slice user exception.
+        ["swift:identifier:userException"]
+        UserException,
+
+        /// The dispatch could not find an implementation for the target object.
+        ["swift:identifier:objectNotExist"]
+        ObjectNotExist,
+
+        /// The dispatch found an implementation for the target object but could not find the requested facet.
+        ["swift:identifier:facetNotExist"]
+        FacetNotExist,
+
+        /// The dispatch found an implementation for the target object but could not find the requested operation.
+        ["swift:identifier:operationNotExist"]
+        OperationNotExist,
+
+        /// The dispatch failed with an Ice local exception.
+        ["swift:identifier:unknownLocalException"]
+        UnknownLocalException,
+
+        /// The dispatch failed with a Slice user exception that does not conform to the exception specification of
+        /// the operation.
+        ["swift:identifier:unknownUserException"]
+        UnknownUserException,
+
+        /// The dispatch failed with some other exception (neither an Ice local exception nor a Slice user exception).
+        ["swift:identifier:unknownException"]
+        UnknownException,
+
+        /// The dispatch failed because the request payload could not be unmarshaled. It is typically due to a mismatch
+        /// in the Slice definitions used by the client and the server.
+        ["swift:identifier:invalidData"]
+        InvalidData,
+
+        /// The caller is not authorized to access the requested resource.
+        ["swift:identifier:unauthorized"]
+        Unauthorized,
+    }
+}

data/dist/ice/slice/Ice/Router.ice

@@ -0,0 +1,54 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["js:module:@zeroc/ice"]]
+
+#include "BuiltinSequences.ice"
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Represents an intermediary object that routes requests and replies between clients and Ice objects that are not
+    /// directly reachable from these clients.
+    interface Router
+    {
+        /// Gets the router's client proxy, i.e. the proxy to use for forwarding requests from the client to the
+        /// router. If a null proxy is returned, the client will forward requests to the router's endpoints.
+        /// @param hasRoutingTable Indicates whether or not the router supports a routing table. If `true`, the Ice
+        /// runtime will call {@link addProxies} to populate the routing table. The Ice runtime assumes the router has
+        /// a routing table when @p hasRoutingTable is not set.
+        /// @return The router's client proxy.
+        /// @remark Introduced in Ice 3.7.
+        ["cpp:const"]
+        idempotent Object* getClientProxy(out optional(1) bool hasRoutingTable);
+
+        /// Gets the router's server proxy, i.e. the proxy to use for forwarding requests from the server to the
+        /// router. The Ice runtime uses the endpoints of this proxy as the published endpoints of bi-dir object
+        /// adapters.
+        /// @return The router's server proxy.
+        ["cpp:const"]
+        idempotent Object* getServerProxy();
+
+        /// Adds new proxy information to the router's routing table.
+        /// @param proxies The proxies to add. Adding a null proxy is an error.
+        /// @return Proxies discarded by the router. These proxies are all non-null.
+        idempotent ObjectProxySeq addProxies(ObjectProxySeq proxies);
+    }
+
+    /// Provides access to a {@link Router} object via a fixed identity.
+    /// A RouterFinder is always registered with identity `Ice/RouterFinder`. This allows clients to obtain the
+    /// associated Router proxy with just the endpoint information of the object. For example, you can use the
+    /// RouterFinder proxy `Ice/RouterFinder:tcp -h somehost -p 4061` to get the Router proxy
+    /// `MyGlacier2/Router:tcp -h somehost -p 4061`.
+    interface RouterFinder
+    {
+        /// Gets a proxy to the associated {@link Router}. The proxy might point to several replicas.
+        /// @return The router proxy. This proxy is never null.
+        Router* getRouter();
+    }
+}

data/dist/ice/slice/Ice/SliceChecksumDict.ice

@@ -0,0 +1,18 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["js:module:@zeroc/ice"]]
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Mapping from type IDs to Slice checksums. This dictionary allows verification at runtime that a client and a
+    /// server use essentially the same Slice definitions.
+    ["deprecated:As of Ice 3.8, the Slice compilers no longer generate Slice checksums."]
+    dictionary<string, string> SliceChecksumDict;
+}

data/dist/ice/slice/Ice/Version.ice

@@ -0,0 +1,43 @@
+// Copyright (c) ZeroC, Inc.
+
+#pragma once
+
+[["cpp:dll-export:ICE_API"]]
+[["cpp:doxygen:include:Ice/Ice.h"]]
+[["cpp:header-ext:h"]]
+
+[["cpp:no-default-include"]]
+[["cpp:no-stream"]]
+[["cpp:include:Ice/Config.h"]]
+[["cpp:include:Ice/TupleCompare.h"]]
+[["cpp:include:cstdint"]]
+[["cpp:include:ostream"]]
+
+[["js:module:@zeroc/ice"]]
+
+["java:identifier:com.zeroc.Ice"]
+module Ice
+{
+    /// Represents a version of the Ice protocol. The only version implemented and supported by Ice is version 1.0.
+    ["cpp:custom-print"]
+    struct ProtocolVersion
+    {
+        /// The major version of the Ice protocol.
+        byte major;
+
+        /// The minor version of the Ice protocol.
+        byte minor;
+    }
+
+    /// Represents a version of the Slice encoding. Ice supports version 1.0 and 1.1 of this encoding.
+    /// @remark The Slice encoding is also known as the Ice encoding.
+    ["cpp:custom-print"]
+    struct EncodingVersion
+    {
+        /// The major version of the Slice encoding.
+        byte major;
+
+        /// The minor version of the Slice encoding.
+        byte minor;
+    }
+}