/*
    * 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.any23.extractor;
  
  import org.apache.any23.extractor.html.MicroformatExtractor;
  import org.openrdf.model.BNode;
  import org.openrdf.model.Resource;
  
  import java.util.Arrays;
  import java.util.List;
  
  /**
   * This interface models a specific {@link ExtractionResult}
   * able to collect property roots generated by <i>HTML Microformat</i> extractions.
   *
   * @author Michele Mostarda (mostarda@fbk.eu)
   */
  public interface TagSoupExtractionResult extends ExtractionResult {
  
      /**
       * Adds a root property to the extraction result, specifying also
       * the <i>path</i> corresponding to the root of data which generated the property
       * and the extractor responsible for such addition.
       *
       * @param path the <i>path</i> from the document root to the local root of the data generating the property.
       * @param root the property root node.
       * @param extractor the extractor responsible of such extraction.
       */
      void addResourceRoot(String[] path, Resource root, Class<? extends MicroformatExtractor> extractor);
  
      /**
       * Returns all the collected property roots.
       *
       * @return an <b>unmodifiable</b> list of
       *         {@link TagSoupExtractionResult.ResourceRoot}s.
       */
      List<ResourceRoot> getResourceRoots();
  
      /**
       * Adds a property path to the list of the extracted data.
       *
       * @param extractor the identifier of the extractor responsible for retrieving such property.
       * @param propertySubject the subject of the property.
       * @param property the property URI.
       * @param object the property object if any, <code>null</code> otherwise.
       * @param path the path of the <i>HTML</i> node from which the property literal has been extracted.
       */
      void addPropertyPath(
              Class<? extends MicroformatExtractor> extractor,
              Resource propertySubject,
              Resource property,
              BNode object,
              String[] path
      );
  
      /**
       * Returns all the collected property paths.
       *
       * @return a valid list of property paths.
       */
      List<PropertyPath> getPropertyPaths();
  
      /**
       * Defines a property root object.
       */
      class ResourceRoot {
          private String[] path;
          private Resource root;
          private Class<? extends MicroformatExtractor>  extractor;
  
          public ResourceRoot(String[] path, Resource root, Class<? extends MicroformatExtractor> extractor) {
              if(path == null || path.length == 0) {
                  throw new IllegalArgumentException( String.format("Invalid xpath: '%s'.", Arrays.toString(path) ) );
              }
              if(root == null) {
                  throw new IllegalArgumentException("Invalid root, cannot be null.");
              }
              if(extractor == null) {
                  throw new IllegalArgumentException("Invalid extractor, cannot ne null");
              }
              this.path      = path;
              this.root      = root;
              this.extractor = extractor;
          }
 
         public String[] getPath() {
             return path;
         }
 
         public Resource getRoot() {
             return root;
         }
 
         public Class<? extends MicroformatExtractor> getExtractor() {
             return extractor;
         }
 
         @Override
         public String toString() {
             return String.format(
                     "%s-%s-%s %s",
                     this.getClass().getCanonicalName(),
                     Arrays.toString(path), 
                     root,
                     extractor
             );
         }
     }
 
     /**
      * Defines a property path object.
      */
     class PropertyPath {
 
         private Class<? extends MicroformatExtractor>  extractor;
         private String[] path;
         private Resource subject;
         private Resource property;
         private BNode    object;
 
         public PropertyPath(String[] path, Resource subject, Resource property, BNode object, Class<? extends MicroformatExtractor> extractor) {
             if(path == null) {
                 throw new NullPointerException("path cannot be null.");
             }
             if(subject == null) {
                 throw new NullPointerException("subject cannot be null.");
             }
             if(property == null) {
                 throw new NullPointerException("property cannot be null.");
             }
             if(extractor == null) {
                 throw new NullPointerException("extractor cannot be null.");
             }
             this.path      = path;
             this.subject   = subject;
             this.property  = property;
             this.object    = object;
             this.extractor = extractor;
         }
 
         public String[] getPath() {
             return path;
         }
 
         public Resource getSubject() {
             return subject;
         }
 
         public Resource getProperty() {
             return property;
         }
 
         public BNode getObject() {
             return object;
         }
 
         public Class<? extends MicroformatExtractor> getExtractor() {
             return extractor;
         }
 
         @Override
          public String toString() {
             return String.format(
                     "%s %s - %s - %s -- %s -->",
                     this.getClass().getCanonicalName(),
                     Arrays.toString(path),
                     extractor,
                     subject,
                     property
             );
         }
     }
 
 }