# ReadOnlyGlobalSearchSession

Artifact: [androidx.appsearch:appsearch](https://developer.android.com/jetpack/androidx/releases/appsearch) [View Source](https://cs.android.com/search?q=file:androidx/appsearch/app/ReadOnlyGlobalSearchSession.java+class:androidx.appsearch.app.ReadOnlyGlobalSearchSession) Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

*** ** * ** ***


```
public interface ReadOnlyGlobalSearchSession
```

<br />

Known direct subclasses [EnterpriseGlobalSearchSession](https://developer.android.com/reference/androidx/appsearch/app/EnterpriseGlobalSearchSession), [GlobalSearchSession](https://developer.android.com/reference/androidx/appsearch/app/GlobalSearchSession)

|---|---|
| `https://developer.android.com/reference/androidx/appsearch/app/EnterpriseGlobalSearchSession` | Provides a connection to all enterprise (work profile) AppSearch databases the querying application has been granted access to. |
| `https://developer.android.com/reference/androidx/appsearch/app/GlobalSearchSession` | Provides a connection to all AppSearch databases the querying application has been granted access to. |

*** ** * ** ***

Provides a connection to query over all AppSearch databases that the calling application has been granted access to.

This interface is strictly for read-only operations, such as searching for documents (`https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#search(java.lang.String,androidx.appsearch.app.SearchSpec)`), retrieving documents by ID (`https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#getByDocumentIdAsync(java.lang.String,java.lang.String,androidx.appsearch.app.GetByDocumentIdRequest)`), and fetching schemas (`https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#getSchemaAsync(java.lang.String,java.lang.String)`). It does not include methods for writing data.

All implementations of this interface must be thread safe.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSession` |   |

## Summary

| ### Public methods |
|---|---|
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/appsearch/app/AppSearchBatchResult<https://developer.android.com/reference/java/lang/String.html, https://developer.android.com/reference/androidx/appsearch/app/GenericDocument>>` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = https://developer.android.com/reference/androidx/appsearch/app/Features.GLOBAL_SEARCH_SESSION_GET_BY_ID) https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#getByDocumentIdAsync(java.lang.String,java.lang.String,androidx.appsearch.app.GetByDocumentIdRequest)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html packageName, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html databaseName, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/GetByDocumentIdRequest request )` Retrieves `https://developer.android.com/reference/androidx/appsearch/app/GenericDocument` documents, belonging to the specified package name and database name and identified by the namespace and ids in the request, from the `https://developer.android.com/reference/androidx/appsearch/app/GlobalSearchSession` database. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/Features` | `https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#getFeatures()()` Returns the `https://developer.android.com/reference/androidx/appsearch/app/Features` to check for the availability of certain features for this session. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/appsearch/app/GetSchemaResponse>` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = https://developer.android.com/reference/androidx/appsearch/app/Features.GLOBAL_SEARCH_SESSION_GET_SCHEMA) https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#getSchemaAsync(java.lang.String,java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html packageName, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html databaseName)` Retrieves the collection of schemas most recently successfully provided to `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSession#setSchemaAsync(androidx.appsearch.app.SetSchemaRequest)` for any types belonging to the requested package and database that the caller has been granted access to. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = https://developer.android.com/reference/androidx/appsearch/app/Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK) https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#registerObserverCallback(java.lang.String,androidx.appsearch.observer.ObserverSpec,java.util.concurrent.Executor,androidx.appsearch.observer.ObserverCallback)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetPackageName, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverSpec spec, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback observer )` Adds an `https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback` to monitor changes within the databases owned by `targetPackageName` if they match the given `https://developer.android.com/reference/androidx/appsearch/observer/ObserverSpec`. |
| `abstract @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/SearchResults` | `https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#search(java.lang.String,androidx.appsearch.app.SearchSpec)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html queryExpression, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/SearchSpec searchSpec)` Retrieves documents from all AppSearch databases that the querying application has access to. |
| `abstract void` | `@https://developer.android.com/reference/androidx/annotation/RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = https://developer.android.com/reference/androidx/appsearch/app/Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK) https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#unregisterObserverCallback(java.lang.String,androidx.appsearch.observer.ObserverCallback)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetPackageName, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback observer )` Removes previously registered `https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback` instances from the system. |

## Public methods

### getByDocumentIdAsync

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_BY_ID)
abstract @NonNull ListenableFuture<AppSearchBatchResult<String, GenericDocument>> getByDocumentIdAsync(
    @NonNull String packageName,
    @NonNull String databaseName,
    @NonNull GetByDocumentIdRequest request
)
```

Retrieves `https://developer.android.com/reference/androidx/appsearch/app/GenericDocument` documents, belonging to the specified package name and database name and identified by the namespace and ids in the request, from the `https://developer.android.com/reference/androidx/appsearch/app/GlobalSearchSession` database. When a call is successful, the result will be returned in the successes section of the `https://developer.android.com/reference/androidx/appsearch/app/AppSearchBatchResult` object in the callback. If the package doesn't exist, database doesn't exist, or if the calling package doesn't have access, these failures will be reflected as `https://developer.android.com/reference/androidx/appsearch/app/AppSearchResult` objects with a RESULT_NOT_FOUND status code in the failures section of the `https://developer.android.com/reference/androidx/appsearch/app/AppSearchBatchResult` object.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html packageName` | the name of the package to get from |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html databaseName` | the name of the database to get from |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/GetByDocumentIdRequest request` | a request containing a namespace and IDs of the documents to retrieve. |

### getFeatures

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
abstract @NonNull Features getFeatures()
```

Returns the `https://developer.android.com/reference/androidx/appsearch/app/Features` to check for the availability of certain features for this session.

### getSchemaAsync

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_GET_SCHEMA)
abstract @NonNull ListenableFuture<GetSchemaResponse> getSchemaAsync(@NonNull String packageName, @NonNull String databaseName)
```

Retrieves the collection of schemas most recently successfully provided to `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSession#setSchemaAsync(androidx.appsearch.app.SetSchemaRequest)` for any types belonging to the requested package and database that the caller has been granted access to.

