zeroc-ice 3.7.11__cp314-cp314-macosx_10_15_universal2.whl → 3.8.0__cp314-cp314-macosx_10_15_universal2.whl

slice/IceGrid/Registry.ice

@@ -1,269 +1,130 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #pragma once
 
 [["cpp:dll-export:ICEGRID_API"]]
 [["cpp:doxygen:include:IceGrid/IceGrid.h"]]
 [["cpp:header-ext:h"]]
-[["cpp:include:IceGrid/Config.h"]]
-
-[["ice-prefix"]]
-
-[["js:module:ice"]]
-[["js:cjs-module"]]
-
-[["objc:dll-export:ICEGRID_API"]]
-[["objc:header-dir:objc"]]
 
-[["python:pkgdir:IceGrid"]]
+[["cpp:include:IceGrid/Config.h"]]
 
-#include <IceGrid/Exception.ice>
-#include <IceGrid/Session.ice>
-#include <IceGrid/Admin.ice>
-#include <Ice/Locator.ice>
+[["js:module:@zeroc/ice"]]
 
-#ifndef __SLICE2JAVA_COMPAT__
-[["java:package:com.zeroc"]]
-#endif
+#include "Admin.ice"
+#include "Exception.ice"
+#include "Ice/Locator.ice"
+#include "Session.ice"
 
