org.jscsi.parser.scsi

Class SCSIResponseParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.TargetMessageParser

org.jscsi.parser.scsi.SCSIResponseParser

public class SCSIResponseParser
extends TargetMessageParser

SCSIResponseParser

This class parses a SCSI Response message defined in the iSCSI Standard (RFC3720).

StatSN - Status Sequence Number

StatSN is a Sequence Number that the target iSCSI layer generates per connection and that in turn, enables the initiator to acknowledge status reception. StatSN is incremented by 1 for every response/status sent on a connection except for responses sent as a result of a retry or SNACK. In the case of responses sent due to a retransmission request, the StatSN MUST be the same as the first time the PDU was sent unless the connection has since been restarted.

ExpCmdSN - Next Expected CmdSN from this Initiator

ExpCmdSN is a Sequence Number that the target iSCSI returns to the initiator to acknowledge command reception. It is used to update a local variable with the same name. An ExpCmdSN equal to MaxCmdSN + 1 indicates that the target cannot accept new commands.

MaxCmdSN - Maximum CmdSN from this Initiator

MaxCmdSN is a Sequence Number that the target iSCSI returns to the initiator to indicate the maximum CmdSN the initiator can send. It is used to update a local variable with the same name. If MaxCmdSN is equal to ExpCmdSN - 1, this indicates to the initiator that the target cannot receive any additional commands. When MaxCmdSN changes at the target while the target has no pending PDUs to convey this information to the initiator, it MUST generate a NOP-IN to carry the new MaxCmdSN.

iSCSI targets MUST support and enable autosense. If Status is CHECK CONDITION (0x02), then the Data Segment MUST contain sense data for the failed command.
For some iSCSI responses, the response data segment MAY contain some response related information, (e.g., for a target failure, it may contain a vendor specific detailed description of the failure).

Author:

Volker Wildi, University of Konstanz

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SCSIResponseParser.ServiceResponse This enumerations defines all valid service responses, which are defined in the iSCSI Standard (RFC 3720).

Field Summary

Fields inherited from class org.jscsi.parser.TargetMessageParser

expectedCommandSequenceNumber, maximumCommandSequenceNumber, statusSequenceNumber

Fields inherited from class org.jscsi.parser.AbstractMessageParser

logicalUnitNumber, protocolDataUnit

Constructor Summary

Constructors

Constructor and Description
SCSIResponseParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty SCSIResponseParser 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.
protected void	deserializeBytes36to39(int line) Parse the bytes 36 till 39 in the Basic Header Segment.
protected void	deserializeBytes40to43(int line) Parse the bytes 40 till 43 in the Basic Header Segment.
protected void	deserializeBytes44to47(int line) Parse the bytes 44 till 47 in the Basic Header Segment.
int	getBidirectionalReadResidualCount() The Bidirectional Read Residual Count field MUST be valid in the case where either the u bit or the o bit is set.
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
int	getExpectedDataSequenceNumber() The number of R2T and Data-In (read) PDUs the target has sent for the command.
int	getResidualCount() The Residual Count field MUST be valid in the case where either the U bit or the O bit is set.
SCSIResponseParser.ServiceResponse	getResponse() This field contains the iSCSI service response.
int	getSNACKTag() This field contains a copy of the SNACK Tag of the last SNACK Tag accepted by the target on the same connection and for the command for which the response is issued.
SCSIStatus	getStatus() The Status field is used to report the SCSI status of the command (as specified in [SAM2]) and is only valid if the Response Code is Command Completed at target.
boolean	isBidirectionalReadResidualOverflow() Returns the status of the Bidirectional Read Residual Overflow flag.
boolean	isBidirectionalReadResidualUnderflow() Returns the status of the Bidirectional Read Residual Underflow flag.
boolean	isResidualOverflow() Returns the status of the Residual Overflow flag.
boolean	isResidualUnderflow() Returns the status of the Residual Underflow flag.
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.
protected int	serializeBytes36to39() Serializes the bytes 36 till 39 in the Basic Header Segment.
protected int	serializeBytes40to43() Serializes the bytes 40 till 43 in the Basic Header Segment.
protected int	serializeBytes44to47() Serializes the bytes 44 till 47 in the Basic Header Segment.
void	setBidirectionalReadResidualCount(int bidirectionalReadResidualCount)
void	setBidirectionalReadResidualOverflow(boolean bidirectionalReadResidualOverflow)
void	setBidirectionalReadResidualUnderflow(boolean bidirectionalReadResidualUnderflow)
void	setExpectedDataSequenceNumber(int expectedDataSequenceNumber)
void	setResidualCount(int residualCount)
void	setResidualOverflow(boolean residualOverflow)
void	setResidualUnderflow(boolean residualUnderflow)
void	setResponse(SCSIResponseParser.ServiceResponse response)
void	setSNACKTag(int snackTag)
void	setStatus(SCSIStatus status)
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.TargetMessageParser

