Class CMFChannel

java.lang.Object

java.util.Observable

org.jpos.iso.BaseChannel

org.jpos.iso.channel.CMFChannel

All Implemented Interfaces:

Cloneable, Configurable, ExceptionHandlerAware, BaseChannelMBean, ClientChannel, FactoryChannel, FilteredChannel, ISOChannel, ISOSource, ServerChannel, ISOMsgMetrics.Source, LogSource

public class CMFChannel
extends BaseChannel

ISOChannel implementation for the jPOS-CMF framing. This channel uses a 3-byte big-endian length prefix (24-bit unsigned) and no additional message header.

Keep-alive handling

A zero-length frame is treated as a keep-alive. When a keep-alive is received and either replyKeepAlive is enabled or BaseChannel.isExpectKeepAlive() returns true, the channel echoes the keep-alive back to the peer.

Configuration

• reply-keepalive (boolean, default true): Whether to echo a received keep-alive (zero-length frame) back to the peer.
• max-keepalives-in-a-row (integer, default 0): Maximum number of consecutive keep-alives allowed while waiting for a non-zero length frame. A value of 0 disables the limit (unlimited), preserving legacy behavior.

Since:

3.0.1

See Also:

• ISOMsg
• ISOException
• ISOChannel
• ISOPackager

Field Summary

Fields inherited from class BaseChannel

cnt, header, incomingFilters, logger, originalRealm, outgoingFilters, overrideHeader, packager, realm, serverIn, serverInLock, serverOut, serverOutLock, serverSocket, socketFactory, usable

Modifier and Type	Field	Description
protected int[]	cnt	Message counters array.
protected byte[]	header	Message header bytes.
protected List<ISOFilter>	incomingFilters	Incoming and outgoing filter chains.
protected Logger	logger	The logger for this channel.
protected String	originalRealm	The original realm before any override.
protected List<ISOFilter>	outgoingFilters	Incoming and outgoing filter chains.
protected boolean	overrideHeader	When true, this channel's own header overrides the message's header.
protected ISOPackager	packager	The packager used to pack/unpack ISO messages.
protected String	realm	The realm string for this channel.
protected DataInputStream	serverIn	Input stream for reading from the connected socket.
protected Lock	serverInLock	Lock guarding BaseChannel.serverIn and read operations.
protected DataOutputStream	serverOut	Output stream for writing to the connected socket.
protected Lock	serverOutLock	Lock guarding BaseChannel.serverOut and write operations.
protected ServerSocket	serverSocket	Server socket used when this channel acts as a server.
protected ISOClientSocketFactory	socketFactory	Optional factory for creating client sockets.
protected boolean	usable	Whether this channel is in a usable state.

Fields inherited from interface ISOChannel

CONNECT, RX, SIZEOF_CNT, TX

Modifier and Type	Field	Description
static final int	CONNECT	Counter index for connection events.
static final int	RX	Counter index for received messages.
static final int	SIZEOF_CNT	Number of counters maintained by this channel.
static final int	TX	Counter index for transmitted messages.

Constructor Summary

Constructors

Constructor	Description
CMFChannel()	Creates an unconfigured CMFChannel.
CMFChannel(String host, int port, ISOPackager p)	Constructs a client CMFChannel.
CMFChannel(ISOPackager p)	Constructs a server CMFChannel.
CMFChannel(ISOPackager p, ServerSocket serverSocket)	Constructs a server CMFChannel associated with an existing ServerSocket.

Method Summary

Modifier and Type	Method	Description
protected int	getHeaderLength()	Returns the channel header length.
int	getMaxPacketLength()	Returns the maximum packet length supported by this channel.
protected int	getMessageLength()	Reads the CMF message length prefix.
protected void	sendMessageHeader(ISOMsg m, int len)	Sends the message header (no-op).
protected void	sendMessageLength(int len)	Sends the CMF message length prefix.
void	setConfiguration(Configuration cfg)	Applies configuration to this channel.

Methods inherited from class BaseChannel

accept, addFilter, addFilter, addIncomingFilter, addOutgoingFilter, applyIncomingFilters, applyIncomingFilters, applyOutgoingFilters, applyTimeout, clone, closeSocket, connect, connect, createISOMsg, createMsg, disconnect, getBytes, getChannel, getConfiguration, getCounters, getDynamicHeader, getDynamicPackager, getDynamicPackager, getDynamicPackager, getExceptionHandlers, getHeader, getHeaderLength, getHeaderLength, getHost, getIncomingFilters, getISOMsgMetrics, getLogger, getMessage, getMessageTrailer, getMessageTrailler, getName, getOriginalRealm, getOutgoingFilters, getPackager, getPort, getRealm, getServerSocket, getSocket, getSocketFactory, getSoLingerSeconds, getTimeout, incrementMsgInCounter, incrementMsgOutCounter, isConnected, isExpectKeepAlive, isOverrideHeader, isRejected, isSoLingerOn, newSocket, newSocket, pack, postConnectHook, readHeader, receive, reconnect, removeFilter, removeFilter, removeIncomingFilter, removeOutgoingFilter, resetCounters, send, send, sendKeepAlive, sendMessage, sendMessageTrailer, sendMessageTrailler, sendMessageTrailler, setHeader, setHeader, setHost, setHost, setIncomingFilters, setISOMsgMetrics, setLocalAddress, setLogger, setMaxPacketLength, setName, setOutgoingFilters, setOverrideHeader, setPackager, setPort, setServerSocket, setSocketFactory, setSoLinger, setTimeout, setUsable, shouldIgnore, streamReceive, toEndpoint, unpack