-["objc:prefix:ICEGRID"]
+/// Deploy and manage Ice servers.
+["java:identifier:com.zeroc.IceGrid"]
 module IceGrid
 {
-
-/**
- *
- * Determines which load sampling interval to use.
- *
- **/
-enum LoadSample
-{
-    /**
-     * Sample every minute.
-     **/
-    LoadSample1,
-
-    /**
-     * Sample every five minutes.
-     **/
-    LoadSample5,
-
-    /**
-     * Sample every fifteen minutes.
-     **/
-    LoadSample15
-}
-
-/**
- *
- * The IceGrid query interface. This interface is accessible to
- * Ice clients who wish to look up well-known objects.
- *
- **/
-interface Query
-{
-    /**
-     *
-     * Find a well-known object by identity.
-     *
-     * @param id The identity.
-     *
-     * @return The proxy or null if no such object has been found.
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent Object* findObjectById(Ice::Identity id);
-
-    /**
-     *
-     * Find a well-known object by type. If there are several objects
-     * registered for the given type, the object is randomly
-     * selected.
-     *
-     * @param type The object type.
-     *
-     * @return The proxy or null, if no such object has been found.
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent Object* findObjectByType(string type);
-
-    /**
-     *
-     * Find a well-known object by type on the least-loaded node. If
-     * the registry does not know which node hosts the object
-     * (for example, because the object was registered with a direct proxy), the
-     * registry assumes the object is hosted on a node that has a load
-     * average of 1.0.
-     *
-     * @param type The object type.
-     *
-     * @param sample The sampling interval.
-     *
-     * @return The proxy or null, if no such object has been found.
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent Object* findObjectByTypeOnLeastLoadedNode(string type, LoadSample sample);
-
-    /**
-     *
-     * Find all the well-known objects with the given type.
-     *
-     * @param type The object type.
-     *
-     * @return The proxies or an empty sequence, if no such objects
-     * have been found.
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent Ice::ObjectProxySeq findAllObjectsByType(string type);
-
-    /**
-     *
-     * Find all the object replicas associated with the given
-     * proxy. If the given proxy is not an indirect proxy from a
-     * replica group, an empty sequence is returned.
-     *
-     * @param proxy The object proxy.
-     *
-     * @return The proxies of each object replica or an empty sequence,
-     * if the given proxy is not from a replica group.
-     *
-     **/
-    ["cpp:const"] idempotent Ice::ObjectProxySeq findAllReplicas(Object* proxy);
-}
-
-/**
- *
- * The IceGrid registry allows clients create sessions
- * directly with the registry.
- *
- * @see Session
- * @see AdminSession
- *
- **/
-interface Registry
-{
-    /**
-     *
-     * Create a client session.
-     *
-     * @return A proxy for the newly created session.
-     *
-     * @param userId The user id.
-     *
-     * @param password The password for the given user id.
-     *
-     * @throws PermissionDeniedException Raised if the password for
-     * the given user id is not correct, or if the user is not allowed
-     * access.
-     *
-     **/
-    Session* createSession(string userId, string password)
-        throws PermissionDeniedException;
-
-    /**
-     *
-     * Create an administrative session.
-     *
-     * @return A proxy for the newly created session.
-     *
-     * @param userId The user id.
-     *
-     * @param password The password for the given user id.
-     *
-     * @throws PermissionDeniedException Raised if the password for
-     * the given user id is not correct, or if the user is not allowed
-     * access.
-     *
-     **/
-    AdminSession* createAdminSession(string userId, string password)
-        throws PermissionDeniedException;
-
-    /**
-     *
-     * Create a client session from a secure connection.
-     *
-     * @return A proxy for the newly created session.
-     *
-     * @throws PermissionDeniedException Raised if the password for
-     * the given user id is not correct, or if the user is not allowed
-     * access.
-     *
-     **/
-    Session* createSessionFromSecureConnection()
-        throws PermissionDeniedException;
-
-    /**
-     *
-     * Create an administrative session from a secure connection.
-     *
-     * @return A proxy for the newly created session.
-     *
-     * @throws PermissionDeniedException Raised if the password for
-     * the given user id is not correct, or if the user is not allowed
-     * access.
-     *
-     **/
-    AdminSession* createAdminSessionFromSecureConnection()
-        throws PermissionDeniedException;
-
-    /**
-     *
-     * Get the session timeout. If a client or administrative client
-     * doesn't call the session keepAlive method in the time interval
-     * defined by this timeout, IceGrid might reap the session.
-     *
-     * @see Session#keepAlive
-     * @see AdminSession#keepAlive
-     *
-     * @return The timeout (in seconds).
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent int getSessionTimeout();
-
-    /**
-     *
-     * Get the value of the ACM timeout. Clients supporting ACM
-     * connection heartbeats can enable them instead of explicitly
-     * sending keep alives requests.
-     *
-     * NOTE: This method is only available since Ice 3.6.
-     *
-     * @return The timeout (in seconds).
-     *
-     **/
-    ["nonmutating", "cpp:const"] idempotent int getACMTimeout();
-}
-
-/**
- *
- * The IceGrid locator interface provides access to the {@link Query}
- * and {@link Registry} object of the IceGrid registry.
- *
- * @see Query
- * @see Registry
- *
- **/
-interface Locator extends Ice::Locator
-{
-    /**
-     *
-     * Get the proxy of the registry object hosted by this IceGrid
-     * registry.
-     *
-     * @return The proxy of the registry object.
-     *
-     **/
-    ["cpp:const"] idempotent Registry* getLocalRegistry();
-
-    /**
-     *
-     * Get the proxy of the query object hosted by this IceGrid
-     * registry.
-     *
-     * @return The proxy of the query object.
-     *
-     **/
-    ["cpp:const"] idempotent Query* getLocalQuery();
-}
-
+    /// Determines which load sampling interval to use.
+    enum LoadSample
+    {
+        /// Sample every minute.
+        ["swift:identifier:loadSample1"]
+        LoadSample1,
+
+        /// Sample every five minutes.
+        ["swift:identifier:loadSample5"]
+        LoadSample5,
+
+        /// Sample every fifteen minutes.
+        ["swift:identifier:loadSample15"]
+        LoadSample15
+    }
+
+    /// Finds well-known Ice objects registered with the IceGrid registry.
+    interface Query
+    {
+        /// Finds a well-known object by identity.
+        /// @param id The identity.
+        /// @return A proxy to the well-known object, or null if no such object is registered.
+        ["cpp:const"]
+        idempotent Object* findObjectById(Ice::Identity id);
+
+        /// Finds a well-known object by type. If there are several objects registered for the given type, the object is
+        /// randomly selected.
+        /// @param type The object type.
+        /// @return A proxy to a well-known object with the specified type, or null if no such object is registered.
+        ["cpp:const"]
+        idempotent Object* findObjectByType(string type);
+
+        /// Finds a well-known object by type on the least-loaded node. If the registry does not know which node hosts
+        /// the object (for example, because the object was registered with a direct proxy), the registry assumes the
+        /// object is hosted on a node that has a load average of 1.0.
+        /// @param type The object type.
+        /// @param sample The sampling interval.
+        /// @return A proxy to the well-known object, or null if no such object is registered.
+        ["cpp:const"]
+        idempotent Object* findObjectByTypeOnLeastLoadedNode(string type, LoadSample sample);
+
+        /// Finds all the well-known objects with the given type.
+        /// @param type The object type.
+        /// @return A list of proxies to the well-known objects with the specified type. Can be empty.
+        ["cpp:const"]
+        idempotent Ice::ObjectProxySeq findAllObjectsByType(string type);
+
+        /// Finds all the replicas of a well-known object.
+        /// @param proxy A proxy that identifies the well-known object.
+        /// @return A list of proxies to the replicas of the well-known object specified by @p proxy. Can be empty.
+        ["cpp:const"]
+        idempotent Ice::ObjectProxySeq findAllReplicas(Object* proxy);
+    }
+
+    /// Represents the main entry point into the IceGrid registry service. It provides operations to create sessions
+    /// with the registry.
+    interface Registry
+    {
+        /// Creates a client session.
+        /// @param userId The user ID.
+        /// @param password The password for the given user.
+        /// @return A proxy to the newly created session. This proxy is never null.
+        /// @throws PermissionDeniedException Thrown when authentication or authorization fails.
+        Session* createSession(string userId, string password)
+            throws PermissionDeniedException;
+
+        /// Creates an administrative session.
+        /// @param userId The user ID.
+        /// @param password The password for the given user.
+        /// @return A proxy to the newly created session. This proxy is never null.
+        /// @throws PermissionDeniedException Thrown when authentication or authorization fails.
+        AdminSession* createAdminSession(string userId, string password)
+            throws PermissionDeniedException;
+
+        /// Creates a client session from a secure connection.
+        /// @return A proxy to the newly created session. This proxy is never null.
+        /// @throws PermissionDeniedException Thrown when authentication or authorization fails.
+        Session* createSessionFromSecureConnection()
+            throws PermissionDeniedException;
+
+        /// Creates an administrative session from a secure connection.
+        /// @return A proxy to the newly created session. This proxy is never null.
+        /// @throws PermissionDeniedException Thrown when authentication or authorization fails.
+        AdminSession* createAdminSessionFromSecureConnection()
+            throws PermissionDeniedException;
+
+        /// Gets the session timeout. An Ice 3.7 or earlier client can use this value to determine how often it needs to
+        /// send heartbeats (using ACM) or call {@link Session#keepAlive} (resp. {@link AdminSession#keepAlive}) to keep
+        /// a session alive in the IceGrid registry.
+        /// @return The session timeout (in seconds).
+        ["cpp:const"]
+        ["deprecated"]
+        idempotent int getSessionTimeout();
+    }
+
+    /// Provides access to the {@link Query} and {@link Registry} objects implemented by the IceGrid registry.
+    interface Locator extends Ice::Locator
+    {
+        /// Gets a proxy to the registry object hosted by this IceGrid registry.
+        /// @return A proxy to the registry object. This proxy is never null.
+        ["cpp:const"]
+        idempotent Registry* getLocalRegistry();
+
+        /// Gets a proxy to the query object hosted by this IceGrid registry.
+        /// @return A proxy to the query object. This proxy is never null.
+        ["cpp:const"]
+        idempotent Query* getLocalQuery();
+    }
 }