deserializeBytes24to27, deserializeBytes28to31, deserializeBytes32to35, getExpectedCommandSequenceNumber, getMaximumCommandSequenceNumber, getShortInfo, getStatusSequenceNumber, incrementSequenceNumber, serializeBytes24to27, serializeBytes28to31, serializeBytes32to35, setExpectedCommandSequenceNumber, setMaximumCommandSequenceNumber, setStatusSequenceNumber

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

SCSIResponseParser

public SCSIResponseParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty SCSIResponseParser object.

Parameters:

initProtocolDataUnit - The reference ProtocolDataUnit instance, which contains this SCSIResponseParser 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 TargetMessageParser

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 TargetMessageParser

getBidirectionalReadResidualCount

public final int getBidirectionalReadResidualCount()

The Bidirectional Read Residual Count field MUST be valid in the case where either the u bit or the o bit is set. If neither bit is set, the Bidirectional Read Residual Count field is reserved. Targets may set the Bidirectional Read Residual Count and initiators may use it when the response code is "completed at target". If the o bit is set, the Bidirectional Read Residual Count indicates the number of bytes that were not transferred to the initiator because the initiator’s Expected Bidirectional Read Transfer Length was not sufficient. If the u bit is set, the Bidirectional Read Residual Count indicates the number of bytes that were not transferred to the initiator out of the number of bytes expected to be transferred.

Returns:

The bidirectional read residual count of this SCSIResponseParser object.

getExpectedDataSequenceNumber

public final int getExpectedDataSequenceNumber()

The number of R2T and Data-In (read) PDUs the target has sent for the command.

This field MUST be 0 if the response code is not Command Completed at Target or the target sent no Data-In PDUs for the command.

Returns:

The expected data sequence number of this SCSIResponseParser object.

isBidirectionalReadResidualOverflow

public final boolean isBidirectionalReadResidualOverflow()

Returns the status of the Bidirectional Read Residual Overflow flag. In this case, the Bidirectional Read Residual Count indicates the number of bytes that were not transferred to the initiator because the initiator’s Expected Bidirectional Read Data Transfer Length was not sufficient.

Returns:

true, if it is set; else false.

isBidirectionalReadResidualUnderflow

public final boolean isBidirectionalReadResidualUnderflow()

Returns the status of the Bidirectional Read Residual Underflow flag. In this case, the Bidirectional Read Residual Count indicates the number of bytes that were not transferred to the initiator out of the number of bytes expected to be transferred.

Returns:

true, if it is set; else false.

getResidualCount

public final int getResidualCount()

The Residual Count field MUST be valid in the case where either the U bit or the O bit is set. If neither bit is set, the Residual Count field is reserved. Targets may set the residual count and initiators may use it when the response code is "completed at target" (even if the status returned is not GOOD). If the O bit is set, the Residual Count indicates the number of bytes that were not transferred because the initiator’s Expected Data Transfer Length was not sufficient. If the U bit is set, the Residual Count indicates the number of bytes that were not transferred out of the number of bytes expected to be transferred.

Returns:

The residual count of this SCSIResponseParser object.

isResidualOverflow

public final boolean isResidualOverflow()

Returns the status of the Residual Overflow flag. In this case, the Residual Count indicates the number of bytes that were not transferred because the initiator’s Expected Data Transfer Length was not sufficient. For a bidirectional operation, the Residual Count contains the residual for the write operation.

Returns:

true, if it is set; else false.

isResidualUnderflow

public final boolean isResidualUnderflow()

Returns the status of the Residual Underflow flag. In this case, the Residual Count indicates the number of bytes that were not transferred out of the number of bytes that were expected to be transferred. For a bidirectional operation, the Residual Count contains the residual for the write operation.

Returns:

true, if it is set; else false.

getResponse

public final SCSIResponseParser.ServiceResponse getResponse()

This field contains the iSCSI service response.

All other response codes are reserved.

