/*
 * Copyright (C) 2015 The Android Open Source Project
 *
 * Licensed 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 com.android.statementservice.retriever;

import android.content.Context;
import android.annotation.NonNull;

import java.util.List;

/**
 * Retrieves the statements made by assets. This class is the entry point of the package.
 * <p>
 * An asset is an identifiable and addressable online entity that typically
 * provides some service or content. Examples of assets are websites, Android
 * apps, Twitter feeds, and Plus Pages.
 * <p>
 * Ownership of an asset is defined by being able to control it and speak for it.
 * An asset owner may establish a relationship between the asset and another
 * asset by making a statement about an intended relationship between the two.
 * An example of a relationship is permission delegation. For example, the owner
 * of a website (the webmaster) may delegate the ability the handle URLs to a
 * particular mobile app. Relationships are considered public information.
 * <p>
 * A particular kind of relationship (like permission delegation) defines a binary
 * relation on assets. The relation is not symmetric or transitive, nor is it
 * antisymmetric or anti-transitive.
 * <p>
 * A statement S(r, a, b) is an assertion that the relation r holds for the
 * ordered pair of assets (a, b). For example, taking r = "delegates permission
 * to view user's location", a = New York Times mobile app,
 * b = nytimes.com website, S(r, a, b) would be an assertion that "the New York
 * Times mobile app delegates its ability to use the user's location to the
 * nytimes.com website".
 * <p>
 * A statement S(r, a, b) is considered <b>reliable</b> if we have confidence that
 * the statement is true; the exact criterion depends on the kind of statement,
 * since some kinds of statements may be true on their face whereas others may
 * require multiple parties to agree.
 * <p>
 * For example, to get the statements made by www.example.com use:
 * <pre>
 * result = retrieveStatements(AssetFactory.create(
 *     "{\"namespace\": \"web\", \"site\": \"https://www.google.com\"}"))
 * </pre>
 * {@code result} will contain the statements and the expiration time of this result. The statements
 * are considered reliable until the expiration time.
 */
public abstract class AbstractStatementRetriever {

    /**
     * Returns the statements made by the {@code source} asset with ttl.
     *
     * @throws AssociationServiceException if the asset namespace is not supported.
     */
    public abstract Result retrieveStatements(AbstractAsset source)
            throws AssociationServiceException;

    /**
     * The retrieved statements and the expiration date.
     */
    public interface Result {

        /**
         * @return the retrieved statements.
         */
        @NonNull
        public List<Statement> getStatements();

        /**
         * @return the expiration time in millisecond.
         */
        public long getExpireMillis();
    }

    /**
     * Creates a new StatementRetriever that directly retrieves statements from the asset.
     *
     * <p> For web assets, {@link AbstractStatementRetriever} will try to retrieve the statement
     * file from URL: {@code [webAsset.site]/.well-known/assetlinks.json"} where {@code
     * [webAsset.site]} is in the form {@code http{s}://[hostname]:[optional_port]}. The file
     * should contain one JSON array of statements.
     *
     * <p> For Android assets, {@link AbstractStatementRetriever} will try to retrieve the statement
     * from the AndroidManifest.xml. The developer should add a {@code meta-data} tag under
     * {@code application} tag where attribute {@code android:name} equals "associated_assets"
     * and {@code android:recourse} points to a string array resource. Each entry in the string
     * array should contain exactly one statement in JSON format. Note that this implementation
     * can only return statements made by installed apps.
     */
    public static AbstractStatementRetriever createDirectRetriever(Context context) {
        return new DirectStatementRetriever(new URLFetcher(),
                new AndroidPackageInfoFetcher(context));
    }
}