slice/IceGrid/Session.ice

@@ -1,128 +1,64 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #pragma once
 
 [["cpp:dll-export:ICEGRID_API"]]
 [["cpp:doxygen:include:IceGrid/IceGrid.h"]]
 [["cpp:header-ext:h"]]
-[["cpp:include:IceGrid/Config.h"]]
-
-[["ice-prefix"]]
-
-[["js:module:ice"]]
-[["js:cjs-module"]]
-
-[["objc:dll-export:ICEGRID_API"]]
-[["objc:header-dir:objc"]]
 
-[["python:pkgdir:IceGrid"]]
+[["cpp:include:IceGrid/Config.h"]]
 
-#include <Glacier2/Session.ice>
-#include <IceGrid/Exception.ice>
+[["js:module:@zeroc/ice"]]
 
-#ifndef __SLICE2JAVA_COMPAT__
-[["java:package:com.zeroc"]]
-#endif
+#include "Exception.ice"
+#include "Glacier2/Session.ice"
 
-["objc:prefix:ICEGRID"]
+["java:identifier:com.zeroc.IceGrid"]
 module IceGrid
 {
+    interface Registry; // For doc-comments.
 
-/**
- *
- * A session object is used by IceGrid clients to allocate and
- * release objects. Client sessions are created either via the
- * {@link Registry} object or via the registry client <code>SessionManager</code>
- * object.
- *
- * @see Registry
- *
- **/
-interface Session extends Glacier2::Session
-{
-    /**
-     *
-     * Keep the session alive. Clients should call this operation
-     * regularly to prevent the server from reaping the session.
-     *
-     * @see Registry#getSessionTimeout
-     *
-     **/
-    idempotent void keepAlive();
-
-    /**
-     *
-     * Allocate an object. Depending on the allocation timeout, this
-     * operation might hang until the object is available or until the
-     * timeout is reached.
-     *
-     * @param id The identity of the object to allocate.
-     *
-     * @return The proxy of the allocated object.
-     *
-     * @throws ObjectNotRegisteredException Raised if the object with
-     * the given identity is not registered with the registry.
-     *
-     * @throws AllocationException Raised if the object can't be
-     * allocated.
-     *
-     * @see #setAllocationTimeout
-     * @see #releaseObject
-     *
-     **/
-    ["amd"] Object* allocateObjectById(Ice::Identity id)
-        throws ObjectNotRegisteredException, AllocationException;
+    /// Represents a session object used by IceGrid clients to allocate and release objects. Client sessions are created
+    /// either via the {@link Registry} object or via the registry client {@link Glacier2::SessionManager} object.
+    interface Session extends Glacier2::Session
+    {
+        /// Keeps the session alive.
+        ["deprecated:As of Ice 3.8, there is no need to call this operation, and its implementation does nothing."]
+        idempotent void keepAlive();
 
-    /**
-     *
-     * Allocate an object with the given type. Depending on the
-     * allocation timeout, this operation can block until an object
-     * becomes available or until the timeout is reached.
-     *
-     * @param type The type of the object.
-     *
-     * @return The proxy of the allocated object.
-     *
-     * @throws AllocationException Raised if the object could not be allocated.
-     *
-     * @see #setAllocationTimeout
-     * @see #releaseObject
-     *
-     **/
-    ["amd"] Object* allocateObjectByType(string type)
-        throws AllocationException;
+        /// Allocates an object.
+        /// @param id The identity of the object to allocate.
+        /// @return A proxy to the allocated object. This proxy is never null.
+        /// @throws ObjectNotRegisteredException Thrown when an object with the given identity is not registered with
+        /// the registry.
+        /// @throws AllocationException Thrown when the allocation fails.
+        /// @see #setAllocationTimeout
+        /// @see #releaseObject
+        Object* allocateObjectById(Ice::Identity id)
+            throws ObjectNotRegisteredException, AllocationException;
 
-    /**
-     *
-     * Release an object that was allocated using <code>allocateObjectById</code> or
-     * <code>allocateObjectByType</code>.
-     *
-     * @param id The identity of the object to release.
-     *
-     * @throws ObjectNotRegisteredException Raised if the object with
-     * the given identity is not registered with the registry.
-     *
-     * @throws AllocationException Raised if the given object can't be
-     * released. This might happen if the object isn't allocatable or
-     * isn't allocated by the session.
-     *
-     **/
-    void releaseObject(Ice::Identity id)
-        throws ObjectNotRegisteredException, AllocationException;
+        /// Allocates an object with the given type.
+        /// @param type The type of the object.
+        /// @return A proxy to the allocated object. This proxy is never null.
+        /// @throws AllocationException Thrown when the allocation fails.
+        /// @see #setAllocationTimeout
+        /// @see #releaseObject
+        Object* allocateObjectByType(string type)
+            throws AllocationException;
 
-    /**
-     *
-     * Set the allocation timeout. If no objects are available for an
-     * allocation request, a call to <code>allocateObjectById</code> or
-     * <code>allocateObjectByType</code> will block for the duration of this
-     * timeout.
-     *
-     * @param timeout The timeout in milliseconds.
-     *
-     **/
-    idempotent void setAllocationTimeout(int timeout);
-}
+        /// Releases an object that was allocated using {@link allocateObjectById} or {@link allocateObjectByType}.
+        /// @param id The identity of the object to release.
+        /// @throws ObjectNotRegisteredException Thrown when an object with the given identity is not registered with
+        /// the registry.
+        /// @throws AllocationException Thrown when the object can't be released. This can happen when the object is not
+        /// allocatable or is not allocated by this session.
+        void releaseObject(Ice::Identity id)
+            throws ObjectNotRegisteredException, AllocationException;
 
+        /// Sets the allocation timeout. When no object is immediately available for an allocation request, the
+        /// implementation of {@link allocateObjectById} and {@link allocateObjectByType} waits for the duration of
+        /// this @p timeout.
+        /// @param timeout The timeout in milliseconds.
+        idempotent void setAllocationTimeout(int timeout);
+    }
 }

slice/IceGrid/UserAccountMapper.ice

@@ -1,69 +1,34 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #pragma once
 
 [["cpp:dll-export:ICEGRID_API"]]
 [["cpp:doxygen:include:IceGrid/IceGrid.h"]]
 [["cpp:header-ext:h"]]
-[["cpp:include:IceGrid/Config.h"]]
-
-[["ice-prefix"]]
-
-[["js:module:ice"]]
-[["js:cjs-module"]]
 
-[["objc:dll-export:ICEGRID_API"]]
-[["objc:header-dir:objc"]]
-
-[["python:pkgdir:IceGrid"]]
+[["cpp:include:IceGrid/Config.h"]]
 
-#ifndef __SLICE2JAVA_COMPAT__
-[["java:package:com.zeroc"]]
-#endif
+[["js:module:@zeroc/ice"]]
 
-["objc:prefix:ICEGRID"]
+["java:identifier:com.zeroc.IceGrid"]
 module IceGrid
 {
-
-/**
- *
- * This exception is raised if a user account for a given session
- * identifier can't be found.
- *
- **/
-exception UserAccountNotFoundException
-{
-}
-
-/**
- *
- * A user account mapper object is used by IceGrid nodes to map
- * session identifiers to user accounts.
- *
- **/
-interface UserAccountMapper
-{
-    /**
-     *
-     * Get the name of the user account for the given user. This is
-     * used by IceGrid nodes to figure out the user account to use
-     * to run servers.
-     *
-     * @param user The value of the server descriptor's <code>user</code>
-     * attribute. If this attribute is not defined, and the server's
-     * activation mode is <code>session</code>, the default value of
-     * <code>user</code> is the session identifier.
-     *
-     * @return The user account name.
-     *
-     * @throws UserAccountNotFoundException Raised if no user account
-     * is found for the given user.
-     *
-     **/
-    string getUserAccount(string user)
-        throws UserAccountNotFoundException;
-}
-
+    /// The exception that is thrown when a user account for a given session identifier can't be found.
+    exception UserAccountNotFoundException
+    {
+    }
+
+    /// Maps user strings in server descriptors to actual user account names. You can configure the user account mapper
+    /// of an IceGrid node with the property `IceGrid.Node.UserAccountMapper`.
+    interface UserAccountMapper
+    {
+        /// Gets the name of the user account for the given user. This is used by IceGrid nodes to figure out the user
+        /// account to use to run servers.
+        /// @param user The value of the server descriptor's `user` attribute. When this attribute is not defined, and
+        /// the server's activation mode is `session`, the default value for `user` is the session identifier.
+        /// @return The user account name.
+        /// @throws UserAccountNotFoundException Thrown when no user account is found for the given user.
+        string getUserAccount(string user)
+            throws UserAccountNotFoundException;
+    }
 }