Modifier and Type	Method	Description
void	accept(ServerSocket s)	Accepts connection
void	addFilter(ISOFilter filter)	Adds a filter to this channel.
void	addFilter(ISOFilter filter, int direction)	Adds a filter to this channel.
void	addIncomingFilter(ISOFilter filter)	Adds a filter to the incoming filter chain.
void	addOutgoingFilter(ISOFilter filter)	Adds a filter to the outgoing filter chain.
protected ISOMsg	applyIncomingFilters(ISOMsg m, byte[] header, byte[] image, LogEvent evt)	Applies all registered incoming filters with the raw message header and image.
protected ISOMsg	applyIncomingFilters(ISOMsg m, LogEvent evt)	Applies all registered incoming filters to the given message.
protected ISOMsg	applyOutgoingFilters(ISOMsg m, LogEvent evt)	Applies all registered outgoing filters to the given message.
protected void	applyTimeout()	sets timeout, and also keep alive
Object	clone()	Returns a clone of this channel.
protected void	closeSocket()	Closes the underlying socket.
void	connect()	Connects client ISOChannel to server
protected void	connect(Socket socket)	setup I/O Streams from socket
protected ISOMsg	createISOMsg()	Creates a new ISOMsg instance; may be overridden to return a subclass.
protected ISOMsg	createMsg()	support old factory method name for backward compatibility
void	disconnect()	disconnects the TCP/IP session.
int	getBytes(byte[] b)	Low level receive
static ISOChannel	getChannel(String name)	Retrieves a channel instance by name from the NameRegistrar.
Configuration	getConfiguration()	Returns the current configuration for this channel.
int[]	getCounters()	Returns the message counters array.
protected ISOHeader	getDynamicHeader(byte[] image)	Allow subclasses to override the Default header on incoming messages.
protected ISOPackager	getDynamicPackager(byte[] image)	allow subclasses to override default packager on incoming messages
protected ISOPackager	getDynamicPackager(byte[] header, byte[] image)	allow subclasses to override default packager on incoming messages
protected ISOPackager	getDynamicPackager(ISOMsg m)	allow subclasses to override default packager on outgoing messages
Map<Class<? extends Exception>, List<ExceptionHandler>>	getExceptionHandlers()	Returns the map of targeted exception handlers, keyed by exception class.
byte[]	getHeader()	Returns the message header bytes.
protected int	getHeaderLength(byte[] b)	Returns the header length for the given raw message bytes.
protected int	getHeaderLength(ISOMsg m)	Returns the header length for the given ISO message.
String	getHost()	Returns the remote host this client channel connects to.
Collection<ISOFilter>	getIncomingFilters()	Returns all filters in the incoming filter chain.
ISOMsgMetrics	getISOMsgMetrics()	Returns the attached ISOMsgMetrics.
Logger	getLogger()	Returns the Logger associated with this source.
protected void	getMessage(byte[] b, int offset, int len)	Reads raw message bytes from the stream into the given buffer.
protected void	getMessageTrailer(ISOMsg m)	Reads the message trailer from the stream and optionally stores it in the given message.
protected void	getMessageTrailler()	Deprecated. use BaseChannel.getMessageTrailer(ISOMsg) instead.
String	getName()	Returns this channel's registered name.
String	getOriginalRealm()	Returns the original realm before any override was applied.
Collection<ISOFilter>	getOutgoingFilters()	Returns all filters in the outgoing filter chain.
ISOPackager	getPackager()	Returns the packager used to pack/unpack ISO messages on this channel.
int	getPort()	Returns the remote port this client channel connects to.
String	getRealm()	Returns the log realm associated with this source.
ServerSocket	getServerSocket()	Returns the current server socket.
Socket	getSocket()	Returns the current connected socket.
ISOClientSocketFactory	getSocketFactory()	Gets the ISOClientSocketFactory (may be null)
int	getSoLingerSeconds()	Returns the SO_LINGER timeout in seconds.
int	getTimeout()	Returns the socket read timeout in milliseconds.
protected void	incrementMsgInCounter(ISOMsg m)	Increments the incoming message counter for the given message.
protected void	incrementMsgOutCounter(ISOMsg m)	Increments the outgoing message counter for the given message.
boolean	isConnected()	Indicates whether this source is currently connected and able to send messages.
boolean	isExpectKeepAlive()	Returns whether this channel expects keep-alive messages.
boolean	isOverrideHeader()	Returns whether the channel header overrides the message header.
protected boolean	isRejected(byte[] b)	Returns whether the given raw message should be rejected.
boolean	isSoLingerOn()	Returns whether SO_LINGER is enabled on the socket.
protected Socket	newSocket(String[] hosts, int[] ports, LogEvent evt)	Creates a new socket connected to one of the given hosts/ports.
protected Socket	newSocket(String host, int port)	factory method pattern (as suggested by Vincent.Greene@amo.com)
protected byte[]	pack(ISOMsg m)	Packs the given ISOMsg into raw bytes using this channel's packager.
protected void	postConnectHook()	Hook called after a successful connection.
protected byte[]	readHeader(int hLen)	Reads in a message header.
ISOMsg	receive()	Waits and receive an ISOMsg over the TCP/IP session
void	reconnect()	Issues a disconnect followed by a connect
void	removeFilter(ISOFilter filter)	Removes a filter from this channel.
void	removeFilter(ISOFilter filter, int direction)	Removes a filter from this channel.
void	removeIncomingFilter(ISOFilter filter)	Removes a filter from the incoming filter chain.
void	removeOutgoingFilter(ISOFilter filter)	Removes a filter from the outgoing filter chain.
void	resetCounters()	reset stat info
void	send(byte[] b)	sends a byte[] over the TCP/IP session
void	send(ISOMsg m)	Sends the specified ISOMsg over this ISOChannel.
void	sendKeepAlive()	Sends a high-level keep-alive message (zero length)
protected void	sendMessage(byte[] b, int offset, int len)	Writes the given bytes to the output stream.
protected void	sendMessageTrailer(ISOMsg m, byte[] b)	Sends the message trailer bytes.
protected void	sendMessageTrailler(ISOMsg m, byte[] b)	Deprecated. use BaseChannel.sendMessageTrailer(ISOMsg, byte[]) instead.
protected void	sendMessageTrailler(ISOMsg m, int len)	Deprecated. use sendMessageTrailer(ISOMsg m, byte[] b) instead.
void	setHeader(byte[] header)	Sets the message header bytes for this channel.
void	setHeader(String header)	Sets the message header from a hex string.
void	setHost(String host)	Sets the remote host name or address.
void	setHost(String host, int port)	initialize an ISOChannel
void	setIncomingFilters(Collection filters)	Replaces the entire incoming filter chain with the given collection.
void	setISOMsgMetrics(ISOMsgMetrics metrics)	Sets the ISOMsgMetrics instance.
void	setLocalAddress(String iface, int port)	initialize an ISOChannel
void	setLogger(Logger logger, String realm)	Attaches a Logger and realm to this log source.
void	setMaxPacketLength(int maxPacketLength)	Sets the maximum packet length accepted by this channel.
void	setName(String name)	associates this ISOChannel with a name using NameRegistrar
void	setOutgoingFilters(Collection filters)	Replaces the entire outgoing filter chain with the given collection.
void	setOverrideHeader(boolean overrideHeader)	Controls whether this channel's own header overrides the message header.
void	setPackager(ISOPackager p)	set Packager for channel
void	setPort(int port)	Sets the remote port number.
void	setServerSocket(ServerSocket sock)	Associates this ISOChannel with a server socket
void	setSocketFactory(ISOClientSocketFactory socketFactory)	Sets the specified Socket Factory to create sockets
void	setSoLinger(boolean on, int linger)	Socket SO_LINGER option to use when closing the socket.
void	setTimeout(int timeout)	sets socket timeout (as suggested by Leonard Thomas <leonard@rhinosystemsinc.com>)
void	setUsable(boolean b)	Marks this channel as usable or not; a non-usable channel will not accept messages.
protected boolean	shouldIgnore(byte[] b)	Returns whether the given raw message should be silently ignored.
protected byte[]	streamReceive()	Reads raw bytes from the stream for protocols without explicit length framing.
protected String	toEndpoint(Socket socket)	Returns a human-readable endpoint string for the given socket.
protected void	unpack(ISOMsg m, byte[] b)	Unpacks raw bytes into the given ISOMsg using this channel's packager.

Methods inherited from class Observable

addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged

Methods inherited from class Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface ExceptionHandlerAware

