org.jscsi.parser.data

Class DataInParser

java.lang.Object

org.jscsi.parser.AbstractMessageParser

org.jscsi.parser.TargetMessageParser

org.jscsi.parser.data.DataInParser

public class DataInParser
extends TargetMessageParser

This class parses a Data-In message defined in the iSCSI Standard (RFC3720).

Author:

Volker Wildi

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
DataInParser(ProtocolDataUnit initProtocolDataUnit) Default constructor, creates a new, empty DataInParser 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	getBufferOffset() The Buffer Offset field contains the offset of this PDU payload data within the complete data transfer.
DataSegmentFactory.DataSegmentFormat	getDataSegmentFormat() If this method returns true, hen it indicates that the data segment data is interpreted as binary data.
int	getDataSequenceNumber() For input (read) or bidirectional Data-In PDUs, the DataSN is the input PDU number within the data transfer for the command identified by the Initiator Task Tag.
int	getResidualCount() The Residual Count field MUST be valid in the case where either the U bit or the O bit is set.
String	getShortInfo() Returns the short version of the used sequence numbers of this parser instance.
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.
int	getTargetTaskTag() On outgoing data, the Target Transfer Tag is provided to the target if the transfer is honoring an R2T.
boolean	incrementSequenceNumber() This AbstractMessageParser instance affects the incrementation of the Expected Status Sequence Number.
boolean	isAcknowledgeFlag() For sessions with ErrorRecoveryLevel 1 or higher, the target sets this bit to 1 to indicate that it requests a positive acknowledgement from the initiator for the data received.
boolean	isBidirectionalReadResidualOverflow() 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.
boolean	isBidirectionalReadResidualUnderflow() 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.
boolean	isResidualOverflow() 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.
boolean	isResidualUnderflow() 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.
boolean	isStatusFlag() Set this to indicate that the Command Status field contains status.
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	setAcknowledgeFlag(boolean acknowledgeFlag)
void	setBufferOffset(int bufferOffset)
void	setDataSequenceNumber(int dataSequenceNumber)
void	setResidualCount(int residualCount)
void	setResidualOverflowFlag(boolean residualOverflowFlag)
void	setResidualUnderflowFlag(boolean residualUnderflowFlag)
void	setStatus(SCSIStatus status)
void	setStatusFlag(boolean statusFlag)
void	setTargetTransferTag(int targetTransferTag)
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, getStatusSequenceNumber, 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

DataInParser

public DataInParser(ProtocolDataUnit initProtocolDataUnit)

Default constructor, creates a new, empty DataInParser object.

Parameters:

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

Method Detail

getShortInfo

public String getShortInfo()

Returns the short version of the used sequence numbers of this parser instance.

Overrides:

getShortInfo in class TargetMessageParser

Returns:

The string with all needed sequence numbers.

toString

public 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 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 void clear()

This method sets all settings to their initial values.

Overrides:

clear in class TargetMessageParser

incrementSequenceNumber

public final boolean incrementSequenceNumber()

This AbstractMessageParser instance affects the incrementation of the Expected Status Sequence Number.

Overrides:

incrementSequenceNumber in class TargetMessageParser

Returns:

true, if the counter has to be incremented. Else false.

getBufferOffset

public int getBufferOffset()

The Buffer Offset field contains the offset of this PDU payload data within the complete data transfer. The sum of the buffer offset and length should not exceed the expected transfer length for the command.
The order of data PDUs within a sequence is determined by DataPDUInOrder. When set to Yes, it means that PDUs have to be in increasing Buffer Offset order and overlays are forbidden.
The ordering between sequences is determined by DataSequenceInOrder. When set to Yes, it means that sequences have to be in increasing Buffer Offset order and overlays are forbidden.

Returns:

The buffer offset of this DataInParser object.

getDataSequenceNumber

public int getDataSequenceNumber()

For input (read) or bidirectional Data-In PDUs, the DataSN is the input PDU number within the data transfer for the command identified by the Initiator Task Tag.
R2T and Data-In PDUs, in the context of bidirectional commands, share the numbering sequence (see Section 3.2.2.3 Data Sequencing).
For output (write) data PDUs, the DataSN is the Data-Out PDU number within the current output sequence. The current output sequence is either identified by the Initiator Task Tag (for unsolicited data) or is a data sequence generated for one R2T (for data solicited through R2T).

Returns:

The Data Sequence Number of this DataInParser object.

getResidualCount

public 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 object.

getTargetTaskTag

public int getTargetTaskTag()

