net.sf.eBus.client.sysmessages.PauseReply Maven / Gradle / Ivy
//
// Copyright 2019, 2020 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.sysmessages;
import java.io.Serializable;
import java.time.Duration;
import javax.annotation.Nullable;
import net.sf.eBus.messages.EReplyMessage.ReplyStatus;
import net.sf.eBus.util.Validator;
/**
* This message is sent is response to a {@link PauseRequest}.
* This response specifies whether the pause request is accepted
* or not. If accepted, then this response provides the allowed
* pause duration and backlog size. These values will be ≤ to
* the requested values, never greater than. The requested
* discard policy is always accepted.
*
* If rejected, then {@link #replyReason} provided
* human-readable text explaining the rejection. Please note that
* {@link #replyStatus} will either be
* {@link ReplyStatus#OK_FINAL} (accepted) or
* {@link ReplyStatus#ERROR} (rejected); it will never be set to
* {@link ReplyStatus#OK_CONTINUING}.
*
*
* @see PauseRequest
* @see LogonReply
*
* @author Charles W. Rapp
*/
public final class PauseReply
extends AbstractLogonMessage
implements Serializable
{
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Constants.
//
/**
* Serialization version identifier.
*/
private static final long serialVersionUID = 0x050200L;
//-----------------------------------------------------------
// Locals.
//
/**
* The current request handling status. If
* {@link ReplyStatus#ERROR}, then {@link #replyReason} will
* contain text explaining why the request was rejected.
*/
public final ReplyStatus replyStatus;
/**
* The reason for a {@link ReplyStatus#ERROR} reply status.
* May be {@code null} or empty.
*/
@Nullable
public final String replyReason;
/**
* Requesting a connection pause lasting for this duration.
* The far-end may not accept this time and require a shorter
* pause time
*/
public final Duration pauseTime;
/**
* Requesting the far-end store up to this many undelivered
* messages before beginning to discard messages. Which
* messages are to be discarded is based on the
* {@link PauseRequest#discardPolicy}. Please note that this
* size is a suggestion. The far-end response may specify
* smaller backlog size.
*/
public final int maximumBacklogSize;
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Creates a pause reply message from the configured builder.
* @param builder pause reply message builder.
*/
private PauseReply(final Builder builder)
{
super (builder);
this.replyStatus = builder.mReplyStatus;
this.replyReason = builder.mReplyReason;
this.pauseTime = builder.mPauseTime;
this.maximumBacklogSize = builder.mMaximumBacklogSize;
} // end of PauseReply(Builder)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
@Override
public String toString()
{
return (
String.format(
"%s%n status: %s%n reason: %s%n pause time: %s%n max backlog size: %d",
super.toString(),
replyStatus,
replyReason,
pauseTime,
maximumBacklogSize));
} // end of toString()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
/**
* Returns a new instance of the {@code PauseReply} message
* builder.
* @return message builder instance.
*/
public static Builder builder()
{
return (new Builder());
} // end of builder()
//---------------------------------------------------------------
// Inner classes.
//
/**
* Class used to create {@link PauseReply} messages. Used
* by eBus to de-serialize an encoded message.
*/
public static final class Builder
extends AbstractLogonMessage.Builder
{
//-----------------------------------------------------------
// Member data.
//
//-------------------------------------------------------
// Locals.
//
/**
* The current request handling status. If
* {@link ReplyStatus#ERROR}, then {@link #replyReason} will
* contain text explaining why the request was rejected.
*/
private ReplyStatus mReplyStatus;
/**
* The reason for a {@link ReplyStatus#ERROR} reply status.
* May be {@code null} or empty.
*/
private String mReplyReason;
/**
* Requesting a connection pause lasting for this duration.
* The far-end may not accept this time and require a shorter
* pause time
*/
private Duration mPauseTime;
/**
* Requesting the far-end store up to this many undelivered
* messages before beginning to discard messages. Which
* messages are to be discarded is based on the
* {@link PauseRequest#discardPolicy}. Please note that
* this size is a suggestion. The far-end response may
* specify smaller backlog size.
*/
private int mMaximumBacklogSize;
//-----------------------------------------------------------
// Member methods.
//
//-------------------------------------------------------
// Constructors.
//
private Builder()
{
super (PauseReply.class);
mMaximumBacklogSize = 0;
} // end of Builder()
//
// end of Constructors.
//-------------------------------------------------------
//-------------------------------------------------------
// Builder Method Overrides.
//
/**
* Returns the newly instantiated {@code PauseReply}
* based on this builder configuration.
* @return target message instance.
*/
@Override
protected PauseReply buildImpl()
{
return (new PauseReply(this));
} // end of buildImpl()
/**
* Adds any and all message configuration problems to
* {@code problems}.
* @param problems used to check field validity and
* collect discovered invalid fields.
* @return {@code problems} to allow for method chaining.
*/
@Override
protected Validator validate(Validator problems)
{
// Reply status and pause time must be set.
// Reply reason and maximum backlog size have
// default settings.
return (super.validate(problems)
.requireNotNull(mReplyStatus,
"reply status")
.requireNotNull(mPauseTime,
"pause time"));
} // end of validate(Validator)
//
// end of Object Method Overrides.
//-------------------------------------------------------
//-------------------------------------------------------
// Set Methods.
//
/**
* Sets the reply status to the given value.
* @param status reply status.
* @return {@code this} pause reply builder.
* @throws NullPointerException
* if {@code status} is {@code null}.
*/
public Builder replyStatus(final ReplyStatus status)
{
if (status == null)
{
throw (
new NullPointerException("status is null"));
}
mReplyStatus = status;
return (this);
} // end of replyStatus(ReplyStatus)
/**
* Sets the reply reason to the given value. May be
* {@code null} or an empty string.
* @param reason reply reason.
* @return {@code this} pause reply builder.
*/
public Builder replyReason(final String reason)
{
mReplyReason = reason;
return (this);
} // end of replyReason(String)
/**
* Sets the pause time to the given value.
* @param time pause time.
* @return {@code this} pause reply builder.
* @throws NullPointerException
* if {@code time} is {@code null}.
*/
public Builder pauseTime(final Duration time)
{
if (time == null)
{
throw (new NullPointerException("time is null"));
}
mPauseTime = time;
return (this);
} // end of pauseTime(Duration)
/**
* Sets the maximum message backlog size to the given
* value.
* @param size maximum message backlog size.
* @return {@code this} pause reply builder.
* @throws IllegalArgumentException
* if {@code size} < zero.
*/
public Builder maximumBacklogSize(final int size)
{
if (size < 0)
{
throw (
new IllegalArgumentException("size < zero"));
}
mMaximumBacklogSize = size;
return (this);
} // end of maximumBacklogSize(int)
//
// end of Set Methods.
//-------------------------------------------------------
} // end of class Builder
} // end of class PauseReply
© 2015 - 2025 Weber Informatics LLC | Privacy Policy