Module com.zeroc.ice
Package com.zeroc.Ice

Class Communicator

java.lang.Object
com.zeroc.Ice.Communicator
All Implemented Interfaces:
AutoCloseable
public final class Communicator extends Object implements AutoCloseable
The central object in Ice. Its responsibilities include: - creating and managing outgoing connections - executing callbacks in its client thread pool - creating and destroying object adapters - loading plug-ins - managing properties (configuration), retries, logging, instrumentation, and more. You create a communicator with Ice.initialize, and it's usually the first object you create when programming with Ice. You can create multiple communicators in a single program, but this is not common.
See Also:

  • Method Details

    • close

      public void close()
      Destroy the communicator. This Java-only method overrides close in java.lang.AutoCloseable and does not throw any exception.
      Specified by:
      close in interface AutoCloseable
      See Also:

    • destroy

      public void destroy()
      Destroys this communicator. This method calls shutdown() implicitly. Calling destroy() destroys all object adapters, and closes all outgoing connections. destroy waits for all outstanding dispatches to complete before returning. This includes "bidirectional dispatches" that execute on outgoing connections.
      See Also:

    • shutdown

      public void shutdown()
      Shuts down this communicator. This method calls ObjectAdapter.deactivate() on all object adapters created by this communicator. Shutting down a communicator has no effect on outgoing connections.
      See Also:

    • waitForShutdown

      public void waitForShutdown()
      Waits for shutdown to complete. This method calls ObjectAdapter.waitForDeactivate() on all object adapters created by this communicator. In a client application that does not accept incoming connections, this method returns as soon as another thread calls shutdown() or destroy() on this communicator.
      See Also:

    • isShutdown

      public boolean isShutdown()
      Checks whether or not shutdown() was called on this communicator.
      Returns:
      true if shutdown() was called on this communicator, false otherwise.
      See Also:

    • stringToProxy

      public ObjectPrx stringToProxy(String str)
      Converts a stringified proxy into a proxy.
      Parameters:
      str - The stringified proxy to convert into a proxy.
      Returns:
      The proxy, or null if str is an empty string.
      Throws:
      ParseException - Thrown when str is not a valid proxy string.
      See Also:

    • proxyToString

      public String proxyToString(ObjectPrx proxy)
      Converts a proxy into a string.
      Parameters:
      proxy - The proxy to convert into a stringified proxy.
      Returns:
      The stringified proxy, or an empty string if proxy is null.
      See Also:

    • propertyToProxy

      public ObjectPrx propertyToProxy(String property)
      Converts a set of proxy properties into a proxy. The "base" name supplied in the property argument refers to a property containing a stringified proxy, such as MyProxy=id:tcp -h localhost -p 10000. Additional properties configure local settings for the proxy.
      Parameters:
      property - The base property name.
      Returns:
      The proxy, or null if the property is not set.

    • proxyToProperty

      public Map<String,String> proxyToProperty(ObjectPrx proxy, String prefix)
      Converts a proxy into a set of proxy properties.
      Parameters:
      proxy - The proxy.
      prefix - The base property name.
      Returns:
      The property set.

    • identityToString

      public String identityToString(Identity ident)
      Converts an identity into a string.
      Parameters:
      ident - The identity to convert into a string.
      Returns:
      The "stringified" identity.

    • createObjectAdapter

      public ObjectAdapter createObjectAdapter(String name)
      Creates a new object adapter. The endpoints for the object adapter are taken from the property name.Endpoints.

      It is legal to create an object adapter with the empty string as its name. Such an object adapter is accessible via bidirectional connections or by collocated invocations.

      Parameters:
      name - The object adapter name.
      Returns:
      The new object adapter.
      See Also:

    • createObjectAdapter

      public ObjectAdapter createObjectAdapter(String name, SSLEngineFactory sslEngineFactory)
      Creates a new object adapter. The endpoints for the object adapter are taken from the property name.Endpoints.

      It is legal to create an object adapter with the empty string as its name. Such an object adapter is accessible via bidirectional connections or by collocated invocations.

      It is an error to pass a non-null sslEngineFactory when the name is empty, this raises IllegalArgumentException.

      Parameters:
      name - The object adapter name.
      sslEngineFactory - The SSL engine factory used by the server-side ssl transport of the new object adapter. When set to a non-null value all Ice.SSL configuration properties are ignored, and any SSL configuration must be done through the SSLEngineFactory. Pass null if the object adapter does not use secure endpoints, or if the ssl transport is configured through Ice.SSL configuration properties. Passing null is equivalent to calling createObjectAdapterWithEndpoints(String, String).
      Returns:
      The new object adapter.
      See Also:

    • createObjectAdapterWithEndpoints

      public ObjectAdapter createObjectAdapterWithEndpoints(String name, String endpoints)
      Creates a new object adapter with endpoints. This method sets the property name.Endpoints, and then calls createObjectAdapter(java.lang.String). It is provided as a convenience method. Calling this method with an empty name will result in a UUID being generated for the name.
      Parameters:
      name - The object adapter name.
      endpoints - The endpoints of the object adapter.
      Returns:
      The new object adapter.
      See Also:

    • createObjectAdapterWithEndpoints

      public ObjectAdapter createObjectAdapterWithEndpoints(String name, String endpoints, SSLEngineFactory sslEngineFactory)
      Creates a new object adapter with endpoints. This method sets the property name.Endpoints, and then calls createObjectAdapter(java.lang.String). It is provided as a convenience method. Calling this method with an empty name will result in a UUID being generated for the name.
      Parameters:
      name - The object adapter name.
      endpoints - The endpoints of the object adapter.
      sslEngineFactory - The SSL engine factory used by the server-side ssl transport of the new object adapter. When set to a non-null value all Ice.SSL configuration properties are ignored, and any SSL configuration must be done through the SSLEngineFactory. Pass null if the object adapter does not use secure endpoints, or if the ssl transport is configured through Ice.SSL configuration properties. Passing null is equivalent to calling createObjectAdapterWithEndpoints(String, String).
      Returns:
      The new object adapter.
      See Also:

    • createObjectAdapterWithRouter

      public ObjectAdapter createObjectAdapterWithRouter(String name, RouterPrx router)
      Creates a new object adapter with a router. This method creates a routed object adapter. Calling this method with an empty name will result in a UUID being generated for the name.
      Parameters:
      name - The object adapter name.
      router - The router.
      Returns:
      The new object adapter.
      See Also:

    • getDefaultObjectAdapter

      public ObjectAdapter getDefaultObjectAdapter()
      Gets the object adapter that is associated by default with new outgoing connections created by this communicator. This method returns null unless you set a non-null default object adapter using setDefaultObjectAdapter(com.zeroc.Ice.ObjectAdapter).
      Returns:
      The object adapter associated by default with new outgoing connections.
      See Also:

    • setDefaultObjectAdapter

      public void setDefaultObjectAdapter(ObjectAdapter adapter)
      Sets the object adapter that will be associated with new outgoing connections created by this communicator. This method has no effect on existing outgoing connections, or on incoming connections.
      Parameters:
      adapter - The object adapter to associate with new outgoing connections.
      See Also:

    • getImplicitContext

      public ImplicitContext getImplicitContext()
      Gets the implicit context associated with this communicator.
      Returns:
      The implicit context associated with this communicator; returns null when the property Ice.ImplicitContext is not set or is set to None.

    • getProperties

      public Properties getProperties()
      Gets the properties of this communicator.
      Returns:
      This communicator's properties.
      See Also:

    • getLogger

      public Logger getLogger()
      Gets the logger of this communicator.
      Returns:
      This communicator's logger.
      See Also:

    • addSliceLoader

      public void addSliceLoader(SliceLoader loader)
      Adds a Slice loader to this communicator, after the Slice loader set in InitializationData (if any) and after other Slice loaders added by this method.

      This method is not thread-safe and should only be called right after the communicator is created. It's provided for applications that cannot set the Slice loader in the InitializationData of the communicator, such as IceBox services.

      Parameters:
      loader - The Slice loader to add.

    • getObserver

      public CommunicatorObserver getObserver()
      Gets the observer object of this communicator.
      Returns:
      This communicator's observer object.

    • getDefaultRouter

      public RouterPrx getDefaultRouter()
      Gets the default router of this communicator.
      Returns:
      The default router of this communicator.
      See Also:

    • setDefaultRouter

      public void setDefaultRouter(RouterPrx router)
      Sets the default router of this communicator. All newly created proxies will use this default router. This method has no effect on existing proxies.
      Parameters:
      router - The new default router. Use null to remove the default router.
      See Also:

    • getDefaultLocator

      public LocatorPrx getDefaultLocator()
      Gets the default locator of this communicator.
      Returns:
      The default locator of this communicator.
      See Also:

    • setDefaultLocator

      public void setDefaultLocator(LocatorPrx locator)
      Sets the default locator of this communicator. All newly created proxies will use this default locator. This method has no effect on existing proxies or object adapters.
      Parameters:
      locator - The new default locator. Use null to remove the default locator.
      See Also:

    • getPluginManager

      public PluginManager getPluginManager()
      Gets the plug-in manager of this communicator.
      Returns:
      This communicator's plug-in manager.
      See Also:

    • flushBatchRequests

      public void flushBatchRequests(CompressBatch compressBatch)
      Flushes any pending batch requests of this communicator. This means all batch requests invoked on fixed proxies for all connections associated with the communicator. Errors that occur while flushing a connection are ignored.
      Parameters:
      compressBatch - Specifies whether or not the queued batch requests should be compressed before being sent over the wire.

    • flushBatchRequestsAsync

      public CompletableFuture<Void> flushBatchRequestsAsync(CompressBatch compressBatch)
      Flushes any pending batch requests of this communicator. This means all batch requests invoked on fixed proxies for all connections associated with the communicator. Errors that occur while flushing a connection are ignored.
      Parameters:
      compressBatch - Specifies whether or not the queued batch requests should be compressed before being sent over the wire.
      Returns:
      A future that will be completed when the invocation completes.

    • createAdmin

      public ObjectPrx createAdmin(ObjectAdapter adminAdapter, Identity adminId)
      Adds the Admin object with all its facets to the provided object adapter. If Ice.Admin.ServerId is set and the provided object adapter has a Locator, createAdmin registers the Admin's Process facet with the Locator's LocatorRegistry.
      Parameters:
      adminAdapter - The object adapter used to host the Admin object; if null and Ice.Admin.Endpoints is set, this method uses the Ice.Admin object adapter, after creating and activating this adapter.
      adminId - The identity of the Admin object.
      Returns:
      A proxy to the main ("") facet of the Admin object.
      Throws:
      InitializationException - Thrown when createAdmin is called more than once.
      See Also:

    • getAdmin

      public ObjectPrx getAdmin()
      Gets a proxy to the main facet of the Admin object. getAdmin also creates the Admin object and creates and activates the Ice.Admin object adapter to host this Admin object if Ice.Admin.Endpoints is set. The identity of the Admin object created by getAdmin is {value of Ice.Admin.InstanceName}/admin, or {UUID}/admin when Ice.Admin.InstanceName is not set. If Ice.Admin.DelayCreation is 0 or not set, getAdmin is called by the communicator initialization, after initialization of all plugins.
      Returns:
      A proxy to the main ("") facet of the Admin object, or null if no Admin object is configured.
      See Also:

    • addAdminFacet

      public void addAdminFacet(Object servant, String facet)
      Adds a new facet to the Admin object.
      Parameters:
      servant - The servant that implements the new Admin facet.
      facet - The name of the new Admin facet.
      Throws:
      AlreadyRegisteredException - Thrown when a facet with the same name is already registered.

    • removeAdminFacet

      public Object removeAdminFacet(String facet)
      Removes a facet from the Admin object.
      Parameters:
      facet - The name of the Admin facet.
      Returns:
      The servant associated with this Admin facet.
      Throws:
      NotRegisteredException - Thrown when no facet with the given name is registered.

    • findAdminFacet

      public Object findAdminFacet(String facet)
      Returns a facet of the Admin object.
      Parameters:
      facet - The name of the Admin facet.
      Returns:
      The servant associated with this Admin facet, or null if no facet is registered with the given name.

    • findAllAdminFacets

      public Map<String,Object> findAllAdminFacets()
      Returns a map of all facets of the Admin object.
      Returns:
      A collection containing all the facet names and servants of the Admin object.
      See Also: