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
Communicator is 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. A communicator is 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:

  • Constructor Details

    • Communicator

      public Communicator(InitializationData initData)
      Constructs a communicator with the specified options.
      Parameters:
      initData - the options for the new communicator

    • Communicator

      public Communicator()
      Constructs a communicator with default options.

    • Communicator

      public Communicator(String[] args, List<String> remainingArgs)
      Constructs a communicator, using Ice properties parsed from command-line arguments. This constructor uses args to create the Properties of the new communicator.
      Parameters:
      args - the command-line arguments
      remainingArgs - if non-null, the remaining command-line arguments after parsing Ice properties

    • Communicator

      public Communicator(String[] args)
      Constructs a communicator, using Ice properties parsed from command-line arguments. This constructor uses args to create the Properties of the new communicator.
      Parameters:
      args - the command-line arguments

  • Method Details

    • close

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

    • destroy

      public void destroy()
      Destroys this communicator. It's an alias for close().

    • 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 close() 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 - if 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.

      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
      Throws:
      IllegalArgumentException - if the provided name is empty and sslEngineFactory is non-null
      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
      Throws:
      CommunicatorDestroyedException - if the communicator has been destroyed
      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
      Throws:
      CommunicatorDestroyedException - if the communicator has been destroyed
      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
      Throws:
      CommunicatorDestroyedException - if this communicator has been destroyed
      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 it is 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 - if 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 - if 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 - if 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: