org.jscsi.parser.logout

Class LogoutRequestParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.InitiatorMessageParser

org.jscsi.parser.logout.LogoutRequestParser

public final class LogoutRequestParser
extends InitiatorMessageParser

LogoutRequestParser

This class parses a Logout Request message defined in the iSCSI Standard (RFC3720).

The Logout Request is used to perform a controlled closing of a connection.

An initiator MAY use a Logout Request to remove a connection from a session or to close an entire session.

After sending the Logout Request PDU, an initiator MUST NOT send any new iSCSI requests on the closing connection. If the Logout Request is intended to close the session, new iSCSI requests MUST NOT be sent on any of the connections participating in the session.

When receiving a Logout Request with the reason code of "close the connection" or "close the session", the target MUST terminate all pending commands, whether acknowledged via ExpCmdSN or not, on that connection or session respectively.

When receiving a Logout Request with the reason code "remove connection for recovery", the target MUST discard all requests not yet acknowledged via ExpCmdSN that were issued on the specified connection, and suspend all data/status/R2T transfers on behalf of pending commands on the specified connection.

The target then issues the Logout Response and half-closes the TCP connection (sends FIN). After receiving the Logout Response and attempting to receive the FIN (if still possible), the initiator MUST completely close the logging-out connection. For the terminated commands, no additional responses should be expected.

A Logout for a CID may be performed on a different transport connection when the TCP connection for the CID has already been terminated. In such a case, only a logical "closing" of the iSCSI connection for the CID is implied with a Logout.

All commands that were not terminated or not completed (with status) and acknowledged when the connection is closed completely can be reassigned to a new connection if the target supports connection recovery.

If an initiator intends to start recovery for a failing connection, it MUST use the Logout Request to "clean-up" the target end of a failing connection and enable recovery to start, or the Login Request with a non-zero TSIH and the same CID on a new connection for the same effect (see Section 10.14.3 CID). In sessions with a single connection, the connection can be closed and then a new connection reopened. A connection reinstatement login can be used for recovery (see Section 5.3.4 Connection Reinstatement).

A successful completion of a Logout Request with the reason code of "close the connection" or "remove the connection for recovery" results at the target in the discarding of unacknowledged commands received on the connection being logged out. These are commands that have arrived on the connection being logged out, but have not been delivered to SCSI because one or more commands with a smaller CmdSN has not been received by iSCSI. See Section 3.2.2.1 Command Numbering and Acknowledging. The resulting holes the in command sequence numbers will have to be handled by appropriate recovery (see Chapter 6) unless the session is also closed.

The entire logout discussion in this section is also applicable for an implicit Logout realized via a connection reinstatement or session reinstatement. When a Login Request performs an implicit Logout, the implicit Logout is performed as if having the reason codes specified below:

Reason code	Type of implicit Logout
0	session reinstatement
1	connection reinstatement when the operational ErrorRecoveryLevel < 2
2	connection reinstatement when the operational ErrorRecoveryLevel = 2

TotalAHSLength and DataSegmentLength

For this PDU TotalAHSLength and DataSegmentLength MUST be 0.

ExpStatSN

This is the last ExpStatSN value for the connection to be closed.

Implicit termination of tasks

A target implicitly terminates the active tasks due to the iSCSI protocol in the following cases:

1. When a connection is implicitly or explicitly logged out with the reason code of "Close the connection" and there are active tasks allegiant to that connection.
2. When a connection fails and eventually the connection state times out (state transition M1 in Section 7.2.2 State Transition Descriptions for Initiators and Targets) and there are active tasks allegiant to that connection.
3. When a successful recovery Logout is performed while there are active tasks allegiant to that connection, and those tasks eventually time out after the Time2Wait and Time2Retain periods without allegiance reassignment.
4. When a connection is implicitly or explicitly logged out with the reason code of "Close the session" and there are active tasks in that session.

If the tasks terminated in any of the above cases are SCSI tasks, they must be internally terminated as if with CHECK CONDITION status. This status is only meaningful for appropriately handling the internal SCSI state and SCSI side effects with respect to ordering because this status is never communicated back as a terminating status to the initiator. However additional actions may have to be taken at SCSI level depending on the SCSI context as defined by the SCSI standards (e.g., queued commands and ACA, in cases a), b), and c), after the tasks are terminated, the target MUST report a Unit Attention condition on the next command processed on any connection for each affected I_T_L nexus with the status of CHECK CONDITION, and the ASC/ASCQ value of 47h/7Fh - "SOME COMMANDS CLEARED BY ISCSI PROTOCOL EVENT" - etc. - see [SAM2] and [SPC3]).

Author:

Volker Wildi

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	LogoutRequestParser.LogoutReasonCode This enumeration defines all the Logout Reasons Codes, which are allowed in a iSCSI Logout Request message (RFC3720).

Field Summary

Fields inherited from class org.jscsi.parser.InitiatorMessageParser

commandSequenceNumber, expectedStatusSequenceNumber

Fields inherited from class org.jscsi.parser.AbstractMessageParser

logicalUnitNumber, protocolDataUnit

Constructor Summary

Constructors

