/*
 * 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;

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

import org.apache.pig.classification.InterfaceAudience;
import org.apache.pig.classification.InterfaceStability;
import org.apache.pig.impl.logicalLayer.FrontendException;

/**
 * This interface defines how to communicate to Pig what functionality can
 * be pushed into the loader.  If a given loader does not implement this interface
 * it will be assumed that it is unable to accept any functionality for push down.
 * @since Pig 0.7
 */
@InterfaceAudience.Public
@InterfaceStability.Evolving
public interface LoadPushDown {

    /**
     * Set of possible operations that Pig can push down to a loader. 
     */
    enum OperatorSet {PROJECTION};

    /**
     * Determine the operators that can be pushed to the loader.  
     * Note that by indicating a loader can accept a certain operator
     * (such as selection) the loader is not promising that it can handle
     * all selections.  When it is passed the actual operators to 
     * push down it will still have a chance to reject them.
     * @return list of all features that the loader can support
     */
    List<OperatorSet> getFeatures();

    /**
     * Indicate to the loader fields that will be needed.  This can be useful for
     * loaders that access data that is stored in a columnar format where indicating
     * columns to be accessed a head of time will save scans.  This method will
     * not be invoked by the Pig runtime if all fields are required. So implementations
     * should assume that if this method is not invoked, then all fields from 
     * the input are required. If the loader function cannot make use of this 
     * information, it is free to ignore it by returning an appropriate Response
     * @param requiredFieldList RequiredFieldList indicating which columns will be needed.
     * This structure is read only. User cannot make change to it inside pushProjection.
     * @return Indicates which fields will be returned
     * @throws FrontendException
     */
    public RequiredFieldResponse pushProjection(RequiredFieldList 
            requiredFieldList) throws FrontendException;
    
    /**
     * Describes a field that is required to execute a scripts.
     */
    @InterfaceAudience.Public
    @InterfaceStability.Evolving
    public static class RequiredField implements Serializable {
        
        private static final long serialVersionUID = 1L;
        
        // will hold name of the field (would be null if not supplied)
        private String alias; 

        // will hold the index (position) of the required field (would be -1 if not supplied), index is 0 based
        private int index; 

        // A list of sub fields in this field (this could be a list of hash keys for example). 
        // This would be null if the entire field is required and no specific sub fields are required. 
        // In the initial implementation only one level of subfields will be populated.
        private List<RequiredField> subFields;
        
        // Type of this field - the value could be any current PIG DataType (as specified by the constants in DataType class).
        private byte type;

        public RequiredField() {
            // to allow piece-meal construction
        }
        
        /**
         * @param alias
         * @param index
         * @param subFields
         * @param type
         */
        public RequiredField(String alias, int index,
                List<RequiredField> subFields, byte type) {
            this.alias = alias;
            this.index = index;
            this.subFields = subFields;
            this.type = type;
        }

        /**
         * @return the alias
         */
        public String getAlias() {
            return alias;
        }

        /**
         * @return the index
         */
        public int getIndex() {
            return index;
        }

        
        /**
         * @return the required sub fields. The return value is null if all
         *         subfields are required
         */
        public List<RequiredField> getSubFields() {
            return subFields;
        }
        
        public void setSubFields(List<RequiredField> subFields)
        {
            this.subFields = subFields;
        }

        /**
         * @return the type
         */
        public byte getType() {
            return type;
        }

        public void setType(byte t) {
            type = t;
        }
        
        public void setIndex(int i) {
            index = i;
        }
        
        public void setAlias(String alias)
        {
            this.alias = alias;
        }

        @Override
        public String toString() {
            if (index != -1)
                return "" + index;
            else if (alias != null)
                return alias;
            return "";
        }
    }

    /**
     * List of fields that Pig knows to be required to executed a script.
     */
    @InterfaceAudience.Public
    @InterfaceStability.Evolving
    public static class RequiredFieldList implements Serializable {
        
        private static final long serialVersionUID = 1L;
        
        // list of Required fields, this will be null if all fields are required
        private List<RequiredField> fields = new ArrayList<RequiredField>(); 
        
        /**
         * Set the list of required fields.
         * @param fields
         */
        public RequiredFieldList(List<RequiredField> fields) {
            this.fields = fields;
        }

        /**
         * Geta ll required fields as a list.
         * @return the required fields - this will be null if all fields are
         *         required
         */
        public List<RequiredField> getFields() {
            return fields;
        }

        public RequiredFieldList() {
        }
        
        @Override
        public String toString() {
            StringBuffer result = new StringBuffer();
            if (fields == null)
                result.append("*");
            else {
                result.append("[");
                for (int i = 0; i < fields.size(); i++) {
                    result.append(fields.get(i));
                    if (i != fields.size() - 1)
                        result.append(",");
                }
                result.append("]");
            }
            return result.toString();
        }
        
        /**
         * Add a field to the list of required fields.
         * @param rf required field to add to the list.
         */
        public void add(RequiredField rf)
        {
            fields.add(rf);
        }
    }

    /**
     * Indicates whether the loader will return the requested fields or all fields.
     */
    @InterfaceAudience.Public
    @InterfaceStability.Evolving
    public static class RequiredFieldResponse {
        // the loader should pass true if it will return data containing
        // only the List of RequiredFields in that order. false if it
        // will return all fields in the data
        private boolean requiredFieldRequestHonored;

        public RequiredFieldResponse(boolean requiredFieldRequestHonored) {
            this.requiredFieldRequestHonored = requiredFieldRequestHonored;
        }

        /**
         * Indicates whether the loader will return only the requested fields or all fields.
         * @return true if only requested fields will be returned, false if all fields will be
         * returned.
         */
        public boolean getRequiredFieldResponse() {
            return requiredFieldRequestHonored;
        }

        /**
         * Set whether the loader will return only the requesetd fields or all fields.
         * @param honored if true only requested fields will be returned, else all fields will be
         * returned.
         */
        public void setRequiredFieldResponse(boolean honored) {
            requiredFieldRequestHonored = honored;
        }
    }

    
}