If the requested package/database combination does not exist or the caller has not been granted access to it, then an empty GetSchemaResponse will be returned.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html packageName` | the package that owns the requested `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSchema` instances. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html databaseName` | the database that owns the requested `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSchema` instances. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://guava.dev/releases/snapshot-android/api/docs/com/google/common/util/concurrent/ListenableFuture.html<https://developer.android.com/reference/androidx/appsearch/app/GetSchemaResponse>` | The pending `https://developer.android.com/reference/androidx/appsearch/app/GetSchemaResponse` containing the schemas that the caller has access to or an empty GetSchemaResponse if the request package and database does not exist, has not set a schema or contains no schemas that are accessible to the caller. |

### registerObserverCallback

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
abstract void registerObserverCallback(
    @NonNull String targetPackageName,
    @NonNull ObserverSpec spec,
    @NonNull Executor executor,
    @NonNull ObserverCallback observer
)
```

Adds an `https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback` to monitor changes within the databases owned by `targetPackageName` if they match the given `https://developer.android.com/reference/androidx/appsearch/observer/ObserverSpec`.

The observer callback is only triggered for data that changes after it is registered. No notification about existing data is sent as a result of registering an observer. To find out about existing data, you must use the `https://developer.android.com/reference/androidx/appsearch/app/ReadOnlyGlobalSearchSession#search(java.lang.String,androidx.appsearch.app.SearchSpec)` API.

If the data owned by `targetPackageName` is not visible to you, the registration call will succeed but no notifications will be dispatched. Notifications could start flowing later if `targetPackageName` changes its schema visibility settings.

If no package matching `targetPackageName` exists on the system, the registration call will succeed but no notifications will be dispatched. Notifications could start flowing later if `targetPackageName` is installed and starts indexing data.

This feature may not be available in all implementations. Check `https://developer.android.com/reference/androidx/appsearch/app/Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK()` before calling this method.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetPackageName` | Package whose changes to monitor |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverSpec spec` | Specification of what types of changes to listen for |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/concurrent/Executor.html executor` | Executor on which to call the `observer` callback methods. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback observer` | Callback to trigger when a schema or document changes |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/appsearch/exceptions/AppSearchException` | if an error occurs trying to register the observer |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | if this feature is not available on this AppSearch implementation. |

### search

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
abstract @NonNull SearchResults search(@NonNull String queryExpression, @NonNull SearchSpec searchSpec)
```

Retrieves documents from all AppSearch databases that the querying application has access to.

Applications can be granted access to documents by specifying `https://developer.android.com/reference/androidx/appsearch/app/SetSchemaRequest.Builder#setSchemaTypeVisibilityForPackage(java.lang.String,boolean,androidx.appsearch.app.PackageIdentifier)`, or `https://developer.android.com/reference/androidx/appsearch/app/SetSchemaRequest.Builder#setDocumentClassVisibilityForPackage(java.lang.Class<?>,boolean,androidx.appsearch.app.PackageIdentifier)` when building a schema.

Document access can also be granted to system UIs by specifying `https://developer.android.com/reference/androidx/appsearch/app/SetSchemaRequest.Builder#setSchemaTypeDisplayedBySystem(java.lang.String,boolean)`, or `https://developer.android.com/reference/androidx/appsearch/app/SetSchemaRequest.Builder#setDocumentClassDisplayedBySystem(java.lang.Class<?>,boolean)` when building a schema.

See `https://developer.android.com/reference/androidx/appsearch/app/AppSearchSession#search(java.lang.String,androidx.appsearch.app.SearchSpec)` for a detailed explanation on forming a query string.

This method is lightweight. The heavy work will be done in `https://developer.android.com/reference/androidx/appsearch/app/SearchResults#getNextPageAsync()`.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html queryExpression` | query string to search. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/SearchSpec searchSpec` | spec for setting document filters, adding projection, setting term match type, etc. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/app/SearchResults` | a `https://developer.android.com/reference/androidx/appsearch/app/SearchResults` object for retrieved matched documents. |

### unregisterObserverCallback

Added in [1.2.0-alpha02](https://developer.android.com/jetpack/androidx/releases/appsearch#1.2.0-alpha02)

```
@RequiresFeature(enforcement = "androidx.appsearch.app.Features#isFeatureSupported", name = Features.GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK)
abstract void unregisterObserverCallback(
    @NonNull String targetPackageName,
    @NonNull ObserverCallback observer
)
```

Removes previously registered `https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback` instances from the system.

All instances of `https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback` which are registered to observe `targetPackageName` and compare equal to the provided callback using the provided argument's equals will be removed.

If no matching observers have been registered, this method has no effect. If multiple matching observers have been registered, all will be removed.

This feature may not be available in all implementations. Check `https://developer.android.com/reference/androidx/appsearch/app/Features#GLOBAL_SEARCH_SESSION_REGISTER_OBSERVER_CALLBACK()` before calling this method.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html targetPackageName` | Package which the observers to be removed are listening to. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/appsearch/observer/ObserverCallback observer` | Callback to unregister. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/appsearch/exceptions/AppSearchException` | if an error occurs trying to remove the observer, such as a failure to communicate with the system service in the platform backend. Note that no error will be thrown if the provided observer doesn't match any registered observer. |
| `https://developer.android.com/reference/java/lang/UnsupportedOperationException.html` | if this feature is not available on this AppSearch implementation. |