core/src/main/java/org/apache/any23/extractor/TagSoupExtractionResult.java

/*
 * 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.eclipse.rdf4j.model.BNode;
import org.eclipse.rdf4j.model.Resource;

import java.util.Arrays;
import java.util.List;
import java.util.Locale;

/**
 * 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 IRI.
     * @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(Locale.ROOT, "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(Locale.ROOT, "%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(Locale.ROOT, "%s %s - %s - %s -- %s -->", this.getClass().getCanonicalName(),
                    Arrays.toString(path), extractor, subject, property);
        }
    }

}