addHandler, addHandler, handle, removeHandler, removeHandler, removeHandlers

Modifier and Type	Method	Description
default void	addHandler(ExceptionHandler handler)	Add a handler to the default pipeline.
default void	addHandler(ExceptionHandler handler, Class<? extends Exception> clazz)	Add a handler to an exception specific pipeline.
default Exception	handle(Exception e)	Execute the pipeline by starting with the specific pipeline for the exception followed by the default pipeline.
default void	removeHandler(ExceptionHandler handler)	Remove a handler from the default pipeline.
default void	removeHandler(ExceptionHandler handler, Class<? extends Exception> clazz)	Remove a handler from an exception specific handler pipeline.
default void	removeHandlers(Class<? extends Exception> clazz)	Remove all handler for a specific exception handling pipeline.

Constructor Details

CMFChannel

public CMFChannel()

Creates an unconfigured CMFChannel. The caller is expected to set the packager/connection parameters through the usual BaseChannel configuration and/or setters before use.

CMFChannel

public CMFChannel(String host,
 int port,
 ISOPackager p)

Constructs a client CMFChannel.

Parameters:

host - server TCP address or hostname.

port - server TCP port number.

p - the ISOPackager used to pack/unpack ISOMsgs.

See Also:

• ISOPackager

CMFChannel

public CMFChannel(ISOPackager p)
           throws IOException

Constructs a server CMFChannel. This constructor creates a ServerSocket internally (as per BaseChannel) and waits for inbound connections when BaseChannel.accept(java.net.ServerSocket) is invoked.

Parameters:

p - the ISOPackager used to pack/unpack ISOMsgs.

Throws:

IOException - if the underlying server socket cannot be created.

See Also:

• ISOPackager

CMFChannel

public CMFChannel(ISOPackager p,
 ServerSocket serverSocket)
           throws IOException

Constructs a server CMFChannel associated with an existing ServerSocket.

Parameters:

p - the ISOPackager used to pack/unpack ISOMsgs.

serverSocket - the server socket used to accept a connection.

Throws:

IOException - if an I/O error occurs while initializing the channel.

See Also:

• ISOPackager

Method Details

sendMessageLength

protected void sendMessageLength(int len)
                          throws IOException

Sends the CMF message length prefix. The CMF framing uses a 3-byte big-endian length prefix (24-bit unsigned).

Overrides:

sendMessageLength in class BaseChannel

Parameters:

len - the packed message length in bytes.

Throws:

IOException - if an I/O error occurs writing to the socket output stream or if len is outside the valid range (0..0xFFFFFF).

getMessageLength

protected int getMessageLength()
                        throws IOException,
ISOException

Reads the CMF message length prefix. Reads a 3-byte big-endian length value. A zero-length frame is treated as a keep-alive. When a keep-alive is received and either replyKeepAlive is enabled or BaseChannel.isExpectKeepAlive() is true, the keep-alive is echoed back to the peer. The method continues reading until a non-zero length is obtained.

If max-keepalives-in-a-row is configured to a value greater than 0, the method will fail after receiving more than that number of consecutive keep-alives without a subsequent non-zero length frame.

Overrides:

getMessageLength in class BaseChannel

Returns:

the packed message length in bytes (always > 0).

Throws:

IOException - if an I/O error occurs reading from the socket input stream, or if too many consecutive keep-alives are received (when limited).

ISOException - if the channel detects an ISO-level framing/processing error.

getHeaderLength

protected int getHeaderLength()

Returns the channel header length. CMF framing does not include a separate message header beyond the 3-byte length prefix.

Overrides:

getHeaderLength in class BaseChannel

Returns:

0.

sendMessageHeader

protected void sendMessageHeader(ISOMsg m,
 int len)

Sends the message header (no-op). CMF framing does not define a message header; only the length prefix is used.

Overrides:

sendMessageHeader in class BaseChannel

Parameters:

m - the message being sent.

len - the packed message length in bytes.

setConfiguration

public void setConfiguration(Configuration cfg)
                      throws ConfigurationException

Applies configuration to this channel. In addition to the base BaseChannel configuration, this method reads:

• reply-keepalive (boolean, default true).
• max-keepalives-in-a-row (integer, default 0).

Specified by:

setConfiguration in interface Configurable

Overrides:

setConfiguration in class BaseChannel

Parameters:

cfg - the configuration source.

Throws:

ConfigurationException - if configuration cannot be applied.

getMaxPacketLength

public int getMaxPacketLength()

Returns the maximum packet length supported by this channel. CMF framing uses a 3-byte unsigned length prefix (24-bit). Therefore, the maximum representable non-zero payload length is 0xFFFFFF (16,777,215 bytes).

Overrides:

getMaxPacketLength in class BaseChannel

Returns:

the maximum packet length, in bytes.