The Response is used to report a Service Response. The mapping of the response code into a SCSI service response code value, if needed, is outside the scope of this document. However, in symbolic terms response value 0x00 maps to the SCSI service response (see [SAM2] and [SPC3]) of TASK COMPLETE or LINKED COMMAND COMPLETE. All other Response values map to the SCSI service response of SERVICE DELIVERY OR TARGET FAILURE.

If a PDU that includes SCSI status (Response PDU or Data-In PDU including status) does not arrive before the session is terminated, the SCSI service response is SERVICE DELIVERY OR TARGET FAILURE. A non-zero Response field indicates a failure to execute the command in which case the Status and Flag fields are undefined.

Returns:

The service response of this SCSIResponseParser object.

See Also:

SCSIResponseParser.ServiceResponse

getSNACKTag

public final int getSNACKTag()

This field contains a copy of the SNACK Tag of the last SNACK Tag accepted by the target on the same connection and for the command for which the response is issued. Otherwise it is reserved and should be set to 0.

After issuing a R-Data SNACK the initiator must discard any SCSI status unless contained in an SCSI Response PDU carrying the same SNACK Tag as the last issued R-Data SNACK for the SCSI command on the current connection.

For a detailed discussion on R-Data SNACK see Section 10.16 SNACK Request.

Returns:

The SNACK Tag of this SCSIResponseParser object.

getStatus

public final SCSIStatus getStatus()

The Status field is used to report the SCSI status of the command (as specified in [SAM2]) and is only valid if the Response Code is Command Completed at target.

Returns:

The status field of this SCSIResponseParser object.

See Also:

SCSIStatus

setBidirectionalReadResidualCount

public final void setBidirectionalReadResidualCount(int bidirectionalReadResidualCount)

setBidirectionalReadResidualOverflow

public final void setBidirectionalReadResidualOverflow(boolean bidirectionalReadResidualOverflow)

setBidirectionalReadResidualUnderflow

public final void setBidirectionalReadResidualUnderflow(boolean bidirectionalReadResidualUnderflow)

setExpectedDataSequenceNumber

public final void setExpectedDataSequenceNumber(int expectedDataSequenceNumber)

setResidualCount

public final void setResidualCount(int residualCount)

setResidualOverflow

public final void setResidualOverflow(boolean residualOverflow)

setResidualUnderflow

public final void setResidualUnderflow(boolean residualUnderflow)

setResponse

public void setResponse(SCSIResponseParser.ServiceResponse response)

setSNACKTag

public final void setSNACKTag(int snackTag)

setStatus

public final void setStatus(SCSIStatus status)

deserializeBytes1to3

protected final void deserializeBytes1to3(int line)
                                   throws InternetSCSIException

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

Overrides:

deserializeBytes1to3 in class TargetMessageParser

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 TargetMessageParser

Parameters:

line - The actual line

Throws:

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

deserializeBytes36to39

protected final void deserializeBytes36to39(int line)
                                     throws InternetSCSIException

Parse the bytes 36 till 39 in the Basic Header Segment.

Overrides:

deserializeBytes36to39 in class TargetMessageParser

Parameters:

line - The actual line

Throws:

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

deserializeBytes40to43

protected final void deserializeBytes40to43(int line)
                                     throws InternetSCSIException

Parse the bytes 40 till 43 in the Basic Header Segment.

Overrides:

deserializeBytes40to43 in class TargetMessageParser

Parameters:

line - The actual line

Throws:

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

deserializeBytes44to47

protected final void deserializeBytes44to47(int line)
                                     throws InternetSCSIException

Parse the bytes 44 till 47 in the Basic Header Segment.

Overrides:

deserializeBytes44to47 in class TargetMessageParser

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 TargetMessageParser

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 TargetMessageParser

Returns:

The serialized byte representation.

serializeBytes36to39

protected final int serializeBytes36to39()

Serializes the bytes 36 till 39 in the Basic Header Segment.

Overrides:

serializeBytes36to39 in class TargetMessageParser

Returns:

The serialized byte representation.

serializeBytes40to43

protected final int serializeBytes40to43()

Serializes the bytes 40 till 43 in the Basic Header Segment.

Overrides:

serializeBytes40to43 in class TargetMessageParser

Returns:

The serialized byte representation.

serializeBytes44to47

protected final int serializeBytes44to47()

Serializes the bytes 44 till 47 in the Basic Header Segment.

Overrides:

serializeBytes44to47 in class TargetMessageParser

Returns:

The serialized byte representation.