On outgoing data, the Target Transfer Tag is provided to the target if the transfer is honoring an R2T. In this case, the Target Transfer Tag field is a replica of the Target Transfer Tag provided with the R2T.
On incoming data, the Target Transfer Tag and LUN MUST be provided by the target if the A bit is set to 1; otherwise they are reserved. The Target Transfer Tag and LUN are copied by the initiator into the SNACK of type DataACK that it issues as a result of receiving a SCSI Data-In PDU with the A bit set to 1.
The Target Transfer Tag values are not specified by this protocol except that the value 0xffffffff is reserved and means that the Target Transfer Tag is not supplied. If the Target Transfer Tag is provided, then the LUN field MUST hold a valid value and be consistent with whatever was specified with the command; otherwise, the LUN field is reserved.

Returns:

Returns the Target Transfer Tag of this DataInParser object.

isAcknowledgeFlag

public boolean isAcknowledgeFlag()

For sessions with ErrorRecoveryLevel 1 or higher, the target sets this bit to 1 to indicate that it requests a positive acknowledgement from the initiator for the data received. The target should use the A bit moderately; it MAY only set the A bit to 1 once every MaxBurstLength bytes, or on the last Data-In PDU that concludes the entire requested read data transfer for the task from the target’s perspective, and it MUST NOT do so more frequently. The target MUST NOT set to 1 the A bit for sessions with ErrorRecoveryLevel=0. The initiator MUST ignore the A bit

On receiving a Data-In PDU with the A bit set to 1 on a session with ErrorRecoveryLevel greater than 0, if there are no holes in the read data until that Data-In PDU, the initiator MUST issue a SNACK of type DataACK except when it is able to acknowledge the status for the task immediately via ExpStatSN on other outbound PDUs if the status for the task is also received. In the latter case (acknowledgement through ExpStatSN), sending a SNACK of type DataACK in response to the A bit is OPTIONAL, but if it is done, it must not be sent after the status acknowledgement through ExpStatSN. If the initiator has detected holes in the read data prior to that Data-In PDU, it MUST postpone issuing the SNACK of type DataACK until the holes are filled. An initiator also MUST NOT acknowledge the status for the task before those holes are filled. A status acknowledgement for a task that generated the Data-In PDUs is considered by the target as an implicit acknowledgement of the Data-In PDUs if such an acknowledgement was requested by the target.

Returns:

Returns true, if the AcknowledgeBit is set. Else false.

isBidirectionalReadResidualOverflow

public boolean isBidirectionalReadResidualOverflow()

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 the ReadResidualOverflow-Flag of this object is set. Else false.

isBidirectionalReadResidualUnderflow

public boolean isBidirectionalReadResidualUnderflow()

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 the ReadResidualUnderflow-Flag of this object is set. Else false.

isResidualOverflow

public boolean isResidualOverflow()

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 the ResidualOverflow-Flag of this object is set. Else false.

isResidualUnderflow

public boolean isResidualUnderflow()

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 the ResidualUnderflow-Flag of this object is set. Else false.

getStatus

public 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.

If a SCSI device error is detected while data from the initiator is still expected (the command PDU did not contain all the data and the target has not received a Data PDU with the final bit Set), the target MUST wait until it receives a Data PDU with the F bit set in the last expected sequence before sending the Response PDU.

Returns:

The status code of this object.

See Also:

SCSIStatus

isStatusFlag

public boolean isStatusFlag()

Set this to indicate that the Command Status field contains status. If this bit is set to 1, the F bit MUST also be set to 1.
The fields StatSN, Status, and Residual Count only have meaningful content if the S bit is set to 1 and their values are defined in Section 10.4 SCSI Response.

Returns:

True, if the Status-Flag of this object is set. Else false.

setAcknowledgeFlag

public void setAcknowledgeFlag(boolean acknowledgeFlag)

setResidualOverflowFlag

public void setResidualOverflowFlag(boolean residualOverflowFlag)

setResidualUnderflowFlag

public void setResidualUnderflowFlag(boolean residualUnderflowFlag)

setStatusFlag

public void setStatusFlag(boolean statusFlag)

setStatus

public void setStatus(SCSIStatus status)

setTargetTransferTag

public void setTargetTransferTag(int targetTransferTag)

setDataSequenceNumber

public void setDataSequenceNumber(int dataSequenceNumber)

setBufferOffset

public void setBufferOffset(int bufferOffset)

setResidualCount

public void setResidualCount(int residualCount)

deserializeBytes1to3

protected 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 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 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 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 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 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 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 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 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 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 int serializeBytes44to47()

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

Overrides:

serializeBytes44to47 in class TargetMessageParser

Returns:

The serialized byte representation.