net.sf.eBus.client.ConnectionMessage Maven / Gradle / Ivy
The newest version!
//
// Copyright 2014, 2016, 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.
//
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later
// version.
//
// This library is distributed in the hope that it will be
// useful, but WITHOUT ANY WARRANTY; without even the implied
// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
// PURPOSE. See the GNU Lesser General Public License for more
// details.
//
// You should have received a copy of the GNU Lesser General
// Public License along with this library; if not, write to the
//
// Free Software Foundation, Inc.,
// 59 Temple Place, Suite 330,
// Boston, MA
// 02111-1307 USA
//
// The Initial Developer of the Original Code is Charles W. Rapp.
// Portions created by Charles W. Rapp are
// Copyright 2014, 2016, 2020. Charles W. Rapp
// All Rights Reserved.
//
package net.sf.eBus.client;
import java.io.Serializable;
import java.util.Formatter;
import java.util.Objects;
import net.sf.eBus.messages.ELocalOnly;
import net.sf.eBus.messages.EMessageKey;
import net.sf.eBus.messages.ESystemMessage;
import net.sf.eBus.util.Validator;
/**
* This message reports when a
* {@link #remoteAddress remote connection} has either
* {@link #state logged on or logged off}. If the remote
* connection logged off, then may provide the
* {@link #reason reason} why remote eBus logged off
* ({@code reason} field may be {@code null}).
*
* All connection messages have the subject
* {@link ESystemMessage#SYSTEM_SUBJECT "/eBus"}. Subscribe to
* {@link #MESSAGE_KEY ConnectionMessage.class/eBus} to receive
* this notification.
*
*
* Note: this notification is published
* locally only and is not sent to remote eBus applications.
*
*
* @see ServerMessage
*
* @author Charles Rapp
*/
@ELocalOnly
public final class ConnectionMessage
extends AbstractEBusMessage
implements Serializable
{
//---------------------------------------------------------------
// Enums.
//
/**
* A remote eBus is either logged on or logged off.
*/
public enum ConnectionState
{
/**
* A remote eBus connection is logged on.
*/
LOGGED_ON,
/**
* A remote eBus connection is logged off.
*/
LOGGED_OFF,
/**
* Remote eBus connection is paused.
*/
PAUSED,
/**
* Remote eBus connection is resumed.
*/
RESUMED
} // end of enum ConnectionState
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Constants.
//
/**
* The connection message key
* {@code ConnectionMessage.class:/eBus}.
*/
public static final EMessageKey MESSAGE_KEY =
new EMessageKey(ConnectionMessage.class,
ESystemMessage.SYSTEM_SUBJECT);
/**
* Serialization version identifier.
*/
private static final long serialVersionUID = 0x050200L;
//-----------------------------------------------------------
// Locals.
//
/**
* The remote eBus is either logged on or logged off.
*/
public final ConnectionState state;
/**
* If {@link #state} is {@link ConnectionState#LOGGED_OFF}
* and the log off was due to an exception, then the
* {@link Throwable#getMessage() exception message} is stored
* here. May be {@code null}.
*/
public final String reason;
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Creates a new connection message based on the builder
* settings.
* @param builder connection message builder.
*/
private ConnectionMessage(final Builder builder)
{
super (builder);
this.state = builder.mConnectionState;
this.reason = builder.mReason;
} // end of ConnectionMessage(Builder)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
/**
* Returns the connection message as text.
* @return textual representation of the connection message.
*/
@Override
public String toString()
{
final String retval;
try (Formatter output = new Formatter())
{
retval = output.format("%s%n", super.toString())
.format(" connection state: %s%n",
state)
.format(" reason: %s",
(reason == null || reason.isEmpty() ?
"(not set)" :
reason))
.toString();
}
return (retval);
} // end of toString()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
/**
* Returns a connection message builder instance.
* @return message builder instance.
*/
public static Builder builder()
{
return (new Builder());
} // end of builder()
//---------------------------------------------------------------
// Inner classes.
//
/**
* Use this builder to create {@code ConnectionMessage}
* instances.
*/
public static final class Builder
extends AbstractEBusMessage.Builder
{
//-----------------------------------------------------------
// Member data.
//
//-------------------------------------------------------
// Locals.
//
private ConnectionState mConnectionState;
private String mReason;
//-----------------------------------------------------------
// Member methods.
//
//-------------------------------------------------------
// Constructors.
//
private Builder()
{
super (ConnectionMessage.class);
} // end of Builder()
//
// end of Constructors.
//-------------------------------------------------------
//-------------------------------------------------------
// Builder Method Overrides.
//
/**
* Returns a connection message based on {@code this}
* builder's field settings.
* @return new eBus connection message.
*/
@Override
protected ConnectionMessage buildImpl()
{
return (new ConnectionMessage(this));
} // end of buildImpl()
/**
* Checks if connection state is set.
* @param problems used to check field validity and
* collect discovered invalid fields.
* @return {@code problems} to allow for method chaining.
*/
@Override
protected Validator validate(final Validator problems)
{
return (super.validate(problems)
.requireNotNull(mConnectionState,
"connection state"));
} // end of validate(Validator)
//
// end of Builder Method Overrides.
//-------------------------------------------------------
//-------------------------------------------------------
// Set Methods.
//
/**
* Sets connection state to given value.
* @param state connection state.
* @return {@code this Builder} instance.
* @throws NullPointerException
* if {@code state} is {@code null}.
*/
public Builder state(final ConnectionState state)
{
mConnectionState =
Objects.requireNonNull(state, "state is null");
return (this);
} // end of state(ConnectionState)
public Builder reason(final String reason)
{
mReason = reason;
return (this);
} // end of reason(String)
//
// end of Set Methods.
//-------------------------------------------------------
} // end of class Builder
} // end of class ConnectionMessage
© 2015 - 2025 Weber Informatics LLC | Privacy Policy