/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.pig.data;

import java.io.Serializable;
import java.util.List;

import org.apache.hadoop.io.WritableComparable;

import org.apache.pig.classification.InterfaceAudience;
import org.apache.pig.classification.InterfaceStability;
import org.apache.pig.backend.executionengine.ExecException;

/**
 * An ordered list of Data.  A tuple has fields, numbered 0 through
 * (number of fields - 1).  The entry in the field can be any datatype,
 * or it can be null.
 * <p>
 * Tuples are constructed only by a {@link TupleFactory}.  A
 * {@link DefaultTupleFactory}
 * is provided by the system.  If users wish to use their own type of
 * Tuple, they should also provide an implementation of {@link TupleFactory} to
 * construct their types of Tuples.
 *
 */

// Put in to make the compiler not complain about WritableComparable
// being a generic type.
@SuppressWarnings("unchecked")
@InterfaceAudience.Public
@InterfaceStability.Stable
public interface Tuple extends WritableComparable, Serializable, Iterable<Object> {
       
    /**
     * Marker for indicating whether the value this object holds
     * is a null
     */
    public static byte NULL = 0x00;
    
    /**
     * Marker for indicating whether the value this object holds
     * is not a null
     */
    public static byte NOTNULL = 0x01;
    
    /**
     * Make this tuple reference the contents of another.  This method does not copy
     * the underlying data.   It maintains references to the data from the original
     * tuple (and possibly even to the data structure holding the data).
     * @param t Tuple to reference.
     */
    @Deprecated
    void reference(Tuple t);

    /**
     * Find the size of the tuple.  Used to be called arity().
     * @return number of fields in the tuple.
     */
    int size();

    /**
     * Find out if a given field is null.
     * @param fieldNum Number of field to check for null.
     * @return true if the field is null, false otherwise.
     * @throws ExecException if the field number given is greater
     * than or equal to the number of fields in the tuple.
     */
    boolean isNull(int fieldNum) throws ExecException;

    /**
     * Find the type of a given field.
     * @param fieldNum Number of field to get the type for.
     * @return type, encoded as a byte value.  The values are defined in
     * {@link DataType}.  If the field is null, then DataType.UNKNOWN
     * will be returned.
     * @throws ExecException if the field number is greater than or equal to
     * the number of fields in the tuple.
     */
    byte getType(int fieldNum) throws ExecException;

    /**
     * Get the value in a given field.
     * @param fieldNum Number of the field to get the value for.
     * @return value, as an Object.
     * @throws ExecException if the field number is greater than or equal to
     * the number of fields in the tuple.
     */
    Object get(int fieldNum) throws ExecException;

    /**
     * Get all of the fields in the tuple as a list.
     * @return a list of objects containing the fields of the tuple
     * in order.
     */
    List<Object> getAll();

    /**
     * Set the value in a given field.  This should not be called unless
     * the tuple was constructed by {@link TupleFactory#newTuple(int)} with an
     * argument greater than the fieldNum being passed here.  This call will
     * not automatically expand the tuple size.  That is if you called 
     * {@link TupleFactory#newTuple(int)} with a 2, it is okay to call
     * this function with a 1, but not with a 2 or greater.
     * @param fieldNum Number of the field to set the value for.
     * @param val Object to put in the indicated field.
     * @throws ExecException if the field number is greater than or equal to
     * the number of fields in the tuple.
     */
    void set(int fieldNum, Object val) throws ExecException;

    /**
     * Append a field to a tuple.  This method is not efficient as it may
     * force copying of existing data in order to grow the data structure.
     * Whenever possible you should construct your Tuple with 
     * {@link TupleFactory#newTuple(int)} and then fill in the values with 
     * {@link #set(int, Object)}, rather
     * than construct it with {@link TupleFactory#newTuple()} and append values.
     * @param val Object to append to the tuple.
     */
    void append(Object val);

    /**
     * Determine the size of tuple in memory.  This is used by data bags
     * to determine their memory size.  This need not be exact, but it
     * should be a decent estimation.
     * @return estimated memory size, in bytes.
     */
    long getMemorySize();

    /** 
     * Write a tuple of values into a string. The output will be the result
     * of calling toString on each of the values in the tuple.
     * @param delim Delimiter to use in the string.
     * @return A string containing the tuple.
     * @throws ExecException this is never thrown. This only exists for backwards compatability reasons.
     */
    String toDelimitedString(String delim) throws ExecException;
}