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