Package org.apache.qpid.protonj2.engine

Interface Endpoint<E extends Endpoint<E>>

Type Parameters:
E - The Endpoint type
All Known Subinterfaces:
Connection, Link<L>, Receiver, Sender, Session, TransactionController, TransactionManager
All Known Implementing Classes:
ProtonConnection, ProtonEndpoint, ProtonLink, ProtonReceiver, ProtonSender, ProtonSession, ProtonTransactionController, ProtonTransactionManager
public interface Endpoint<E extends Endpoint<E>>
Represents a conceptual endpoint type used to provide common operations that all the endpoint types will share.

  • Method Details

    • open

      E open() throws EngineStateException
      Open the end point locally, sending the Open performative immediately if possible or holding it until SASL negotiations or the AMQP header exchange and other required performative exchanges has completed. The end point will signal any registered handler of the remote opening the Connection once the remote performative that signals open completion arrives.
      Returns:
      this Endpoint instance.
      Throws:
      EngineStateException - if an error occurs opening the Connection or the Engine is shutdown.

    • close

      E close() throws EngineFailedException
      Close the end point locally and send the closing performative immediately if possible or holds it until the Connection / Engine state allows it. If the engine encounters an error writing the performative or the engine is in a failed state from a previous error then this method will throw an exception. If the engine has been shutdown then this method will close out the local end of the Endpoint and clean up any local resources before returning normally.
      Returns:
      this Endpoint instance.
      Throws:
      EngineFailedException - if an error occurs closing the end point or the Engine is in a failed state.

    • getAttachments

      Attachments getAttachments()
      Returns:
      the Attachments instance that is associated with this Endpoint

    • getEngine

      Engine getEngine()
      Returns:
      the Engine which created this Endpoint instance.

    • getParent

      Endpoint<?> getParent()
      Gets the parent of this Endpoint which can be itself for Connection instance.
      Returns:
      the parent of this Endpoint or itself if this is a Connection;

    • setLinkedResource

      E setLinkedResource(Object resource)
      Links a given resource to this Endpoint.
      Parameters:
      resource - The resource to link to this Endpoint.
      Returns:
      this Endpoint instance.

    • getLinkedResource

      <T> T getLinkedResource()
      Type Parameters:
      T - The type that the linked resource should be cast to on return.
      Returns:
      the user set linked resource for this Endpoint instance.

    • getLinkedResource

      <T> T getLinkedResource(Class<T> typeClass)
      Gets the linked resource (if set) and returns it using the type information provided to cast the returned value.
      Type Parameters:
      T - The type to cast the linked resource to if one is set.
      Parameters:
      typeClass - the type's Class which is used for casting the returned value.
      Returns:
      the user set linked resource for this Context instance.
      Throws:
      ClassCastException - if the linked resource cannot be cast to the type requested.

    • getCondition

      ErrorCondition getCondition()
      Returns:
      the local Endpoint error, or null if there is none

    • setCondition

      E setCondition(ErrorCondition condition)
      Sets the local ErrorCondition to be applied to a Endpoint close.
      Parameters:
      condition - The error condition to convey to the remote peer on close of this end point.
      Returns:
      this Endpoint instance.

    • isLocallyOpen

      boolean isLocallyOpen()
      Returns true if this Endpoint is currently locally open meaning that the open() has been called but the close() has not.
      Returns:
      true if the Endpoint is locally open.
      See Also:

    • isLocallyClosed

      boolean isLocallyClosed()
      Returns true if this Endpoint is currently locally closed meaning that a call to the close() method has occurred.
      Returns:
      true if the Endpoint is locally closed.
      See Also:

    • setOfferedCapabilities

      E setOfferedCapabilities(Symbol... capabilities) throws IllegalStateException
      Sets the capabilities to be offered on to the remote when this Endpoint is opened. The offered capabilities value can only be modified prior to a call to open(), once the Endpoint has been opened locally an error will be thrown if this method is called.
      Parameters:
      capabilities - The capabilities to be offered to the remote when the Endpoint is opened.
      Returns:
      this Endpoint instance.
      Throws:
      IllegalStateException - if the Endpoint has already been opened.

    • getOfferedCapabilities

      Symbol[] getOfferedCapabilities()
      Returns:
      the configured capabilities that are offered to the remote when the Endpoint is opened.

    • setDesiredCapabilities

      E setDesiredCapabilities(Symbol... capabilities) throws IllegalStateException
      Sets the capabilities that are desired from the remote when this Endpoint is opened. The desired capabilities value can only be modified prior to a call to open(), once the Endpoint has been opened locally an error will be thrown if this method is called.
      Parameters:
      capabilities - The capabilities desired from the remote when the Endpoint is opened.
      Returns:
      this Endpoint instance.
      Throws:
      IllegalStateException - if the Endpoint has already been opened.

    • getDesiredCapabilities

      Symbol[] getDesiredCapabilities()
      Returns:
      the configured desired capabilities that are sent to the remote when the Connection is opened.

    • setProperties

      E setProperties(Map<Symbol,Object> properties) throws IllegalStateException
      Sets the properties to be sent to the remote when this Endpoint is Opened. The Endpoint properties value can only be modified prior to a call to open(), once the Endpoint has been opened locally an error will be thrown if this method is called.
      Parameters:
      properties - The properties that will be sent to the remote when this Connection is opened.
      Returns:
      this Endpoint instance.
      Throws:
      IllegalStateException - if the Endpoint has already been opened.

    • getProperties

      Map<Symbol,Object> getProperties()
      Returns:
      the configured properties sent to the remote when this Connection is opened.

    • isRemotelyOpen

      boolean isRemotelyOpen()
      Returns true if this Endpoint is currently remotely open meaning that the AMQP performative that completes the open phase of this Endpoint's lifetime has arrived but the performative that closes it has not.
      Returns:
      true if the Endpoint is remotely open.
      See Also:

    • isRemotelyClosed

      boolean isRemotelyClosed()
      Returns true if this Endpoint is currently remotely closed meaning that the AMQP performative that completes the close phase of this Endpoint's lifetime has arrived.
      Returns:
      true if the Endpoint is remotely closed.
      See Also:

    • getRemoteCondition

      ErrorCondition getRemoteCondition()
      If the remote has closed this Endpoint and provided an ErrorCondition as part of the closing AMQP performative then this method will return it.
      Returns:
      the remote supplied ErrorCondition, or null if there is none.

    • getRemoteOfferedCapabilities

      Symbol[] getRemoteOfferedCapabilities()
      Returns:
      the capabilities offered by the remote when it opened its end of the Endpoint.

    • getRemoteDesiredCapabilities

      Symbol[] getRemoteDesiredCapabilities()
      Returns:
      the capabilities desired by the remote when it opened its end of the Endpoint.

    • getRemoteProperties

      Map<Symbol,Object> getRemoteProperties()
      Returns:
      the properties sent by the remote when it opened its end of the Endpoint.

    • localOpenHandler

      E localOpenHandler(EventHandler<E> localOpenHandler)
      Sets a EventHandler for when an this Endpoint is opened locally via a call to open() Typically used by clients for logging or other state update event processing. Clients should not perform any blocking calls within this context. It is an error for the handler to throw an exception and the outcome of doing so is undefined.
      Parameters:
      localOpenHandler - The EventHandler to notify when this Endpoint is locally opened.
      Returns:
      this Endpoint instance.

    • localCloseHandler

      E localCloseHandler(EventHandler<E> localCloseHandler)
      Sets a EventHandler for when an this Endpoint is closed locally via a call to close() Typically used by clients for logging or other state update event processing. Clients should not perform any blocking calls within this context. It is an error for the handler to throw an exception and the outcome of doing so is undefined.
      Parameters:
      localCloseHandler - The EventHandler to notify when this Endpoint is locally closed.
      Returns:
      this Endpoint instance.

    • openHandler

      E openHandler(EventHandler<E> remoteOpenEventHandler)
      Sets a EventHandler for when an AMQP Open frame is received from the remote peer. Used to process remotely initiated Connections. Locally initiated sessions have their own EventHandler invoked instead. This method is typically used by servers to listen for the remote peer to open its Endpoint, while a client would listen for the server to open its end of the Endpoint once a local open has been performed. Typically used by clients as servers will typically listen to some parent resource event handler to determine if the remote is initiating a resource open.
      Parameters:
      remoteOpenEventHandler - the EventHandler that will be signaled when the Endpoint has been remotely opened
      Returns:
      this Endpoint instance.

    • closeHandler

      E closeHandler(EventHandler<E> remoteCloseEventHandler)
      Sets a EventHandler for when an AMQP Close frame is received from the remote peer.
      Parameters:
      remoteCloseEventHandler - the EventHandler that will be signaled when the Endpoint is remotely closed.
      Returns:
      this Endpoint instance.

    • engineShutdownHandler

      E engineShutdownHandler(EventHandler<Engine> engineShutdownEventHandler)
      Sets an EventHandler that is invoked when the engine that supports this Endpoint is shutdown via a call to Engine.shutdown() which indicates a desire to terminate all engine operations. Any Endpoint that has been both locally and remotely closed will not receive this event as it will no longer be tracked by the parent its parent Endpoint. A typical use of this event would be from a locally closed Endpoint that is awaiting response from the remote. If this event fires then there will never be a remote response to any pending operations and the client or server instance should react accordingly to clean up any related resources etc.
      Parameters:
      engineShutdownEventHandler - the EventHandler that will be signaled when this Endpoint's engine is explicitly shutdown.
      Returns:
      this Endpoint instance.