Interfaces
8 min read
9 min read
9 min read
9 min read
6 min read
5 min read
9 min read
6 min read
9 min read
Syntax and Semantics of Interfaces
A Slice interface defines the operations that clients invoke on an Ice object. For example:
module M{ struct TimeOfDay { short hour; // 0 - 23 short minute; // 0 - 59 short second; // 0 - 59 }
interface Clock { TimeOfDay getTime(); void setTime(TimeOfDay time); }}Clock defines two operations: getTime returns the current time, and setTime sets it. A client calls these operations on a proxy for an Ice object that implements Clock.
An interface contains only operations: you cannot define a type, an exception, or a field inside an interface.
An interface can be empty:
interface Empty {}Client-Side Mapping for Interfaces
Proxy Classes
On the client side, a Slice interface maps to a C++ proxy class with member functions that correspond to the operations on that interface. Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Slice compiler generates the following definitions for use by the client:
class SimplePrx : public Ice::Proxy<SimplePrx, Ice::ObjectPrx>{public: // Constructors SimplePrx( const Ice::CommunicatorPtr& communicator, std::string_view proxyString); SimplePrx(const SimplePrx& other) noexcept; SimplePrx(SimplePrx&& other) noexcept;
// Assignment operators. SimplePrx& operator=(const SimplePrx& rhs) noexcept; SimplePrx& operator=(SimplePrx&& rhs) noexcept;
// Member functions mapped from Slice operation op.
void op(const Ice::Context& = Ice::noExplicitContext) const;
[[nodiscard]] std::future<void> opAsync( const Ice::Context& context = Ice::noExplicitContext) const;
std::function<void()> opAsync( std::function<void()> response, std::function<void(std::exception_ptr)> exception = nullptr, std::function<void(bool)> sent = nullptr, const Ice::Context& context = Ice::noExplicitContext) const;};Your client code interacts directly with the proxy class, M::SimplePrx in the example above. More generally, the generated proxy class for an interface in module M is the C++ proxy class M::<interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
Use the constructor of the generated class to create a proxy from a communicator and a “stringified” proxy. For example:
M::SimplePrx simple{communicator, "simple:tcp -h localhost -p 4061"};A proxy is a C++ value type.
The proxy’s constructor does not allow you to create a “null” proxy. A nullable proxy - and by extension a null proxy - is a proxy held in a std::optional. For example:
// A nullable Simple proxy, default-initialized to std::nullopt.std::optional<M::SimplePrx> simple;Inheritance from Ice::ObjectPrx
Ice::ObjectPrxAll generated proxy classes inherit indirectly from the Ice::ObjectPrx class, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated C++ classes. For example:
module M{ interface A { ... } interface B { ... } interface C extends A, B { ... }}The generated code for CPrx reflects the inheritance hierarchy:
namespace M{ class CPrx : public Ice::Proxy<CPrx, APrx, BPrx> { ... };}Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Proxy Factory Methods
A proxy provides a variety of methods for customizing it. Since proxies are immutable, each of these "factory methods" returns a copy of the original proxy that contains the desired modification. The factory methods return the proxy's own type: calling ice_invocationTimeout on a GreeterPrx returns a GreeterPrx. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};
// Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000);The factory methods ice_facet and ice_identity are the exceptions. The new facet or identity can designate an object of an unrelated type, so these two functions return an Ice::ObjectPrx unless you supply the desired proxy type as a template argument. For example:
GreeterPrx greeter{communicator, "greeter:tcp -h localhost -p 4061"};GreeterAdminPrx greeterAdmin = greeter.ice_facet<GreeterAdminPrx>("admin");Server-Side Mapping for Interfaces
Skeleton Classes
On the server side, interfaces map to skeleton classes. A skeleton is a class that has a pure virtual member function for each operation on the corresponding interface. For example, consider our Slice definition for the Greeter interface:
module VisitorCenter{ interface Greeter { string greet(string name); }}The Slice compiler generates the following classes for this interface:
namespace VisitorCenter{ class Greeter : public virtual Ice::Object { public: void dispatch( Ice::IncomingRequest& request, std::function<void(Ice::OutgoingResponse)> sendResponse) override;
virtual std::string greet(std::string name, const Ice::Current&) = 0;
// ... };
class AsyncGreeter : public virtual Ice::Object { public: void dispatch( Ice::IncomingRequest& request, std::function<void(Ice::OutgoingResponse)> sendResponse) override;
virtual void greetAsync( std::string name, std::function<void(std::string_view returnValue)> response, std::function<void(std::exception_ptr)> exception, const Ice::Current&) = 0; // ... }; // ...}The important points to note are:
- As for the client side, Slice modules are mapped to C++ namespaces with the same name, so the skeleton class definition is nested in the namespace
VisitorCenter. - The Slice compiler generates two skeleton classes: the default skeleton class has the same name as the Slice interface (
Greeterwith our example), and the async skeleton class gets an additional Async prefix (AsyncGreeter). - Each skeleton class contains a pure virtual member function for each operation in the Slice interface.
- Each skeleton class is an abstract base class because its member functions are pure virtual.
- Each skeleton class inherits from
Ice::Object(which forms the root of the Ice servant hierarchy). - Each skeleton class reimplements (overrides) the
dispatchfunction defined onIce::Object.
Ice::Object Servant Base Class
Ice::Object Servant Base ClassThe Slice pseudo-interface Object is mapped to the Ice::Object class in C++:
namespace Ice{ class Object { public: /// Dispatches an incoming request and returns the corresponding outgoing /// response. virtual void dispatch( IncomingRequest& request, std::function<void(OutgoingResponse)> sendResponse); // ... };}Object implements dispatch for the 4 operations on the Slice pseudo-interface Object: ice_ping, ice_isA, ice_id and ice_ids.
Servant Classes
In order to provide an implementation for an Ice object, you must create a servant class that inherits from one of the generated skeleton classes. For example, to create a servant for the Greeter interface, you could write:
#include "Greeter.h" // Slice-generated header
class Chatbot : public VisitorCenter::Greeter{public: std::string greet(std::string name, const Ice::Current&) override;};Note that Chatbot derives from VisitorCenter::Greeter, one of the two generated skeleton classes.
As far as Ice is concerned, the Chatbot class must implement only a single member function: the pure virtual greet function that it inherits from its skeleton. This makes the servant class a concrete class that you can instantiate. You can add other member functions and data members as you see fit to support your implementation.
The async skeleton class is described in Asynchronous Method Dispatch (AMD) in C++.
Client-Side Mapping for Interfaces
Proxy Interfaces
On the client side, a Slice interface maps to a C# interface with methods that correspond to the operations on that interface. Consider the following Slice interface:
module M{ interface Simple { ["cs:identifier:Op"] void op(); }}The Slice compiler generates the following definition for use by the client:
public partial interface SimplePrx : Ice.ObjectPrx{ Task OpAsync( Dictionary<string, string>? context = null, IProgress<bool>? progress = null, CancellationToken cancel = default);
// Synchronous method provided for backwards compatibility. void Op(Dictionary<string, string>? context = null);}As you can see, the compiler generates a proxy interfaceSimplePrx. In general, the generated name is <interface-name>Prx. If an interface is nested in a module M, the generated interface is part of namespace M, so the fully-qualified name is M.<interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
For each Slice interface, apart from the proxy interface, the Slice-to-C# compiler generates a helper class: for an interface Simple, the name of the generated helper class is SimplePrxHelper.
This helper class provides the createProxy method. With our previous example:
public class SimplePrxHelper : ...{ public static SimplePrx createProxy( Ice.Communicator communicator, string proxyString) { ... }}Use createProxy to create a proxy from a communicator and a “stringified” proxy:
SimplePrx simple = SimplePrxHelper.createProxy( communicator, "simple:tcp -h localhost -p 4061");Inheritance from Ice.ObjectPrx
Ice.ObjectPrxAll generated proxy interfaces inherit directly or indirectly from the Ice.ObjectPrx interface, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated C# interfaces. For example:
module M{ interface A { ... } interface B { ... } interface C extends A, B { ... }}The generated code for CPrx reflects the inheritance hierarchy:
namespace M;
public interface CPrx : APrx, BPrx{...}Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
In addition to createProxy, the generated helper class provides two static methods for converting a proxy into a proxy of another type:
public class SimplePrxHelper : ...{ public static SimplePrx? uncheckedCast(Ice.ObjectPrx? proxy) { ... }
public static async Task<SimplePrx?> checkedCastAsync( Ice.ObjectPrx proxy, Dictionary<string, string>? context = null, IProgress<bool>? progress = null, CancellationToken cancel = default) { ... }}uncheckedCast
The helper’s uncheckedCast static method allows you to convert any proxy into the helper’s proxy type. For example:
// Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.WidgetPrx widget = WidgetPrxHelper.uncheckedCast(simple);uncheckedCast is a local operation that always succeeds.
checkedCastAsync
checkedCastAsync makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
// Call operation ice_isA on the Ice object to check if it implements Slice interface// Widget.WidgetPrx? widget = await WidgetPrxHelper.checkedCastAsync(simple);If the target object implements the Slice interface, checkedCastAsync returns a non-null proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCastAsync returns null. checkedCastAsync can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCastAsync when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy interface ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
GreeterPrx greeter = GreeterPrxHelper.createProxy(...);
// Create a new GreeterPrx and assign it to greeter.greeter = GreeterPrxHelper.uncheckedCast(greeter.ice_invocationTimeout(10000));ice_invocationTimeout and other factory methods in C# return an Ice.ObjectPrx. You need to convert this proxy into a proxy of the correct type, as shown above.
Server-Side Mapping for Interfaces
Skeleton Classes
On the server side, interfaces map to skeleton classes. A skeleton is a class that has an abstract method for each operation on the corresponding interface. For example, consider our Slice definition for the Greeter interface:
module VisitorCenter{ interface Greeter { ["cs:identifier:Greet"] string greet(string name); }}The Slice compiler generates the following definitions for this interface:
namespace VisitorCenter{ public partial interface Greeter : Ice.Object { string Greet(string name, Ice.Current current); }
public abstract partial class GreeterDisp_ : Greeter { public abstract string Greet(string name, Ice.Current current);
public ValueTask<Ice.OutgoingResponse> dispatchAsync( Ice.IncomingRequest request) { ... } }
public partial interface AsyncGreeter : Ice.Object { Task<string> GreetAsync(string name, Ice.Current current); }
public abstract partial class AsyncGreeterDisp_ : AsyncGreeter { public abstract Task<string> GreetAsync(string name, Ice.Current current);
public ValueTask<Ice.OutgoingResponse> dispatchAsync( Ice.IncomingRequest request) { ... } }}The important points to note here are:
- As for the client side, Slice modules are mapped to C# namespaces with the same name, so the skeleton class definitions are part of the
VisitorCenternamespace. - For each Slice interface, the compiler generates two C# interfaces and two C# classes - the skeleton interfaces and classes.
- Each skeleton class contains an abstract method for each operation in the Slice interface.
- Each skeleton class implements the
dispatchAsyncmethod provided byIce.Object: it dispatches incoming requests to the methods on the skeleton class based on the operation name received in the request.
Ice.Object Servant Base Interface
Ice.Object Servant Base InterfaceThe Slice pseudo-interface Object is mapped to the Ice.Object interface in C#:
namespace Ice{ public interface Object { public ValueTask<OutgoingResponse> dispatchAsync(IncomingRequest request) { ... } ... }}Ice.Object provides a default dispatchAsync implementation for the 4 operations on the Slice pseudo-interface Object: ice_ping, ice_isA, ice_id and ice_ids.
Servant Classes
In order to provide an implementation for an Ice object, you must create a servant class that inherits from one of the generated skeleton classes. For example, to create a servant for the Greeter interface, you could write:
public class Chatbot : VisitorCenter.GreeterDisp_{ public override string Greet(string name, Ice.Current current) => $"Hello, {name}!";}Note that Chatbot inherits from VisitorCenter.GreeterDisp_, one of the two skeleton classes.
As far as Ice is concerned, the Chatbot class must implement only a single method: the abstract method Greet that it inherits from the skeleton class. This makes the servant class a concrete class that you can instantiate. You can add other methods and fields as you see fit to support your implementation.
The async skeleton class is described in Asynchronous Method Dispatch (AMD) in C#.
Client-Side Mapping for Interfaces
Proxy Interfaces
On the client side, a Slice interface maps to a Java interface with methods that correspond to the operations on that interface. Consider the following Slice interface:
interface Simple{ void op();}The Slice compiler generates the following definition for use by the client:
public interface SimplePrx extends com.zeroc.Ice.ObjectPrx { void op(); void op(java.util.Map<String, String> context);
java.util.concurrent.CompletableFuture<Void> opAsync();
java.util.concurrent.CompletableFuture<Void> opAsync( java.util.Map<String, String> context);}As you can see, the compiler generates a proxy interface SimplePrx. In general, the generated name is <interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
The generated proxy interface provides a static createProxy method. With our previous example:
public interface SimplePrx extends com.zeroc.Ice.ObjectPrx { static SimplePrx createProxy( com.zeroc.Ice.Communicator communicator, String proxyString) { ... } ...}Use createProxy to create a proxy from a communicator and a “stringified” proxy:
SimplePrx simple = SimplePrx.createProxy( communicator, "simple:tcp -h localhost -p 4061");Inheritance from com.zeroc.Ice.ObjectPrx
com.zeroc.Ice.ObjectPrxAll generated proxy interfaces inherit directly or indirectly from the com.zeroc.Ice.ObjectPrx interface, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated Java interfaces. For example:
interface A { ... }interface B { ... }interface C extends A, B { ... }The generated code for CPrx reflects the inheritance hierarchy:
public interface CPrx extends APrx, BPrx { ...}Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
In addition to createProxy, the generated proxy interface provides two static methods for converting a proxy into a proxy of another type:
public interface SimplePrx extends com.zeroc.Ice.ObjectPrx { static SimplePrx uncheckedCast(com.zeroc.Ice.ObjectPrx obj) { ... }
static SimplePrx checkedCast(com.zeroc.Ice.ObjectPrx obj) { ... }}uncheckedCast
The static uncheckedCast method allows you to convert any proxy into a proxy of this type. For example:
// Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.WidgetPrx widget = WidgetPrx.uncheckedCast(simple);uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
// Call operation ice_isA on the Ice object to check if it implements Slice interface// Widget.WidgetPrx widget = WidgetPrx.checkedCast(simple);If the target object implements the Slice interface, checkedCast returns a non-null proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns null. checkedCast can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy interface ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
GreeterPrx greeter = GreeterPrx.createProxy(...);
// Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000);The factory methods usually return a proxy of the same type as the current proxy, as in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
GreeterPrx greeter = GreeterPrx.createProxy(...);GreeterAdminPrx greeterAdmin = GreeterAdminPrx.uncheckedCast( greeter.ice_facet("admin"));Server-Side Mapping for Interfaces
Skeleton Interfaces
On the server side, interfaces map to skeleton interfaces. A skeleton is an interface that defines a method for each operation on the corresponding Slice interface. For example, consider our Slice definition for the Greeter interface:
module VisitorCenter{ interface Greeter { string greet(string name); }}The Slice compiler generates the following definition for this interface:
package VisitorCenter;
public interface Greeter extends com.zeroc.Ice.Object { String greet(String name, com.zeroc.Ice.Current current);
@Override default CompletionStage<com.zeroc.Ice.OutgoingResponse> dispatch( com.zeroc.Ice.IncomingRequest request) throws com.zeroc.Ice.UserException { ... }}
public interface AsyncGreeter extends com.zeroc.Ice.Object { CompletionStage<String> greetAsync( String name, com.zeroc.Ice.Current current);
@Override default CompletionStage<com.zeroc.Ice.OutgoingResponse> dispatch( com.zeroc.Ice.IncomingRequest request) throws com.zeroc.Ice.UserException { ... }}The important points to note here are:
As for the client side, Slice modules are mapped to Java packages with the same name, so the generated skeleton interface is part of the
VisitorCenterpackage unless you remap it with thejava:identifiermetadata directive.For each Slice interface
<interface-name>, the compiler generates two Java interfaces that extendcom.zeroc.Ice.Object(the skeleton interfaces).Each skeleton interface contains an abstract method for each operation in the Slice interface.
Each skeleton interface reimplements (overrides) the
dispatchmethod provided bycom.zeroc.Ice.Object: it dispatches incoming requests to the methods on the skeleton based on the operation name received in the request.
Object Servant Base Interface
Object Servant Base InterfaceThe Slice pseudo-interface Object is mapped to the com.zeroc.Ice.Object interface in Java:
package com.zeroc.Ice;
public interface Object { default CompletionStage<OutgoingResponse> dispatch(IncomingRequest request) throws UserException { ... }}com.zeroc.Ice.Object provides a default dispatch implementation for the 4 operations on the Slice pseudo-interface Object: ice_ping, ice_isA, ice_id and ice_ids.
Servant Classes
In order to provide an implementation for an Ice object, you must create a servant class that implements one of the generated skeleton interfaces. For example, to create a servant for the Greeter interface, you could write:
class Chatbot implements Greeter { @Override public String greet(String name, com.zeroc.Ice.Current current) { return "Hello, " + name + "!"; }}Note that Chatbot implements VisitorCenter.Greeter, one of the two skeleton interfaces.
As far as Ice is concerned, the Chatbot class must implement only a single method: the abstract method greet. This makes the servant class a concrete class that you can instantiate. You can add other methods and fields as you see fit to support your implementation.
The async skeleton interface is described in Asynchronous Method Dispatch (AMD) in Java.
Client-Side Mapping for Interfaces
Proxy Classes
On the client side, a Slice interface maps to a JavaScript class with methods that correspond to the operations on that interface. Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Slice compiler generates code like:
class SimplePrx extends Ice.ObjectPrx { op(context) { ... }}export namespace M { export class SimplePrx extends Ice.ObjectPrx { op(context?: Map<string, string>): Ice.AsyncResult<void>; }}As you can see, the compiler generates a proxy type SimplePrx. In general, the generated name is <interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
Use the constructor of the generated class to create a proxy from a communicator and a “stringified” proxy. For example:
const simple = new M.SimplePrx( communicator, "simple:tcp -h localhost -p 4061");Inheritance from Ice.ObjectPrx
Ice.ObjectPrxAll generated proxy classes inherit directly from the Ice.ObjectPrx class, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Slice interface inheritance is preserved in the generated TypeScript declarations, but not in the emitted JavaScript at runtime.
interface A { ... }interface B { ... }interface C extends A, B { ... }The generated proxy class looks like:
M.CPrx = class extends Ice.ObjectPrx { // ...};At runtime, the operations from APrx and BPrx are copied onto CPrx.prototype (no JavaScript class inheritance chain is used). This has two important consequences:
- You can call any operation from Slice interface
AorBon aCPrxinstance, because those methods are present onCPrx.prototype. - However, c instanceof M.APrx (or M.BPrx) is false, since CPrx does not inherit from
APrxorBPrxin JavaScript.
You can still pass a CPrx wherever an APrx or BPrx is expected—TypeScript’s generated declarations model this with implements, so the type checker accepts such usages even though the JavaScript runtime does not establish an inheritance relationship between the proxy classes.
export class CPrx extends Ice.ObjectPrx implements M.APrx, M.BPrx { // ...}Creating a Proxy of Another Type
The generated proxy class provides two static methods for converting a proxy into a proxy of another type:
export class SimplePrx extends Ice.ObjectPrx { static uncheckedCast(prx: Ice.ObjectPrx, facet?: string): SimplePrx;
static checkedCast( prx: Ice.ObjectPrx, facet?: string, context?: Map<string, string>): Promise<SimplePrx | null>;}uncheckedCast
The uncheckedCast static method allows you to convert any proxy into a proxy of this type. For example:
// Convert a SimplePrx into a WidgetPrx, even though the two types are// unrelated.const widget = M.WidgetPrx.uncheckedCast(simple);uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
// Call operation ice_isA on the Ice object to check if it implements// Slice interface Widget.const widget = await M.WidgetPrx.checkedCast(simple);If the target object implements the Slice interface, checkedCast returns a new proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns null. checkedCast can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy class ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
import { VisitorCenter } from "./Greeter.js"let greeter = new VisitorCenter.GreeterPrx( communicator, "greeter:tcp -h localhost -p 4061");greeter = greeter.ice_invocationTimeout(10000);The factory methods usually return a proxy of the same type as the current proxy, as in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
import { VisitorCenter } from "./Greeter.js"
const greeter = new VisitorCenter.GreeterPrx( communicator, "greeter:tcp -h localhost -p 4061");const greeterAdmin = VisitorCenter.GreeterAdminPrx.uncheckedCast( greeter.ice_facet("admin"));Server-Side Mapping for Interfaces
Skeleton Classes
On the server side, interfaces map to skeleton classes. A skeleton is a type that conceptually has an abstract method for each operation on the corresponding interface. For example, consider our Slice definition for the Node interface:
module Filesystem{ interface Node { idempotent string name(); } // ...}The Slice compiler generates the following definition for this interface:
class Node extends Ice.Object { // ...}abstract class Node extends Ice.Object { abstract name(current: Ice.Current): PromiseLike<string> | string;}The important points to note here are:
As for the client side, Slice modules are mapped to JavaScript objects with the same name, so the skeleton definitions are part of the
Filesystemobject.For each Slice interface
<interface-name>, the compiler generates a JavaScript class<interface-name>(Nodein this example). This type extendsIce.Objectand serves as the actual skeleton; it is the base type from which you derive your servant implementation.
Servant Classes
In order to provide an implementation for an Ice object, you must create a servant class that inherits from the corresponding skeleton. For example, to create a servant for the Node interface, you could write:
class MNode extends Filesystem.Node { _name: string;
constructor(name: string) { super(); this._name = name; }
name(current: Ice.Current) { return this._name; }}Note that MNode extends Filesystem.Node, the skeleton class.
As far as Ice is concerned, the MNode class must implement only a single method: the abstract method name. This makes the servant class a concrete class that you can instantiate. You can add other methods and fields as you see fit to support your implementation. For example, in the preceding definition, we added a _name field and a constructor.
Client-Side Mapping for Interfaces
Proxy Classes
A Slice interface maps to a MATLAB class with methods that correspond to the operations on that interface. Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Slice compiler generates the following definition for use by the client:
classdef SimplePrx < Ice.ObjectPrx methods function op(obj, context) % ... end function future = opAsync(obj, context) % ... end end % ...endAs you can see, the compiler generates a proxy class SimplePrx. In general, the generated name is <interface-name>Prx. If an interface is nested in a module M, the generated class is part of namespace M, so the fully-qualified name is M.<interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
Use the inherited constructor of the generated class to create a proxy from a communicator and a “stringified” proxy. For example:
simple = M.SimplePrx(communicator, 'simple:tcp -h localhost -p 4061');Inheritance from Ice.ObjectPrx
Ice.ObjectPrxAll generated proxy classes inherit directly or indirectly from the Ice.ObjectPrx class, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated MATLAB classes. For example:
interface A { ... }interface B { ... }interface C extends A, B { ... }The generated code for CPrx reflects the inheritance hierarchy:
classdef CPrx < APrx & BPrx % ...endGiven a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
The generated proxy class provides two static methods for converting a proxy into a proxy of another type:
classdef SimplePrx < Ice.ObjectPrx methods(Static) function r = uncheckedCast(proxy) % ... end function r = checkedCast(proxy, context) % ... end end % ...enduncheckedCast
The uncheckedCast static method allows you to convert any proxy into a proxy of this type. For example:
% Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.widget = M.WidgetPrx.uncheckedCast(simple);uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
% Call operation ice_isA on the Ice object to check if it implements Slice interface% Widget.widget = M.WidgetPrx.checkedCast(simple);If the target object implements the Slice interface, checkedCast returns a new proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns an empty array. checkedCast can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy class ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');
% Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000);The proxy factory methods usually return a proxy of the same type as the current proxy, like in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
greeter = GreeterPrx(communicator, 'greeter:tcp -h localhost -p 4061');greeterAdmin = GreeterAdminPrx.uncheckedCast(greeter.ice_facet('admin'));Client-Side Mapping for Interfaces
Proxy Objects
In PHP, a single class, Ice\ObjectPrx, implements the proxies of every Slice interface. Each proxy carries the definition of one Slice interface, its type information, and acts as a proxy for that interface. A proxy whose type information is interface Simple is a proxy for Simple: besides the ice_ methods of ObjectPrx, you can call the operations of Simple on it, including the operations Simple inherits.
Creating a Proxy
For each Slice interface, the Slice-to-PHP compiler generates a helper class: for an interface Simple, the name of the generated helper class is SimplePrxHelper.
This helper class provides the createProxy method. For an interface Simple in module M, this helper class is:
namespace M{ class SimplePrxHelper { public static function createProxy($communicator, $proxyString) { ... } }}Use createProxy to create a proxy for Simple from a communicator and a “stringified” proxy. For example:
$simple = M\SimplePrxHelper::createProxy( $communicator, 'simple:tcp -h localhost -p 4061');Interface Inheritance
interface A { ... }interface B { ... }interface C extends A, B { ... }Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Attaching Type Information to a Proxy
In addition to createProxy, the generated helper class provides two static methods that return a copy of a proxy with the type information of the helper's interface:
namespace M{ class SimplePrxHelper { public static function uncheckedCast($proxy, $facet=null) { ... }
public static function checkedCast($proxy, ...$args) { ... } }}uncheckedCast
The helper's uncheckedCast static method returns a copy of any proxy with the type information of its interface, without contacting the target object. For example:
// Create a proxy for Widget from a proxy for Simple, even though the two interfaces are unrelated.$widget = M\WidgetPrxHelper::uncheckedCast($simple);uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast first makes a remote call to the target object to check if this object implements the helper's Slice interface. For example:
// Call operation ice_isA on the Ice object to check if it implements Slice interface// Widget.$widget = M\WidgetPrxHelper::checkedCast($simple);If the target object implements the Slice interface, checkedCast returns a proxy for this interface, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns null. checkedCast can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy for the interface you need directly.
Proxy Factory Methods
The ObjectPrx class supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
$greeter = VisitorCenter\GreeterPrxHelper::createProxy(...);
// Create a new Greeter proxy and assign it to $greeter.$greeter = $greeter->ice_invocationTimeout(10000);The factory methods keep the type information of the proxy they copy, as in the example above.
The only exceptions are the factory methods ice_facet and ice_identity, which return a proxy for Ice::Object: the new facet or identity can designate an object that implements another interface. Attach the type information of that interface with its helper before you invoke an operation on this proxy. For example:
$greeter = VisitorCenter\GreeterPrxHelper::createProxy(...);$greeterAdmin = VisitorCenter\GreeterAdminPrxHelper::uncheckedCast( $greeter->ice_facet("admin"));Client-Side Mapping for Interfaces
Proxy Classes
On the client side, a Slice interface maps to a Python class with methods that correspond to the operations on that interface. Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Python mapping generates the following definition for use by the client:
class SimplePrx(Ice.ObjectPrx):
def op(self, context: dict[str, str] | None = None) -> None: ...
def opAsync(self, context: dict[str, str] | None = None) -> Awaitable[None]: ...As you can see, the compiler generates a proxy class SimplePrx. In general, the generated name is <interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Inheritance from Ice.ObjectPrx
Ice.ObjectPrxAll generated proxy classes inherit directly or indirectly from the Ice.ObjectPrx class, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Creating a Proxy
Use the constructor of the generated proxy class to create a proxy from a communicator and a “stringified” proxy. For example:
import M
simple = M.SimplePrx(communicator, "simple:tcp -h localhost -p 4061")__init__ is inherited from Ice.ObjectPrx.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated Python classes. For example:
interface A { ... }interface B { ... }interface C extends A, B { ... }The generated code for CPrx reflects the inheritance hierarchy:
class CPrx(APrx, BPrx): ...Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
The Python mapping for a proxy also generates 3 static methods for converting a proxy into a proxy of another type:
class SimplePrx(Ice.ObjectPrx): @staticmethod def uncheckedCast(proxy: ObjectPrx | None, facet: str | None = None) -> SimplePrx | None: ...
@staticmethod def checkedCastAsync( proxy: ObjectPrx | None, facet: str | None = None, context: dict[str, str] | None = None) -> Awaitable[SimplePrx | None]: ...
@staticmethod def checkedCast( proxy: ObjectPrx | None, facet: str | None = None, context: dict[str, str] | None = None) -> SimplePrx | None: ...uncheckedCast
uncheckedCast allows you to convert any proxy into a SimplePrx proxy. For example:
# Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.widget = WidgetPrx.uncheckedCast(simple)uncheckedCast is a local operation that always succeeds.
checkedCastAsync
checkedCastAsync makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
# Call operation ice_isA on the Ice object to check if it implements Slice interface# Widget.widget = await WidgetPrx.checkedCastAsync(simple)If the target object implements the Slice interface, checkedCastAsync returns a non-null proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCastAsync returns None. checkedCastAsync can also raise an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCastAsync when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
checkedCast
checkedCast is the synchronous equivalent of checkedCastAsync: it blocks the caller until it receives the response. You should prefer async methods over their synchronous equivalent when making remote calls with Ice.
Proxy Factory Methods
The base proxy class ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
greeter = VisitorCenter.GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")
# Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000)The factory methods usually return a proxy of the same type as the current proxy, as in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
greeter = VisitorCenter.GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")greeterAdmin = VisitorCenter.GreeterAdminPrx.uncheckedCast( greeter.ice_facet("admin"))Server-Side Mapping for Interfaces
Skeleton Classes
On the server side, interfaces map to skeleton classes. A skeleton is an abstract base class from which you derive your servant class and define a method for each operation on the corresponding interface. For example, consider our Slice definition for the Node interface:
module Filesystem{ interface Node { idempotent string name(); } // ...}The Python mapping generates the following definition for this interface:
class Node(Ice.Object, ABC): @abstractmethod def name(self, current: Current) -> str | Awaitable[str]: passThe important points to note here are:
- As for the client side, Slice modules are mapped to Python packages with the same name, so the skeleton class definitions are part of the
Filesystempackage. - The name of the skeleton class is the same as the Slice interface (
Node). - The skeleton class is an abstract base class with an abstract method for each operation defined in the Slice interface.
- The skeleton class inherits from
Ice.Object(which forms the root of the Ice object hierarchy).
Ice.Object Servant Base Class
Ice.Object Servant Base ClassThe Slice pseudo-interface Object is mapped to the Ice.Object class in Python.
Servant Classes
In order to provide an implementation for an Ice object, you must create a servant class that inherits from the corresponding skeleton class. For example, to create a servant for the Node interface, you could write:
from Filesystem import Nodeimport Ice
class MNode(Node): def __init__(self, name: str): self._name = name
def name(self, _: Ice.Current) -> str: return self._nameNote that MNode implements Node, the skeleton class.
As far as Ice is concerned, the MNode class must implement only a single method: the abstract method name. This makes the servant class a concrete class that you can instantiate. You can add other methods and attributes as you see fit to support your implementation. For example, in the preceding definition, we added a _name instance attribute and an initializer.
Client-Side Mapping for Interfaces
Proxy Classes
On the client side, a Slice interface maps to a Ruby class with methods that correspond to the operations on those interfaces. Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Ruby mapping generates the following definition for use by the client:
module SimplePrx_mixin def op(context=nil) ... endend
class SimplePrx < Ice::ObjectPrx include SimplePrx_mixinendIn the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
Use the constructor of the generated class to create a proxy from a communicator and a “stringified” proxy. For example:
simple = M::SimplePrx.new(communicator, "simple:tcp -h localhost -p 4061")Inheritance from Ice::ObjectPrx
Ice::ObjectPrxAll generated proxy classes inherit directly or indirectly from the Ice::ObjectPrx class, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated Ruby classes. For example:
interface A { ... }interface B { ... }interface C extends A, B { ... }The generated code for CPrx uses mixins to include the operations of APrx and BPrx:
module CPrx_mixin include APrx_mixin include BPrx_mixinend
class CPrx < Ice::ObjectPrx include CPrx_mixinendGiven a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
All proxy classes provide 2 class methods that allow you to convert any proxy into a proxy of this type.
def uncheckedCast(proxy, facet: nil) ...end
def checkedCast(proxy, facet: nil, context: nil) ...enduncheckedCast
The uncheckedCast method allows you to convert any proxy into a proxy of this type. For example:
# Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.widget = M::WidgetPrx.uncheckedCast(simple)uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
# Call operation ice_isA on the Ice object to check if it implements Slice interface# Widget.widget = M::WidgetPrx.checkedCast(simple)If the target object implements the Slice interface, checkedCast returns a new proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns nil. checkedCast can also raise an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy class ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
greeter = VisitorCenter::GreeterPrx.new( communicator, "greeter:tcp -h localhost -p 4061")
# Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000)The proxy factory methods usually return a proxy of the same type as the current proxy, like in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
greeter = VisitorCenter::GreeterPrx.new( communicator, "greeter:tcp -h localhost -p 4061")greeterAdmin = VisitorCenter::GreeterAdminPrx.uncheckedCast( greeter.ice_facet("admin"))Client-Side Mapping for Interfaces
Proxy Protocols
On the client side, a Slice interface maps to an empty Swift protocol. A public extension of this protocol provides an async method for each Slice operation of your Slice interface.
Consider the following Slice interface:
module M{ interface Simple { void op(); }}The Slice compiler generates the following definitions for use by the client:
// in module M
public protocol SimplePrx: Ice.ObjectPrx {}
public extension SimplePrx { func op(context: Ice.Context? = nil) async throws { ... }}As you can see, the compiler generates a proxy protocol SimplePrx. In general, the generated name is <interface-name>Prx.
In the client, an instance of SimplePrx is a proxy for an Ice object that implements Simple: it holds the addressing information of this object, such as its identity and endpoints; see Proxy Types.
Creating a Proxy
For each proxy, the Slice compiler generates a makeProxy factory function in the same Swift module. With our previous example:
public protocol SimplePrx: Ice.ObjectPrx {}
public func makeProxy(communicator: Ice.Communicator, proxyString: String, type: SimplePrx.Protocol) throws -> SimplePrx { ...}Call makeProxy to create a proxy from a communicator and a “stringified” proxy:
let simple = try makeProxy( communicator: communicator, proxyString: "simple:tcp -h localhost -p 4061", type: SimplePrx.self)Inheritance from Ice.ObjectPrx
Ice.ObjectPrxAll generated proxy protocols inherit directly or indirectly from the Ice.ObjectPrx protocol, reflecting the fact that all Slice interfaces implicitly inherit from Object.
Interface Inheritance
Inheritance relationships among Slice interfaces are maintained in the generated Swift protocols. For example:
module M{ interface A { ... } interface B { ... } interface C extends A, B { ... }}The generated code for CPrx reflects the inheritance hierarchy:
public protocol CPrx: APrx, BPrx {}Given a proxy for C, a client can invoke any operation defined for interface C, as well as any operation inherited from C's base interfaces.
Creating a Proxy of Another Type
For each proxy, the Slice compiler generates two helper functions that allow you to convert any proxy into a proxy of this type. With our Simple example:
public protocol SimplePrx: Ice.ObjectPrx {}
public func uncheckedCast(prx: Ice.ObjectPrx, type: SimplePrx.Protocol, facet: String? = nil) -> SimplePrx { ...}
public func checkedCast(prx: Ice.ObjectPrx, type: SimplePrx.Protocol, facet: String? = nil, context: Ice.Context? = nil) async throws -> SimplePrx? { ...}uncheckedCast
The uncheckedCast function allows you to convert a proxy into another proxy. For example:
// Convert a SimplePrx into a WidgetPrx, even though the two types are unrelated.let widget = uncheckedCast(prx: simple, type: WidgetPrx.self)uncheckedCast is a local operation that always succeeds.
checkedCast
checkedCast makes a remote call to the target object to check whether it implements the Slice interface of the requested proxy type. For example:
// Call operation ice_isA on the Ice object to check if it implements Slice interface// Widget.let widget = try await checkedCast(prx: simple, type: WidgetPrx.self)If the target object implements the Slice interface, checkedCast returns a non-nil proxy, just like uncheckedCast. If the target object doesn’t implement this interface, checkedCast returns nil. checkedCast can also throw an exception, for example if it cannot reach the remote object.
Use uncheckedCast when you know the target object implements the Slice interface, and checkedCast when you need to ask the target object whether it implements this interface. You rarely need either: you usually create a proxy of the type you need directly.
Proxy Factory Methods
The base proxy interface ObjectPrx supports a variety of methods for customizing a proxy. Since proxies are immutable, each of these factory methods returns a copy of the original proxy that contains the desired modification. For example, you can obtain a proxy configured with a ten second invocation timeout as shown below:
var greeter = try makeProxy(communicator: ..., proxyString: ..., type: GreeterPrx.self)
// Create a new GreeterPrx and assign it to greeter.greeter = greeter.ice_invocationTimeout(10000)The factory methods usually return a proxy of the same type as the current proxy, as in the example above.
The only exceptions are the factory methods ice_facet and ice_identity. Calls to either of these methods may produce a proxy for an object of an unrelated type, and you need to convert the returned proxy into a proxy of that type. For example:
let greeter = try makeProxy(communicator: ..., proxyString: ..., type: GreeterPrx.self)let greeterAdmin = uncheckedCast( prx: greeter.ice_facet("admin"), type: GreeterAdminPrx.self)Server-Side Mapping for Interfaces
The server-side mapping for interfaces provides an up-call API for the Ice runtime: by implementing instance methods in a servant class, you provide the hook that gets the thread of control from the Ice server-side runtime into your application code.
Skeleton Protocols
On the server side, interfaces map to skeleton protocols. A skeleton protocol specifies an instance method for each operation on the corresponding Slice interface. For example, consider our Slice definition for the Node interface:
module Filesystem{ interface Node { idempotent string name(); } // ...}The Slice compiler generates the following definitions for this interface:
// Skeleton protocolpublic protocol Node: Ice.Dispatcher { func name(current: Ice.Current) async throws -> Swift.String}
extension Node { public func dispatch( _ request: sending Ice.IncomingRequest) async throws -> Ice.OutgoingResponse { ... }}The important points to note here are:
- For each Slice interface
<interface-name>, the compiler generates a Swift protocol<interface-name>(Nodein this example). - This skeleton protocol extends
Ice.Dispatcher, and the Slice compiler generates an extension for the skeleton protocol that implementsdispatch(Dispatcher’s only method). - The base servant protocol in Swift is
Ice.Dispatcher; skeleton protocols do not derive fromIce.Object.
Servant Implementation
In order to provide an implementation for an Ice object, you must create a servant struct, class or actor that adopts the corresponding skeleton protocol. For example, to create a servant for the Node interface, you could write:
struct MNode: Node { private let name: String
init(name: String) { self.name = name }
func name(current _: Ice.Current) -> String { name }}Note that MNode adopts Node, the skeleton protocol.
As far as Ice is concerned, the MNode struct must implement only a single method: the name method from its skeleton. This makes the servant struct a concrete type that can be instantiated. You can add other methods and fields as you see fit to support your implementation. For example, in the preceding definition, we added a name field and an initializer.
A skeleton protocol inherits Sendable from Ice.Dispatcher, and the object adapter dispatches each request in its own task, so several tasks can call the same servant concurrently. A struct servant such as MNode satisfies this requirement when all its stored properties are Sendable. Implement a servant with mutable state as an actor. An actor can't return a value whose type doesn't conform to Sendable from a skeleton method, so when the type of a return value or out parameter contains a class, implement the servant as a class that synchronizes access to its state and is declared @unchecked Sendable.