GenericDocument

public class GenericDocument
extends Object

java.lang.Object
   ↳ androidx.appsearch.app.GenericDocument


Represents a document unit.

Documents contain structured data conforming to their AppSearchSchema type. Each document is uniquely identified by a namespace and a String ID within that namespace.

Documents are constructed either by using the GenericDocument.Builder or providing an annotated Document data class.

Summary

Nested classes

class GenericDocument.Builder<BuilderType extends Builder>

The builder class for GenericDocument

Protected constructors

GenericDocument(GenericDocument document)

Creates a new GenericDocument from an existing instance.

Public methods

boolean equals(Object other)
static GenericDocument fromDocumentClass(Object document)

Converts an instance of a class annotated with \@Document into an instance of GenericDocument.

long getCreationTimestampMillis()

Returns the creation timestamp of the GenericDocument, in milliseconds.

String getId()

Returns the unique identifier of the GenericDocument.

static int getMaxIndexedProperties()

The maximum number of indexed properties a document can have.

String getNamespace()

Returns the namespace of the GenericDocument.

Object getProperty(String path)

Retrieves the property value with the given path as Object.

boolean getPropertyBoolean(String path)

Retrieves a boolean property by path.

boolean[] getPropertyBooleanArray(String path)

Retrieves a repeated boolean property by path.

byte[] getPropertyBytes(String path)

Retrieves a byte[] property by path.

byte[][] getPropertyBytesArray(String path)

Retrieves a byte[][] property by path.

GenericDocument getPropertyDocument(String path)

Retrieves a GenericDocument property by path.

GenericDocument[] getPropertyDocumentArray(String path)

Retrieves a repeated GenericDocument property by path.

double getPropertyDouble(String path)

Retrieves a double property by path.

double[] getPropertyDoubleArray(String path)

Retrieves a repeated double property by path.

long getPropertyLong(String path)

Retrieves a long property by path.

long[] getPropertyLongArray(String path)

Retrieves a repeated long[] property by path.

Set<String> getPropertyNames()

Returns the names of all properties defined in this document.

String getPropertyString(String path)

Retrieves a String property by path.

String[] getPropertyStringArray(String path)

Retrieves a repeated String property by path.

String getSchemaType()

Returns the AppSearchSchema type of the GenericDocument.

int getScore()

Returns the score of the GenericDocument.

long getTtlMillis()

Returns the TTL (time-to-live) of the GenericDocument, in milliseconds.

int hashCode()
Builder<Builder<?>> toBuilder()

Copies the contents of this GenericDocument into a new GenericDocument.Builder.

<T> T toDocumentClass(Class<T> documentClass)

Converts this GenericDocument into an instance of the provided document class.

String toString()

Inherited methods

Protected constructors

GenericDocument

protected GenericDocument (GenericDocument document)

Creates a new GenericDocument from an existing instance.

This method should be only used by constructor of a subclass.

Parameters
document GenericDocument

Public methods

equals

public boolean equals (Object other)

Parameters
other Object

Returns
boolean

fromDocumentClass

public static GenericDocument fromDocumentClass (Object document)

Converts an instance of a class annotated with \@Document into an instance of GenericDocument.

Parameters
document Object: An instance of a class annotated with \@Document.

Returns
GenericDocument an instance of GenericDocument produced by converting document.

Throws
AppSearchException if no generated conversion class exists on the classpath for the given document class or an unexpected error occurs during conversion.

getCreationTimestampMillis

public long getCreationTimestampMillis ()

Returns the creation timestamp of the GenericDocument, in milliseconds.

The value is in the System.currentTimeMillis() time base.

Returns
long

getId

public String getId ()

Returns the unique identifier of the GenericDocument.

Returns
String

getMaxIndexedProperties

public static int getMaxIndexedProperties ()

The maximum number of indexed properties a document can have.

Indexed properties are properties which are strings where the AppSearchSchema.StringPropertyConfig.getIndexingType() value is anything other than AppSearchSchema.StringPropertyConfig.INDEXING_TYPE_NONE.

Returns
int

getNamespace

public String getNamespace ()

Returns the namespace of the GenericDocument.

Returns
String

getProperty

public Object getProperty (String path)

Retrieves the property value with the given path as Object.

A path can be a simple property name, such as those returned by getPropertyNames(). It may also be a dot-delimited path through the nested document hierarchy, with nested GenericDocument properties accessed via '.' and repeated properties optionally indexed into via [n].

For example, given the following GenericDocument:

     (Message) {
         from: "sender@example.com"
         to: [{
             name: "Albert Einstein"
             email: "einstein@example.com"
           }, {
             name: "Marie Curie"
             email: "curie@example.com"
           }]
         tags: ["important", "inbox"]
         subject: "Hello"
     }
 

