net.sf.eBus.client.EReplier Maven / Gradle / Ivy
//
// Copyright 2008 - 2011, 2013, 2015, 2016, 2021 Charles W. Rapp
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
package net.sf.eBus.client;
import net.sf.eBus.messages.EReplyMessage;
import net.sf.eBus.messages.EReplyMessage.ReplyStatus;
/**
* Classes able to reply to eBus requests must implement this
* interface. A replier must:
*
* -
* {@link EReplyFeed.Builder build} the reply feed,
*
* -
* {@link EReplyFeed#advertise() advertise} this reply ability, and
*
* -
* {@link EReplyFeed#updateFeedState(EFeedState) declare}
* with an up feed state that it (the replier) is ready to
* handle requests.
*
*
* The message key used in opening the feed must be a
* request message class.
*
* A replier can retract an advertisement by calling
* {@link EReplyFeed#unadvertise()}. The reply feed is discarded
* by calling {@link EReplyFeed#close()}. If a replier is
* temporarily unable to reply to a request, then
* {@code updateFeedState(EFeedState.DOWN)} should be used rather
* than un-advertising. When the replier is again able to
* respond, {@code updateFeedState(EFeedState.UP)} is called.
*
*
* Requests matching the advertised reply feed are forwarded as
* {@link EReplyFeed.ERequest} instances via the
* {@link EReplier#request(EReplyFeed.ERequest)}
* callback. Replies are sent via
* {@link EReplyFeed.ERequest#reply(net.sf.eBus.messages.EReplyMessage)}.
*
*
* Note: the replier is limited to
* {@link net.sf.eBus.messages.EReplyMessage reply messages}
* specified in the
* {@link net.sf.eBus.messages.ERequestMessage request message's}
* {@link net.sf.eBus.messages.EReplyInfo} annotation or in the
* request message super class ({@code EReplyInfo} is inherited).
* If the reply message is not a member of
* {@link net.sf.eBus.messages.EReplyInfo#replyMessageClasses()},
* then it will be rejected.
*
*
* As of eBus v. 4.2.0, implementing the interface methods is no
* longer necessary. Instead, Java lambda expressions may be used
* to handle replier callbacks. This is done by calling
* {@link EReplyFeed.Builder#requestCallback(RequestCallback)}
* and/or
* {@link EReplyFeed.Builder#cancelRequestCallback(CancelRequestCallback)}
* and passing a lambda expression to specify the callback
* target. Still, the application must either override
* {@code EReplier} interface methods or put callbacks in place.
* Failure to do either results in {@link EReplyFeed#advertise()}
* failing. A class wishing to receive requests must still
* implement {@code EReplier} even though it is no longer
* necessary to override the interface methods.
*
*
* It is possible to mix and match {@code EReplier} overrides and
* callbacks. That is, a request callback can be used in
* conjunction with a
* {@link EReplier#cancelRequest(EReplyFeed.ERequest, boolean)}
* override.
*
*
* eBus maintains a weak reference to application objects. If a
* replier is garbage collected without un-advertising and
* closing its reply feed, eBus automatically closes the feed and
* posts failure replies to all active requests.
*
* Canceling an Active Request
*
* eBus v. 5.6.0 updated how request cancellation works by adding
* a second parameter to {@code cancelRequest}:
* {@code boolean mayRespond}. If this {@code boolean} is
* {@code false} then {@code request} is unilaterally closed just
* as before where the replier may no longer
* send replies to the {@link EReplyFeed.ERequest request}.
*
*
* If {@code mayRespond} is {@code true} then this is an
* optional cancel which the replier may or may not accept. The
* replier is expected (but not required) to respond to the
* request. The simplest response is an {@link EReplyMessage}
* with the status set to either
* {@link ReplyStatus#CANCELED} (for accepting the cancel
* request) or {@link ReplyStatus#CANCEL_REJECT}. If the cancel
* request is rejected then {@code request} is still alive and
* the replier may continue to process that request.
*
*
* @see ERequestor
* @see EReplyFeed.ERequest
* @see EReplyFeed
* @see net.sf.eBus.messages.ERequestMessage
* @see net.sf.eBus.messages.EReplyMessage
*
* @author Charles Rapp
*/
public interface EReplier
extends EObject
{
/**
* An incoming request. The replier may send a
* {@link EReplyFeed.ERequest#reply(net.sf.eBus.messages.EReplyMessage) reply}
* either from within this method call or asynchronously
* after returning from this method. If the reply is sent
* asynchronously, then the replier must store
* {@code request} for later use. Replies are sent using
* {@code ERequest} and not {@code EReplyFeed}.
*
* The
* {@link net.sf.eBus.messages.ERequestMessage request message}
* is stored in {@code request} and can be retrieved by
* calling {@link EReplyFeed.ERequest#request()}.
*
*
* The {@link EReplyFeed.ERequest request} matches the
* replier's open and advertised {@link EReplyFeed feed}. The
* associated {@code EReplyFeed} may be retrieved by calling
* {@link EReplyFeed.ERequest#replier()}.
*
* @param request post replies via this request.
* @throws UnsupportedOperationException
* if implementing class does not override this method nor
* uses a callback.
*
* @see #cancelRequest(EReplyFeed.ERequest, boolean)
*/
default void request(EReplyFeed.ERequest request)
{
throw (
new UnsupportedOperationException(
"request not implemented"));
} // end of request(EReplyFeed.ERequest)
/**
* With eBus release 5.6.0 a second, parameter is added:
* {@code mayRespond}. If {@code true} the replier should
* respond with an appropriate
* {@link EReplyMessage reply message}.
* {@link ReplyStatus} was updated with two new values:
* {@code CANCELED} and {@code CANCEL_REJECT}. If the replier
* accepts the cancel request then the reply status should be
* set to {@code CANCELED}. This terminates the request
* (as far as the replier is concerned) and no more requests
* may be sent.
*
* If the replier rejects the cancel request then the reply
* status should be set to {@code CANCEL_REJECT}. This means
* the request is still active and the replier may send
* further replies.
*
*
* If {@code mayRespond} is {@code false} then this is a
* unilateral request cancellation. The request is shut down
* and no further replies will be accepted. However,
* in-flight replies posted prior to cancellation
* may still be delivered.
*
*
* {@link EReplyFeed.ERequest request} matches the
* replier's open and advertised {@link EReplyFeed feed}. The
* associated {@code EReplyFeed} may be retrieved by calling
* {@link EReplyFeed.ERequest#replier()}.
*
* @param request cancel this request.
* @param mayRespond set to {@code true} if replier is
* allowed to respond to the cancel request. This allows the
* replier to accept or reject the request cancellation.
* @throws UnsupportedOperationException
* if implementing class does not override this method nor
* uses a callback.
*
* @see #request(EReplyFeed.ERequest)
*/
default void cancelRequest(EReplyFeed.ERequest request,
boolean mayRespond)
{
throw (
new UnsupportedOperationException(
"cancelRequest not implemented"));
} // end of cancelRequest(EReplyFeed.ERequest, boolean)
} // end of interface EReplier