/**
    * This file Copyright (c) 2014-2015 Magnolia International
    * Ltd.  (http://www.magnolia-cms.com). All rights reserved.
    *
    *
    * This file is dual-licensed under both the Magnolia
    * Network Agreement and the GNU General Public License.
    * You may elect to use one or the other of these licenses.
    *
   * This file is distributed in the hope that it will be
   * useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
   * implied warranty of MERCHANTABILITY or FITNESS FOR A
   * PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
   * Redistribution, except as permitted by whichever of the GPL
   * or MNA you select, is prohibited.
   *
   * 1. For the GPL license (GPL), you can redistribute and/or
   * modify this file under the terms of the GNU General
   * Public License, Version 3, as published by the Free Software
   * Foundation.  You should have received a copy of the GNU
   * General Public License, Version 3 along with this program;
   * if not, write to the Free Software Foundation, Inc., 51
   * Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
   *
   * 2. For the Magnolia Network Agreement (MNA), this file
   * and the accompanying materials are made available under the
   * terms of the MNA which accompanies this distribution, and
   * is available at http://www.magnolia-cms.com/mna.html
   *
   * Any modifications to this file must keep this entire header
   * intact.
   *
   */
  package info.magnolia.dam.api;
  
  import info.magnolia.dam.api.metadata.AssetMetadata;
  
  import java.util.ArrayList;
  import java.util.List;
  
  import com.google.common.base.Preconditions;
  import com.google.common.net.MediaType;
  
  /**
   * Represents a query to an AssetProvider. Use new AssetQuery.Builder()...build() to construct instances.
   * @see AssetProvider#list(AssetQuery)
   */
  public interface AssetQuery {
      String getRootPath();
  
      Folder getRootFolder();
  
      /**
       * @deprecated since 2.0.5. use {@link #includesDescendants()}
       */
      boolean includesChildren();
  
      /**
       * Includes all the descendants of the specified path or folder, not just the direct children.
       */
      boolean includesDescendants();
  
      List<MediaType> getMediaTypes();
  
      String getExtension();
  
      String getKeywordSearchTerm();
  
      /**
       * An additional statement, usually provider-specific, which is appended to the underlying query.
       * There is no common language between providers, so there is no guarantee that this works accross
       * providers. No guarantee is made by providers on how this is used either. Some providers
       * might refuse to use this in addition to other criteria.
       * @deprecated since 2.0. Kept around for backwards compatibility.
       */
      String getAdditionalQueryStatement();
  
      boolean includesFolders();
  
      boolean includesAssets();
  
      List<OrderBy> getSorters();
  
      long getMaxResults();
  
      /**
       * The number of items to skip before returning the results.
       * Results that are skipped due to offset do not count against the limit specified by max results.
       */
      long getOffset();
  
      /**
       * Enumeration specifying the order of sorting.
       */
      static enum Order {
          ASCENDING,
  
          DESCENDING
      }
 
     /**
      * Represents a sorting rule to be applied to a query.
      */
     static class OrderBy {
 
         private Class<? extends AssetMetadata> metadataClass;
         private String propertyId;
         private Order order;
 
         public OrderBy(Class<? extends AssetMetadata> metadataClass, String propertyId, Order order) {
             this.metadataClass = metadataClass;
             this.propertyId = propertyId;
             this.order = order;
         }
 
         public Class<? extends AssetMetadata> getMetadataClass() {
             return metadataClass;
         }
 
         public String getPropertyId() {
             return propertyId;
         }
 
         public Order getOrder() {
             return order;
         }
     }
 
     /**
      * A builder for {@link AssetQuery} which provides a fluent API.
      */
     public static final class Builder {
         private String rootPath;
         private Folder rootFolder;
         private boolean includeDescendants = true;
 
         private List<MediaType> mediaTypes = new ArrayList<MediaType>();
         private String extension;
         private String keywordSearchTerm;
         private String additionalQueryStatement;
 
         private boolean includeFolders = false;
         private boolean includeAssets = true;
 
         private long maxResults = 100;
         private long offset = 0;
         private List<OrderBy> sorters = new ArrayList<OrderBy>();
 
         public Builder() {
         }
 
         public Builder fromPath(String rootPath) {
             Preconditions.checkState(this.rootFolder == null, "Can't set rootPath, rootFolder is already set");
             Preconditions.checkState(this.rootPath == null, "Can't set rootPath, it is already set");
             this.rootPath = rootPath;
             return this;
         }
 
         public Builder fromFolder(Folder rootFolder) {
             Preconditions.checkState(this.rootPath == null, "Can't set rootFolder, rootPath is already set");
             Preconditions.checkState(this.rootFolder == null, "Can't set rootFolder, it is already set");
             this.rootFolder = rootFolder;
             return this;
         }
 
         /**
          * @deprecated since 2.0.5. use {@link #excludeDescendants()}
          */
         public Builder excludeChildren() {
             this.includeDescendants = false;
             return this;
         }
 
         /**
          * Do not include all the descendants of the specified path or folder, only the direct children.
          * Only applies when a Path or Folder were specified.
          */
         public Builder excludeDescendants() {
             this.includeDescendants = false;
             return this;
         }
 
         public Builder withExtension(String extension) {
             this.extension = extension;
             return this;
         }
 
         public Builder withMediaType(MediaType... mediaTypes) {
             for (MediaType mediaType : mediaTypes) {
                 this.mediaTypes.add(mediaType);
             }
             return this;
         }
 
         public Builder orderBy(Class<? extends AssetMetadata> metadataClass, String propertyId, Order order) {
             this.sorters.add(new OrderBy(metadataClass, propertyId, order));
             return this;
         }
 
         public Builder withKeyword(String keyword) {
             this.keywordSearchTerm = keyword;
             return this;
         }
 
         public Builder withAdditionalQueryStatement(String additionalQueryStatement) {
             this.additionalQueryStatement = additionalQueryStatement;
             return this;
         }
 
         public Builder withMaxResults(long maxResults) {
             this.maxResults = maxResults;
             return this;
         }
 
         public Builder withOffset(long offset) {
             this.offset = offset;
             return this;
         }
 
         public Builder includeFolders() {
             this.includeFolders = true;
             return this;
         }
 
         public Builder excludeAssets() {
             this.includeAssets = false;
             return this;
         }
 
         public AssetQuery build() {
             return new AssetQuery() {
                 @Override
                 public String getRootPath() {
                     return rootPath;
                 }
 
                 @Override
                 public Folder getRootFolder() {
                     return rootFolder;
                 }
 
                 @Override
                 public boolean includesChildren() {
                     return includeDescendants;
                 }
 
                 @Override
                 public boolean includesDescendants() {
                     return includeDescendants;
                 }
 
                 @Override
                 public List<MediaType> getMediaTypes() {
                     return mediaTypes;
                 }
 
                 @Override
                 public List<OrderBy> getSorters() {
                     return sorters;
                 }
 
                 @Override
                 public String getExtension() {
                     return extension;
                 }
 
                 @Override
                 public String getKeywordSearchTerm() {
                     return keywordSearchTerm;
                 }
 
                 @Override
                 public String getAdditionalQueryStatement() {
                     return additionalQueryStatement;
                 }
 
                 @Override
                 public boolean includesFolders() {
                     return includeFolders;
                 }
 
                 @Override
                 public boolean includesAssets() {
                     return includeAssets;
                 }
 
                 @Override
                 public long getMaxResults() {
                     return maxResults;
                 }
 
                 @Override
                 public long getOffset() {
                     return offset;
                 }
             };
         }
     }
 }