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;

     }

 }