Here are some example paths and their results:

  • "from" returns "sender@example.com" as a String array with one element
  • "to" returns the two nested documents containing contact information as a GenericDocument array with two elements
  • "to[1]" returns the second nested document containing Marie Curie's contact information as a GenericDocument array with one element
  • "to[1].email" returns "curie@example.com"
  • "to[100].email" returns null as this particular document does not have that many elements in its "to" array.
  • "to.email" aggregates emails across all nested documents that have them, returning ["einstein@example.com", "curie@example.com"] as a String array with two elements.

If you know the expected type of the property you are retrieving, it is recommended to use one of the typed versions of this method instead, such as getPropertyString(String) or getPropertyStringArray(String).

Parameters
path String: The path to look for.

Returns
Object The entry with the given path as an object or null if there is no such path. The returned object will be one of the following types: String[], long[], double[], boolean[], byte[][], GenericDocument[].

getPropertyBoolean

public boolean getPropertyBoolean (String path)

Retrieves a boolean property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
boolean The first boolean associated with the given path or default value false if there is no such value or the value is of a different type.

getPropertyBooleanArray

public boolean[] getPropertyBooleanArray (String path)

Retrieves a repeated boolean property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
boolean[] The boolean[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyBytes

public byte[] getPropertyBytes (String path)

Retrieves a byte[] property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
byte[] The first byte[] associated with the given path or null if there is no such value or the value is of a different type.

getPropertyBytesArray

public byte[][] getPropertyBytesArray (String path)

Retrieves a byte[][] property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
byte[][] The byte[][] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyDocument

public GenericDocument getPropertyDocument (String path)

Retrieves a GenericDocument property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
GenericDocument The first GenericDocument associated with the given path or null if there is no such value or the value is of a different type.

getPropertyDocumentArray

public GenericDocument[] getPropertyDocumentArray (String path)

Retrieves a repeated GenericDocument property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
GenericDocument[] The GenericDocument[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyDouble

public double getPropertyDouble (String path)

Retrieves a double property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
double The first double associated with the given path or default value 0.0 if there is no such value or the value is of a different type.

getPropertyDoubleArray

public double[] getPropertyDoubleArray (String path)

Retrieves a repeated double property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
double[] The double[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyLong

public long getPropertyLong (String path)

Retrieves a long property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
long The first long associated with the given path or default value 0 if there is no such value or the value is of a different type.

getPropertyLongArray

public long[] getPropertyLongArray (String path)

Retrieves a repeated long[] property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
long[] The long[] associated with the given path, or null if no value is set or the value is of a different type.

getPropertyNames

public Set<String> getPropertyNames ()

Returns the names of all properties defined in this document.

Returns
Set<String>

getPropertyString

public String getPropertyString (String path)

Retrieves a String property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
String The first String associated with the given path or null if there is no such value or the value is of a different type.

getPropertyStringArray

public String[] getPropertyStringArray (String path)

Retrieves a repeated String property by path.

See getProperty(String) for a detailed description of the path syntax.

Parameters
path String: The path to look for.

Returns
String[] The String[] associated with the given path, or null if no value is set or the value is of a different type.

getSchemaType

public String getSchemaType ()

Returns the AppSearchSchema type of the GenericDocument.

Returns
String

getScore

public int getScore ()

Returns the score of the GenericDocument.

The score is a query-independent measure of the document's quality, relative to other GenericDocument objects of the same AppSearchSchema type.

Results may be sorted by score using SearchSpec.Builder.setRankingStrategy(int). Documents with higher scores are considered better than documents with lower scores.

Any non-negative integer can be used a score.

Returns
int

getTtlMillis

public long getTtlMillis ()

Returns the TTL (time-to-live) of the GenericDocument, in milliseconds.

The TTL is measured against getCreationTimestampMillis(). At the timestamp of creationTimestampMillis + ttlMillis, measured in the System.currentTimeMillis() time base, the document will be auto-deleted.

The default value is 0, which means the document is permanent and won't be auto-deleted until the app is uninstalled or AppSearchSession.remove(RemoveByDocumentIdRequest) is called.

Returns
long

hashCode

public int hashCode ()

Returns
int

toBuilder

public Builder<Builder<?>> toBuilder ()

Copies the contents of this GenericDocument into a new GenericDocument.Builder.

The returned builder is a deep copy whose data is separate from this document.

Returns
Builder<Builder<?>>

toDocumentClass

public T toDocumentClass (Class<T> documentClass)

Converts this GenericDocument into an instance of the provided document class.

It is the developer's responsibility to ensure the right kind of document class is being supplied here, either by structuring the application code to ensure the document type is known, or by checking the return value of getSchemaType().

Document properties are identified by String names. Any that are found are assigned into fields of the given document class. As such, the most likely outcome of supplying the wrong document class would be an empty or partially populated result.

Parameters
documentClass Class: a class annotated with Document

Returns