Constructor and Description
LogoutRequestParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty LogoutRequestParser object.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	checkIntegrity() This method checks, if all parsed fields are valid.
void	clear() This method sets all settings to their initial values.
protected void	deserializeBytes1to3(int line) Parse the bytes 1 till 3 in the Basic Header Segment.
protected void	deserializeBytes20to23(int line) Parse the bytes 20 till 23 in the Basic Header Segment.
short	getConnectionID() This is the Connection ID of the connection to be closed (including closing the TCP stream).
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
LogoutRequestParser.LogoutReasonCode	getReasonCode() Returns the reason for the logout.
protected int	serializeBytes1to3() Serializes the bytes 1 till 3 in the Basic Header Segment.
protected int	serializeBytes20to23() Serializes the bytes 20 till 23 in the Basic Header Segment.
void	setConnectionID(short newCID) Sets the new Connection ID of this LogoutRequestParser object.
void	setReasonCode(LogoutRequestParser.LogoutReasonCode newReasonCode) Sets the Reason Code of this LogoutRequestParser object.
String	toString() This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Methods inherited from class org.jscsi.parser.InitiatorMessageParser

deserializeBytes24to27, deserializeBytes28to31, deserializeBytes32to35, deserializeBytes36to39, deserializeBytes40to43, deserializeBytes44to47, getCommandSequenceNumber, getExpectedStatusSequenceNumber, getShortInfo, incrementSequenceNumber, serializeBytes24to27, serializeBytes28to31, serializeBytes32to35, serializeBytes36to39, serializeBytes40to43, serializeBytes44to47, setCommandSequenceNumber, setExpectedStatusSequenceNumber

Methods inherited from class org.jscsi.parser.AbstractMessageParser

canContainAdditionalHeaderSegments, canHaveDigests, deserializeBytes12to15, deserializeBytes8to11, getLogicalUnitNumber, serializeBytes12to15, serializeBytes8to11, setLogicalUnitNumber

Methods inherited from class java.lang.Object

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

Constructor Detail

LogoutRequestParser

public LogoutRequestParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty LogoutRequestParser object.

Parameters:

initProtocolDataUnit - The reference ProtocolDataUnit instance, which contains this LogoutRequestParser subclass object.

Method Detail

toString

public final String toString()

This method concatenate all the fields of a derived parser to allow an easy generation of debug informations.

Overrides:

toString in class InitiatorMessageParser

Returns:

The debug formatted string.

getDataSegmentFormat

public final DataSegmentFactory.DataSegmentFormat getDataSegmentFormat()

If this method returns true, hen it indicates that the data segment data is interpreted as binary data. Else the data segment data must be interpreted as Text Format.

Specified by:

getDataSegmentFormat in class AbstractMessageParser

Returns:

Returns a format defined by the DataSegmentFormat enumeration.

See Also:

DataSegmentFactory.DataSegmentFormat

clear

public final void clear()

This method sets all settings to their initial values.

Overrides:

clear in class InitiatorMessageParser

getConnectionID

public final short getConnectionID()

This is the Connection ID of the connection to be closed (including closing the TCP stream). This field is only valid if the reason code is not "close the session".

Returns:

The Connection ID of this LogoutRequestParser object.

getReasonCode

public final LogoutRequestParser.LogoutReasonCode getReasonCode()

Returns the reason for the logout.

Returns:

The reason code for this logout request.

See Also:

LogoutRequestParser.LogoutReasonCode

setConnectionID

public final void setConnectionID(short newCID)

Sets the new Connection ID of this LogoutRequestParser object.

Parameters:

newCID - The new Connection ID.

setReasonCode

public final void setReasonCode(LogoutRequestParser.LogoutReasonCode newReasonCode)

Sets the Reason Code of this LogoutRequestParser object.

Parameters:

newReasonCode - The new Reason Code.

deserializeBytes1to3

protected final void deserializeBytes1to3(int line)
                                   throws InternetSCSIException

Parse the bytes 1 till 3 in the Basic Header Segment.

Overrides:

deserializeBytes1to3 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

deserializeBytes20to23

protected final void deserializeBytes20to23(int line)
                                     throws InternetSCSIException

Parse the bytes 20 till 23 in the Basic Header Segment.

Overrides:

deserializeBytes20to23 in class InitiatorMessageParser

Parameters:

line - The actual line

Throws:

InternetSCSIException - If any violation of the iSCSI-Standard emerge.

checkIntegrity

protected final void checkIntegrity()
                             throws InternetSCSIException

This method checks, if all parsed fields are valid. Because there are several fields, which are reserved for future versions, and these must be zero. Is this the case an exception will be thrown.

Specified by:

checkIntegrity in class AbstractMessageParser

Throws:

InternetSCSIException - If the integrity is violated.

serializeBytes1to3

protected final int serializeBytes1to3()

Serializes the bytes 1 till 3 in the Basic Header Segment.

Overrides:

serializeBytes1to3 in class InitiatorMessageParser

Returns:

The serialized byte representation.

serializeBytes20to23

protected final int serializeBytes20to23()

Serializes the bytes 20 till 23 in the Basic Header Segment.

Overrides:

serializeBytes20to23 in class InitiatorMessageParser

Returns:

The serialized byte representation.