net.sf.eBus.messages.EMessageHeader Maven / Gradle / Ivy
The newest version!
//
// Copyright 2011 - 2013, 2015, 2016 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.messages;
import java.net.SocketAddress;
import net.sf.eBus.messages.type.DataType;
/**
* Contains the {@link EMessage} header information. This
* includes the "from" proxy identifier, the "to" proxy
* identifier, and the eBus {@link EMessage}. The proxy
* identifiers are used to route messages between remote eBus
* applications. The proxies are used to represent the remote
* eBus' capability within the local JVM.
*
* This class is immutable.
*
* The binary serialization format for an eBus message header is:
*
* -
* 2-byte, signed integer serialized header length. These two
* bytes are also used for the heartbeat (-15,000) and
* heartbeat reply (-8,000) indicators.
*
* -
* 4-byte, signed integer message class identifier. This is
* the same identifier received from the remote application's
* {@link net.sf.eBus.client.sysmessages.KeyMessage}.
*
* -
* 4-byte, signed integer from feed identifier. The local
* eBus feed responsible for sending this message.
*
* -
* 4-byte, signed integer to feed identifier. The remote
* eBus feed responsible for handling this message. If the
* remote feed is not known when the message is sent, it is
* set to {@link #NO_ID}.
*
* -
* The de-serialized eBus message. See
* {@link net.sf.eBus.messages.type.MessageType} about eBus
* message and field serialization.
*
*
*
* Both the "to" and "from" feeds are encapsulated in an
* {@code ERemoteApp} instance.
*
*
* @see net.sf.eBus.messages.EMessage
*
* @author Charles Rapp
*/
public final class EMessageHeader
{
//---------------------------------------------------------------
// Member data.
//
//-----------------------------------------------------------
// Constants.
//
/**
* Proxy identifiers are set to -1 to signify that they are
* unknown at the time the message was sent.
*/
public static final int NO_ID = -1;
//-----------------------------------------------------------
// Locals.
//
/**
* The unique class identifier. This identifier
* is unique within the scope of its local eBus application.
*/
private final int mClassId;
/**
* The message was sent from this eBus proxy instance. Set to
* {@link #NO_ID} for system messages.
*/
private final int mFromFeedId;
/**
* The message is destined for this eBus proxy instance. Set
* to {@link #NO_ID} if the destination proxy is unknown.
*/
private final int mToFeedId;
/**
* Message sequence number.
*/
private int mSequenceNumber;
/**
* The optional source or destination address for this eBus
* message. This field is only set for messages posted via
* UDP datagram packets. Set to {@code null} when posting
* messages via TCP.
*/
private final SocketAddress mAddress;
/**
* The encapsulated eBus message.
*/
private final EMessage mMessage;
/**
* Encapsulated message's type.
*/
private final DataType mDataType;
//---------------------------------------------------------------
// Member methods.
//
//-----------------------------------------------------------
// Constructors.
//
/**
* Creates a message header with the given key, from and to
* feed identifiers and eBus message. Sets the message's
* associated address to {@code null} and sequence number to
* {@link #NO_ID}.
* @param classId the message class identifier.
* @param fromFeedId the message is from this eBus proxy.
* Will be {@link #NO_ID} for
* {@link ESystemMessage system messages} only; all other
* messages must set this to a value ≥ zero.
* @param toFeedId the message is destined for this eBus
* proxy. Will be {@link #NO_ID} if the destination proxy is
* unknown.
* @param msg the eBus message.
* @throws IllegalArgumentException
* if {@code msg} is {@code null} or if {@code msg} is an
* application message and {@code classId},
* {@code fromFeedId}, or {@code sequenceNumber} is <
* zero.
*/
public EMessageHeader(final int classId,
final int fromFeedId,
final int toFeedId,
final EMessage msg)
{
this (classId,
fromFeedId,
toFeedId,
NO_ID,
null,
msg);
} // end of EMessageHeader(int, int, int, int, EMessage)
/**
* Creates a message header with the given key, from and to
* feed identifiers, message source/destination address, and
* eBus message. Sequence number set to {@link #NO_ID}.
* @param classId the message class identifier.
* @param fromFeedId the message is from this eBus proxy.
* Will be {@link #NO_ID} for
* {@link ESystemMessage system messages} only; all other
* messages must set this to a value ≥ zero.
* @param toFeedId the message is destined for this eBus
* proxy. Will be {@link #NO_ID} if the destination proxy is
* unknown.
* @param address message source or destination address. May
* be {@code null}.
* @param msg the eBus message.
* @throws IllegalArgumentException
* if {@code msg} is {@code null} or if {@code msg} is an
* application message and {@code classId},
* {@code fromFeedId}, or {@code sequenceNumber} is <
* zero.
*/
public EMessageHeader(final int classId,
final int fromFeedId,
final int toFeedId,
final SocketAddress address,
final EMessage msg)
{
this (classId,
fromFeedId,
toFeedId,
NO_ID,
address,
msg);
} // end of EMessageHeader(...)
/**
* Creates a message header with the given key, from and to
* feed identifiers and eBus message.
* @param classId the message class identifier.
* @param fromFeedId the message is from this eBus proxy.
* Will be {@link #NO_ID} for
* {@link ESystemMessage system messages} only; all other
* messages must set this to a value ≥ zero.
* @param toFeedId the message is destined for this eBus
* proxy. Will be {@link #NO_ID} if the destination proxy is
* unknown.
* @param sequenceNumber message sequence number.
* @param address message source or destination address. May
* be {@code null}.
* @param msg the eBus message.
* @throws IllegalArgumentException
* if {@code msg} is {@code null} or if {@code msg} is an
* application message and {@code classId},
* {@code fromFeedId}, or {@code sequenceNumber} is <
* zero.
*/
public EMessageHeader(final int classId,
final int fromFeedId,
final int toFeedId,
final int sequenceNumber,
final SocketAddress address,
final EMessage msg)
{
if (msg == null)
{
throw (new IllegalArgumentException("null msg"));
}
// If this is a system message, then the class and from
// feed identifiers may be less than zero.
if (msg.isApplicationMessage())
{
if (classId < 0)
{
throw (
new IllegalArgumentException("classId < 0"));
}
if (fromFeedId < 0)
{
throw (
new IllegalArgumentException(
"fromProxyId < 0"));
}
}
mClassId = classId;
mFromFeedId = fromFeedId;
mToFeedId = toFeedId;
mSequenceNumber = sequenceNumber;
mAddress = address;
mMessage = msg;
mDataType = DataType.findType(msg.getClass());
} // end of EMessageHeader(...)
//
// end of Constructors.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Object Method Overrides.
//
/**
* Returns this header as human-readable text.
* @return the header as text.
*/
@Override
public String toString()
{
return (String.format("[key=%d,from=%d;to=%d,seq num=%,d]%n%s",
mClassId,
mFromFeedId,
mToFeedId,
mSequenceNumber,
mMessage));
} // end of toString()
//
// end of Object Method Overrides.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Get methods
//
/**
* Returns the message class.
* @return message class.
*/
public Class messageClass()
{
return (mMessage.getClass());
} // end of messageClass()
/**
* Returns {@code true} if the contained message is a
* system message.
* @return {@code true} if a system message.
*/
public boolean isSystemMessage()
{
return (mMessage.messageType() ==
EMessage.MessageType.SYSTEM);
} // end of isSystemMessage()
/**
* Returns the encapsulated message type.
* @return message type.
*/
public EMessage.MessageType messageType()
{
return (mMessage.messageType());
} // end of messageType()
/**
* Returns the encapsulated message key.
* @return message key.
*/
public EMessageKey messageKey()
{
return (mMessage.key());
} // end of messageKey()
/**
* Returns the unique class identifier.
* @return class identifier.
*/
public int classId()
{
return (mClassId);
} // end of classId()
/**
* Returns the from proxy identifier. If this is a
* {@link ESystemMessage}, then returns {@link #NO_ID}.
* @return the from proxy identifier.
*/
public int fromFeedId()
{
return (mFromFeedId);
} // end of fromFeedId()
/**
* Returns the to proxy identifier. If the destination proxy
* is not known at the time the message was sent, then
* returns {@link #NO_ID}.
* @return the destination proxy identifier.
*/
public int toFeedId()
{
return (mToFeedId);
} // end of toFeedId()
/**
* Returns message sequence number. If the sequence number
* is not set, then returns {@link #NO_ID}.
* @return message sequence number.
*/
public int sequenceNumber()
{
return (mSequenceNumber);
} // end of sequenceNumber()
/**
* Returns the message source or destination address. May
* return {@code null}.
* @return socket address.
*/
public SocketAddress address()
{
return (mAddress);
} // end of address()
/**
* Returns the encapsulated eBus message.
* @return the encapsulated eBus message.
*/
public EMessage message()
{
return (mMessage);
} // end of message()
/**
* Returns encapsulated message's data type.
* @return message data type.
*/
public DataType dataType()
{
return (mDataType);
} // end of messageType()
//
// end of Get methods.
//-----------------------------------------------------------
//-----------------------------------------------------------
// Set methods
//
/**
* Sets message sequence number to the given value
* if not previously set.
* @param n message sequence number.
* @throws IllegalArgumentException
* if {@code n} < zero.
* @throws IllegalStateException
* if {@code sequenceNumber(int)} previously called for this
* message header.
*/
public void sequenceNumber(final int n)
{
if (n < 0)
{
throw (new IllegalArgumentException("n < 0"));
}
if (mSequenceNumber >= 0)
{
throw (
new IllegalStateException(
"sequence number already set"));
}
mSequenceNumber = n;
} // end of sequenceNumber(int)
//
// end of Set methods.
//-----------------------------------------------------------
} // end of class EMessageHeader