package org.jscsi.target.settings.entry;
import java.util.Collection;
import javax.naming.OperationNotSupportedException;
import org.jscsi.parser.ProtocolDataUnit;
import org.jscsi.parser.login.LoginStage;
import org.jscsi.target.TargetServer;
import org.jscsi.target.settings.KeySet;
import org.jscsi.target.settings.NegotiationStatus;
import org.jscsi.target.settings.NegotiationType;
import org.jscsi.target.settings.SettingsNegotiator;
import org.jscsi.target.settings.TextKeyword;
import org.jscsi.target.settings.TextParameter;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* {@link Entry} objects are used by instances {@link SettingsNegotiator} during text negotiation of connection and
* session parameter. For all parameters that are either declared by the iSCSI initiator or negotiated between the
* initiator and the target a separate {@link Entry} takes care of processing the respective <i>key=value</i> pair and
* returning the negotiated value, if appropriate.
* <p>
* For brevity, the term "negotiated" will be used in the following in a way that can either mean
* "declared or negotiated", unless the distinction is evident by context.
*
* @author Andreas Ergenzinger, University of Konstanz
*/
public abstract class Entry {
private static final Logger LOGGER = LoggerFactory.getLogger(Entry.class);
/**
* A {@link KeySet} containing all keys that can be used for negotiating this {@link Entry}'s value.
*/
protected final KeySet keySet;
/**
* Specifies if the {@link Entry}'s parameter is declared or negotiated.
*/
protected final NegotiationType negotiationType;
/**
* Determines during which stages this {@link Entry}'s parameters may be negotiated.
*/
protected final Use use;
/**
* This variable specifies the progress and necessity of negotiating the parameter managed by this {@link Entry}.
*/
protected NegotiationStatus negotiationStatus;
/**
* The currently valid value or <code>null</code>.
*/
protected Object value;
/**
* This variable is used to detect illegal attempts to renegotiate a previously negotiated or declared text
* parameter.
* <p>
* This variable will be set back to <code>false</code> after each negotiation task (login phase, or text parameter
* negotiation stage). Renegotiation accross stages/tasks can be prevented by initializing the {@link #use} variable
* accordingly.
*
* @see #resetAlreadyNegotiated()
*/
protected boolean alreadyNegotiated = false;
/**
* Abstract constructor.
*
* @param keySet contains all relevant keys
* @param negotiationType declared or negotiated
* @param use determines under which circumstances the parameter may be negotiated
* @param negotiationStatus indicates whether there is a default value or if the parameter must be negotiated
* @param defaultValue the default value or <code>null</code>
*/
public Entry (final KeySet keySet, final NegotiationType negotiationType, final Use use, final NegotiationStatus negotiationStatus, Object defaultValue) {
this.keySet = keySet;
this.negotiationType = negotiationType;
this.use = use;
this.negotiationStatus = negotiationStatus;
this.value = defaultValue;
}
/**
* Logs an error message containing all {@link #keySet} keys as well as the passed {@link String} parameter and
* indicates an unsuccessful negotiation by setting {@link #negotiationStatus} to {@link NegotiationStatus#REJECTED}
* .
*
* @param logMessage
*/
private void fail (final String logMessage) {
LOGGER.error("negotiation error " + keySet + ": " + logMessage);
negotiationStatus = NegotiationStatus.REJECTED;
}
/**
* Parses the passed {@link String} parameter and returns a sub-class-specific {@link Object} which represents the
* the specified <i>value</i> part a <i>key=value</i> pair.
*
* @param values the <i>value</i> part of a <i>key=value</i> pair
* @return sub-class-specific {@link Object} or <code>null</code> if the parameter violated the expected format
*/
protected abstract Object parseOffer (TargetServer target, String values);
/**
* This method is used for negotiating or declaring the {@link Entry}'s parameter.
*
* @param loginStage specifying the current stage or phase of the connection whose parameters are to be negotiated
* @param leadingConnection <code>true</code> if the connection is the first connection in its session,
* <code>false</code> if not
* @param initialPdu <code>true</code> if the <i>key=value</i> pair parameters have been sent in the first login
* {@link ProtocolDataUnit} from the initiator, <code>false</code> if thy have not
* @param key the <i>key</i> part from the received <i>key=value</i> pair
* @param values the <i>value</i> part from the received <i>key=value</i> pair
* @param responseKeyValuePairs where the reply <i>key=value</i> pair will be added to if necessary
* @return <code>true</code> if everything went fine, <code>false</code> if errors occured
*/
public final boolean negotiate (TargetServer target, final LoginStage loginStage, final boolean leadingConnection, final boolean initialPdu, final String key, final String values, final Collection<String> responseKeyValuePairs) {
// (re)check key (just in case), this should have been checked before
// calling this method
if (!matchKey(key)) {
fail("\"" + key + "\" does not match key in" + keySet);
return false;
}
// prevent renegotiation and remember this negotiation
if (alreadyNegotiated) {
fail("illegal renegotiation");
return false;
}
alreadyNegotiated = true;
// check use code
if (!use.checkUse(loginStage, leadingConnection, initialPdu)) {
fail("wrong use: " + use + ", " + loginStage + ", " + leadingConnection + ", " + initialPdu);
return false;
}
// transform values to appropriate type
final Object offer = parseOffer(target, values);
if (offer == null) {
fail("value format error: " + values);
return false;
}
// check if values are in the protocol-conform range/set of values
if (!inProtocolValueRange(offer)) {
fail("illegal values offered: " + values);
return false;
}
// *** declare ***
if (negotiationType == NegotiationType.DECLARED) {
// save received value ...
processDeclaration(offer);
// ... and accept silently
negotiationStatus = NegotiationStatus.ACCEPTED;
return true;
}
// *** negotiate ***
if (negotiationType == NegotiationType.NEGOTIATED) {
String negotiatedValue;// will be returned as value part
if (negotiationStatus == NegotiationStatus.IRRELEVANT)
negotiatedValue = TextKeyword.IRRELEVANT;
else
negotiatedValue = processNegotiation(offer);
String reply;
// reply, remember outcome, log, and return
if (negotiatedValue == null) {// no commonly supported values
reply = TextParameter.toKeyValuePair(key, TextKeyword.REJECT);
responseKeyValuePairs.add(reply);
fail("rejected value(s): " + values);
return false;
}// else
reply = TextParameter.toKeyValuePair(key, negotiatedValue);
responseKeyValuePairs.add(reply);
return true;
}
// we should not be here
fail("initialization error: negotiationType == null");
return false;
}
/**
* Sets {@link #alreadyNegotiated} back to <code>false</code>.
* <p>
* This method must be used at the end of each negotiation task, i.e. at the end of the login phase and the FFP text
* negotiation stage.
*/
public void resetAlreadyNegotiated () {
alreadyNegotiated = false;
}
/**
* Returns the negotiated (or default) value as a {@link Boolean}.
*
* @return the negotiated (or default) value as a {@link Boolean}
* @throws OperationNotSupportedException if {@link #value} is not of the boolean type
*/
public Boolean getBooleanValue () throws OperationNotSupportedException {
throw new OperationNotSupportedException();
}
/**
* Returns the negotiated (or default) value as an {@link Integer}.
*
* @return the negotiated (or default) value as an {@link Integer}
* @throws OperationNotSupportedException if {@link #value} is not of the integer type
*/
public Integer getIntegerValue () throws OperationNotSupportedException {
throw new OperationNotSupportedException();
}
/**
* Returns the negotiated (or default) value as a {@link String}.
*
* @return the negotiated (or default) value as a {@link String}
* @throws OperationNotSupportedException if {@link #value} is not a {@link String}
*/
public String getStringValue () throws OperationNotSupportedException {
throw new OperationNotSupportedException();
}
/**
* Returns <code>true</code> if one of the keys of {@link #keySet} equals the parameter and <code>false</code> if
* there is not match.
*
* @param key the key to compare to the {@link #keySet} keys
* @return <code>true</code> if one of the keys of {@link #keySet} equals the parameter and <code>false</code> if
* not
*/
public final boolean matchKey (final String key) {
return keySet.matchKey(key);
}
/**
* This method is used for checking if a sub-class-specific {@link Object}, representing a single, a range, or a
* list of values sent by the initiator, is illegal, according to the iSCSI standard.
*
* @param values a sub-class-specific {@link Object}, representing a single, a range, or a list of values sent by
* the initiator
* @return <code>false</code> if the iSCSI standard has been violated, <code>true</code> if not
*/
protected abstract boolean inProtocolValueRange (Object values);
/**
* Receives a sub-class-specific {@link Object}, representing a legal parameter value declared by the initiator and
* accepts it as the new {@link #value}.
*
* @param values sub-class-specific representation of a single <i>value</i> declared by the initiator
*/
protected abstract void processDeclaration (Object values);
// returns null if reply is to be key=Reject
/**
* Receives a sub-class-specific {@link Object}, representing a list, a range, or a single legal parameter value
* offered by the initiator and tries to select a value from that offer. If none of the offered values is supported
* by the jSCSI Target, <code>null</code> is returned, otherwise the selection is accepted as the new {@link #value}
* and returned as a {@link String}. {@link #value}.
*
* @param values a sub-class-specific {@link Object}, representing a list, a range, or a single legal parameter
* value offered by the initiator
* @return the final, negotiated value or <code>null</code>, if the initiator's offer does not overlap with the
* values supported by the jSCSI Target
*/
protected abstract String processNegotiation (Object values);
/**
* Returns {@link #negotiationStatus}.
*
* @return {@link #negotiationStatus}
*/
public final NegotiationStatus getNegotiationStatus () {
return negotiationStatus;
}
/**
* Returns an exact copy of this {@link Entry}.
*
* @return a copy of this {@link Entry}.
*/
public abstract Entry copy ();
/**
* Returns <code>true</code> if {@link #negotiationStatus} is {@link NegotiationStatus#ACCEPTED} and
* <code>false</code> if it is not.
*
* @return <code>true</code> if {@link #negotiationStatus} is {@link NegotiationStatus#ACCEPTED}, <code>false</code>
* if not
*/
public boolean checkAccepted () {
return negotiationStatus == NegotiationStatus.ACCEPTED;
}
}