Package org.eclipse.californium.core.observe

Class ObserveRelation

java.lang.Object
org.eclipse.californium.core.observe.ObserveRelation
public class ObserveRelation extends Object
The ObserveRelation is a server-side control structure.

It represents a relation between a client endpoint and a resource on this server. It holds the initial Exchange with the Request, and it keeps also track of some states, especially a mechanism to probe frequently the client's interest by using CON notifies. A mechanism to handle resource changes while such a CON notification is in transit and may be required to be retransmitted is also implemented her.

The observe-relations a stored in two collections, one per client, the ObservingEndpoint, and one per resource, the ObservableResource. When receiving an observer request, the observe relation is first put in ObserveRelation.State.INIT and is stored in the ObservingEndpoint. With the first response, the observe relation gets either ObserveRelation.State.ESTABILSHED, if the response is Response.isSuccess(), or the observe relation gets ObserveRelation.State.CANCELED. When it get's established, the observe relation is also added to the ObservableResource and with that changes will be reported by notifies.

If a CON notification is send and times out, the endpoint is considered to be not longer reachable and all established observe-relations are canceled. If such a CON notification is rejected by a RST message, only this observe relation is canceled.

  • Constructor Details

  • Method Details

    • setEndpoint

      public void setEndpoint(ObservingEndpoint endpoint)
      Set observing endpoint.
      Parameters:
      endpoint - observing endpoint
      Since:
      3.6

    • isEstablished

      public boolean isEstablished()
      Returns his relation established state.
      Returns:
      true, if this relation has been established, false, otherwise

    • setEstablished

      public void setEstablished()
      Sets the established field. Adds this relations to the resource
      Throws:
      IllegalStateException - if the relation was already canceled.

    • isCanceled

      public boolean isCanceled()
      Check, if this relation is canceled.
      Returns:
      true, if relation was canceled, false, otherwise.

    • cleanup

      @Deprecated public void cleanup()
      Deprecated.
      use cancel() also for not established relations
      Cleanup relation. cancel(), if isEstablished().
      Since:
      3.0

    • reject

      public void reject()

    • cancel

      public void cancel()
      Cancel this observe relation. This methods invokes the cancel methods of the resource and the endpoint. A last response must have been sent before. Otherwise the Exchange will be completed and fail that sending. Note: calling this method outside the execution of the related exchange may naturally cause indeterministic behavior.
      Throws:
      IllegalStateException - if relation wasn't established.

    • cancelAll

      public void cancelAll()
      Cancel all observer relations that this server has established with this relation's endpoint.

    • notifyObservers

      @Deprecated public void notifyObservers()
      Deprecated.
      obsolete
      Notifies the observing endpoint that the resource has been changed. This method makes the resource process the same request again. Note: the ObservableResource must implement Resource as well in order to call this method
      Throws:
      ClassCastException - if ObservableResource does not implement Resource as well

    • getResource

      @Deprecated public Resource getResource()
      Deprecated.
      obsolete
      Gets the resource. Note: the ObservableResource must implement Resource as well in order to call this method
      Returns:
      the resource
      Throws:
      ClassCastException - if ObservableResource does not implement Resource as well

    • getExchange

      public Exchange getExchange()
      Gets the exchange.
      Returns:
      the exchange

    • getSource

      public InetSocketAddress getSource()
      Gets the source address of the observing endpoint.
      Returns:
      the source address

    • getEndpoint

      public ObservingEndpoint getEndpoint()
      Gets the source address of the observing endpoint.
      Returns:
      the source address

    • getObserveType

      public CoAP.Type getObserveType()
      Get the type of the notifications that will be sent. Uses ObservableResource.getObserveType(), or the request's type, if no observe-type is provided. If this results in CoAP.Type.NON, then check() is used, to determine, if the notification is adapted to CoAP.Type.CON to verify, that the client is still interested.
      Returns:
      the type of the notifications
      Since:
      3.6

    • onResponse

      public ObserveRelation.State onResponse(Response response)
      Process response using this observe relation. The first response will setEstablished() the relation and ObservableResource.addObserveRelation(ObserveRelation) it. If the response Response.isSuccess(), OptionSet.setObserve(int) is not already provided, and this relation is not isCanceled(), the ObservableResource.getNotificationSequenceNumber() will be provided to OptionSet.setObserve(int)
      Parameters:
      response - response
      Returns:
      current relation state.
      Since:
      3.11 (behavior change: already provided observe options will not be overwritten).

    • check

      public boolean check()
      Check, if notification is sent to test, if it is still requested by the client. Send notification as CON response in order to challenge the client to acknowledge the message.
      Returns:
      true, to check the observer relation with a CON-notification, false, otherwise.

    • isPostponedNotification

      public boolean isPostponedNotification(Response response)
      Check, if sending the provided notification is postponed. Postponed notification are kept and sent after the current notification. Calls onSend(Response), if not postponed.
      Parameters:
      response - notification to check.
      Returns:
      true, if sending the notification is postponed, false, if not.
      Since:
      3.0

    • getNextNotification

      public Response getNextNotification(Response response, boolean acknowledged)
      Get next notification. Calls onSend(Response) for next notification.
      Parameters:
      response - current notification
      acknowledged - true, if the current notification was acknowledged, or false, on retransmission (caused by missing acknowledged)
      Returns:
      next notification, or null, if no next notification is available.
      Since:
      3.0

    • send

      @Deprecated public void send(Response response)
      Deprecated.
      use onSend(Response) instead
      Send response for this relation. If the response is no notification, cancel() the relation internally without completing the exchange.
      Parameters:
      response - response to sent.
      Since:
      3.0

    • onSend

      public void onSend(Response response)
      On send response for this relation. If the response is no notification, cancel() the relation internally without completing the exchange.
      Parameters:
      response - response to sent.
      Since:
      3.6

    • getKeyToken

      public KeyToken getKeyToken()
      Get key-token, identifying this observer relation. Combination of source-address and token.
      Returns:
      identifying key
      Since:
      3.6

    • getKey

      @Deprecated public String getKey()
      Deprecated.
      use getKeyToken() instead
      Get key, identifying this observer relation. Combination of source-address and token.
      Returns:
      identifying key

    • onResponse

      public static ObserveRelation.State onResponse(ObserveRelation relation, Response response)
      Process response using this observe relation. The first response will setEstablished() the relation and ObservableResource.addObserveRelation(ObserveRelation) it. If the response Response.isSuccess(), OptionSet.setObserve(int) is not already provided, and this relation is not isCanceled(), the ObservableResource.getNotificationSequenceNumber() will be provided to OptionSet.setObserve(int)
      Parameters:
      relation - the observe relation, or null, if not available
      response - response
      Returns:
      current relation state.
      Since:
      3.11 (behavior change: already provided observe options will not be overwritten for success responses).
      See Also:

    • getKeyToken

      public static KeyToken getKeyToken(Exchange exchange)
      Get key token from exchange.
      Parameters:
      exchange - observe- or cancel-request exchange
      Returns:
      key token with remote endpoint and request token.
      Since:
      3.6