public final class

Portal

extends Object
implements RemoteResource Loadable
java.lang.Object
   ↳ com.esri.arcgisruntime.portal.Portal

Class Overview

Represents an information portal such as ArcGIS Online or Portal for ArcGIS. Supports the following operations:

  • sign in to the portal
  • get metadata describing the portal
  • search the portal for content such as portal items and groups
  • fetch items from the portal

Note that if a Portal is initially loaded anonymously and attempts to access a secured resource, an AuthenticationChallenge will be issued. If the challenge results in a Credential object that satisfies the secure resource, that Credential will be set back on the Portal. At this point, subsequent requests will use that Credential for authentication. The PortalInfo and PortalUser, however, will remain as the anonymous versions as they were initially loaded. If these objects are desired to have privileged information, then a new Portal instance needs to be constructed and the Credential needs to be set using setCredential(Credential) before loading the new Portal instance.

Summary

Nested Classes
enum Portal.LoginType Signifies the login type for a portal. 
enum Portal.Mode Signifies the tenancy mode of a portal. 
Public Constructors
Portal(String portalUrl)
Creates a Portal for anonymous access using the portal URL.
Portal(String portalUrl, boolean loginRequired)
Creates a Portal for anonymous or authenticated access using the portal URL, depending on the value of the loginRequired parameter.
Public Methods
void addCredentialChangedListener(CredentialChangedListener credentialChangedListener)
Adds a CredentialChangedListener to be called when the Portal's Credential is changed.
void addDoneLoadingListener(Runnable listener)
Adds a listener to the loadable resource that is invoked when loading has completed.
void addLoadStatusChangedListener(LoadStatusChangedListener listener)
Adds a LoadStatusChangedListener to the loadable resource that is invoked whenever the load status changes.
void cancelLoad()
Cancels a pending load operation.
ListenableFuture<List<Basemap>> fetchBasemapsAsync()
Executes an asynchronous operation to fetch the basemaps in the basemap gallery for the organization.
ListenableFuture<List<PortalGroup>> fetchFeaturedGroupsAsync()
Executes an asynchronous operation to fetch the featured groups for the organization.
ListenableFuture<List<PortalItem>> fetchFeaturedItemsAsync()
Executes an asynchronous operation to fetch the featured items for the organization.
ListenableFuture<List<PortalItem>> fetchHomePageFeaturedContentAsync()
Executes an asynchronous operation to fetch the featured content for display on the organization's home page.
static ListenableFuture<Portal.LoginType> fetchLoginTypeForUrlAsync(String url)
Executes an asynchronous operation to determine the login type for a given portal URL.
ListenableFuture<PortalQueryResultSet<PortalGroup>> findGroupsAsync(PortalQueryParameters queryParameters)
Executes an asynchronous operation to find groups in this portal with a query using the specified portal query parameters.
ListenableFuture<PortalQueryResultSet<PortalItem>> findItemsAsync(PortalQueryParameters queryParameters)
Executes an asynchronous operation to find items in this portal with a query using the specified portal query parameters.
Credential getCredential()
Gets the credential set on this portal instance.
ArcGISRuntimeException getLoadError()
Returns the most recent error that was encountered when the loadable resource transitioned to the FAILED_TO_LOAD state, either due to calling loadAsync or retryLoadAsync.
LoadStatus getLoadStatus()
Returns the LoadStatus of the loadable resource.
PortalInfo getPortalInfo()
Gets the PortalInfo object for this portal.
RequestConfiguration getRequestConfiguration()
Gets the RequestConfiguration object in use by this Portal.
String getSharingUrl()
Gets the sharing URL, that is, the URL of the root REST resource for the portal.
String getUri()
Gets the portal URL.
PortalUser getUser()
Gets a PortalUser object describing the user currently signed in to this portal.
boolean isLoginRequired()
Indicates if loginRequired was specified when this Portal object was constructed.
void loadAsync()
Loads the metadata of the loadable resource asynchronously.
ListenableFuture<String> postRequestAsync(String requestUrl)
Executes an asynchronous operation to send a customized request and let the caller handle the response.
boolean removeCredentialChangedListener(CredentialChangedListener credentialChangedListener)
Attempts to remove a CredentialChangedListener.
boolean removeDoneLoadingListener(Runnable listener)
Removes a done loading listener from the loadable resource.
boolean removeLoadStatusChangedListener(LoadStatusChangedListener listener)
Removes a LoadStatusChangedListener from the loadable resource.
void retryLoadAsync()
Tries to reload the metadata of the loadable resource asynchronously, but only if the resource failed to load previously (LoadStatus.FAILED_TO_LOAD state) or wasn't loaded to begin with ( LoadStatus.NOT_LOADED state).
ListenableFuture<String> sendRequestAsync(String requestUrl)
Executes an asynchronous operation to send a customized request and let the caller handle the response.
void setCredential(Credential credential)
Sets the credential used to authenticate the user with the Portal.
void setRequestConfiguration(RequestConfiguration requestConfiguration)
Sets configuration parameters used for network requests sent using this Portal object.
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.esri.arcgisruntime.io.RemoteResource
From interface com.esri.arcgisruntime.loadable.Loadable

Public Constructors

public Portal (String portalUrl)

Creates a Portal for anonymous access using the portal URL. If the portal does not support anonymous access, an AuthenticationChallenge will be issued to obtain credentials. If valid credentials are not supplied, the portal will fail to load. This is the same as calling new Portal(url, false). If the app knows the credential to use in advance, it can avoid an AuthenticationChallenge by calling setCredential(Credential) after this constructor and before loading this Portal.

Parameters
portalUrl the portal URL. For example http://www.arcgis.com for ArcGIS Online, or http://<host>:<port>/arcgis for an on-premises portal.
Throws
IllegalArgumentException if the portalUrl is null or empty

public Portal (String portalUrl, boolean loginRequired)

Creates a Portal for anonymous or authenticated access using the portal URL, depending on the value of the loginRequired parameter. If true is passed, then the user will be required to login to the portal in order to use it at all (this will be done using the AuthenticationChallengeHandler, so the credential does not need to be known in advance). If it is false, then the user will only be required to login if the portal does not support anonymous access (that is, if the PortalAccess is PRIVATE). If the app knows the credential to use in advance, it can avoid an AuthenticationChallenge by calling setCredential(Credential) after this constructor and before loading this Portal.

Parameters
portalUrl the portal URL. For example http://www.arcgis.com for ArcGIS Online, or http://<host>:<port>/arcgis for an on-premises portal.
loginRequired true to force user login, false to only login if required by the portal
Throws
IllegalArgumentException if the portalUrl is null or empty

Public Methods

public void addCredentialChangedListener (CredentialChangedListener credentialChangedListener)

Adds a CredentialChangedListener to be called when the Portal's Credential is changed. If the Credential is changed the app may want to create and load a new Portal object using the new Credential.

This listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

Parameters
credentialChangedListener the CredentialChangedListener to add
Throws
IllegalArgumentException if the listener is null

public void addDoneLoadingListener (Runnable listener)

Adds a listener to the loadable resource that is invoked when loading has completed.

The listener may be added at any point, whether the loadable resource has already completed loading or not.

  • For resources that are not loaded when the listener is added (LoadStatus is NOT_LOADED or LOADING): When the resource completes loading, the listener will be invoked on the UI thread if it is added from the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.
  • For resources that are already loaded when the listener is added (LoadStatus is LOADED or FAILED_TO_LOAD): The listener will be called immediately, on the current thread.

Alternatively, to be notified when there is any change in the load status, use the addLoadStatusChangedListener(LoadStatusChangedListener) method instead.

Parameters
listener a Runnable that is invoked upon completion of the load operation

public void addLoadStatusChangedListener (LoadStatusChangedListener listener)

Adds a LoadStatusChangedListener to the loadable resource that is invoked whenever the load status changes.

Adding this listener on the UI thread will cause it to be invoked on the UI thread, otherwise it is not guaranteed on which thread the listener is invoked.

The listener will not be called if added to a loadable resource that has already completed loading. To be notified when a loadable resource has completed loading, including if the resource is already loaded when the listener is added, use the addDoneLoadingListener(Runnable) method.

Parameters
listener the LoadStatusChangedListener to be added

public void cancelLoad ()

Cancels a pending load operation.

A load operation that is in progress (LoadStatus.LOADING state) can be cancelled by calling this method and the resource will transition from LoadStatus.LOADING to LoadStatus.FAILED_TO_LOAD state. If the load operation was successfully cancelled a CancellationException will be returned from getLoadError().

Cancellation should be used carefully because all enqueued done loading listeners for that resource instance will get invoked with an error stating that the operation was cancelled. Thus, one component in the application can cancel the load operation initiated by other components.

This method does nothing if the resource is not in LoadStatus.LOADING state.

public ListenableFuture<List<Basemap>> fetchBasemapsAsync ()

Executes an asynchronous operation to fetch the basemaps in the basemap gallery for the organization. The result is an unmodifiable list of Basemaps. The Basemaps are not loaded, but their PortalItem metadata are available using getItem().

Note: the size of the resultant list is limited to 25. If a portal has more than 25 basemaps, they can all be fetched by using getBasemapGalleryGroupQuery(), findGroupsAsync(PortalQueryParameters) and findItemsAsync(PortalQueryParameters).

Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if a network request fails

public ListenableFuture<List<PortalGroup>> fetchFeaturedGroupsAsync ()

Executes an asynchronous operation to fetch the featured groups for the organization. The result is an unmodifiable list of PortalGroups.

Note: the size of the resultant list is limited to 25. If an organization has more than 25 featured groups, they can all be fetched by using getFeaturedGroupsQueries() and findGroupsAsync(PortalQueryParameters).

Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if a network request fails

public ListenableFuture<List<PortalItem>> fetchFeaturedItemsAsync ()

Executes an asynchronous operation to fetch the featured items for the organization. The result is an unmodifiable list of PortalItems.

Note: the size of the resultant list is limited to 25. If an organization has more than 25 featured items, they can all be fetched by using getFeaturedItemsGroupQuery(), findGroupsAsync(PortalQueryParameters) and findItemsAsync(PortalQueryParameters).

Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if a network request fails

public ListenableFuture<List<PortalItem>> fetchHomePageFeaturedContentAsync ()

Executes an asynchronous operation to fetch the featured content for display on the organization's home page. The result is an unmodifiable list of PortalItems.

Note: the size of the resultant list is limited to 25. If an organization has more than 25 home page featured items, they can all be fetched by using getHomePageFeaturedContentGroupQuery(), findGroupsAsync(PortalQueryParameters) and findItemsAsync(PortalQueryParameters).

Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if a network request fails

public static ListenableFuture<Portal.LoginType> fetchLoginTypeForUrlAsync (String url)

Executes an asynchronous operation to determine the login type for a given portal URL. The result is a LoginType enum.

Parameters
url the URL
Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if a network request fails
Throws
IllegalArgumentException if url is null or empty

public ListenableFuture<PortalQueryResultSet<PortalGroup>> findGroupsAsync (PortalQueryParameters queryParameters)

Executes an asynchronous operation to find groups in this portal with a query using the specified portal query parameters. The result is a PortalQueryResultSet object containing a set of portal groups.

Parameters
queryParameters parameters used to search the portal
Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if the network request fails
Throws
IllegalArgumentException if queryParameters is null

public ListenableFuture<PortalQueryResultSet<PortalItem>> findItemsAsync (PortalQueryParameters queryParameters)

Executes an asynchronous operation to find items in this portal with a query using the specified portal query parameters. The result is a PortalQueryResultSet object containing a set of portal items.

Parameters
queryParameters parameters used to search the portal
Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if the network request fails
Throws
IllegalArgumentException if queryParameters is null

public Credential getCredential ()

Gets the credential set on this portal instance.

Returns
  • the credential, or null if none has been set

public ArcGISRuntimeException getLoadError ()

Returns the most recent error that was encountered when the loadable resource transitioned to the FAILED_TO_LOAD state, either due to calling loadAsync or retryLoadAsync.

If the resource subsequently transitions to LOADED, for example if a call to retryLoadAsync completes successfully, the error is cleared out.

Returns
  • the most recent error that was encountered when the loadable resource transitioned to the LoadStatus.FAILED_TO_LOAD state.

public LoadStatus getLoadStatus ()

Returns the LoadStatus of the loadable resource.

Returns
  • the LoadStatus of the loadable resource

public PortalInfo getPortalInfo ()

Gets the PortalInfo object for this portal.

Returns
  • the PortalInfo object for this portal, or null if the portal is not loaded yet
See Also

public RequestConfiguration getRequestConfiguration ()

Gets the RequestConfiguration object in use by this Portal. If null is returned, then that indicates that the global RequestConfiguration is used instead.

Returns
  • the RequestConfiguration object or null if none is set

public String getSharingUrl ()

Gets the sharing URL, that is, the URL of the root REST resource for the portal. For example http://www.arcgis.com/sharing/rest for ArcGIS Online, or http://<host>:<port>/arcgis/sharing/rest for an on-premises portal.

Returns
  • the sharing URL

public String getUri ()

Gets the portal URL.

Returns
  • the portal URL that was passed to the constructor

public PortalUser getUser ()

Gets a PortalUser object describing the user currently signed in to this portal.

Returns
  • a PortalUser object, or null if no user is signed in due to anonymous access or portal not loaded yet
See Also

public boolean isLoginRequired ()

Indicates if loginRequired was specified when this Portal object was constructed.

Returns
  • true if login is required, false if anonymous access is allowed

public void loadAsync ()

Loads the metadata of the loadable resource asynchronously.

The load status changes from LoadStatus.NOT_LOADED to LoadStatus.LOADING. A listener can be added via addDoneLoadingListener(Runnable) that is invoked upon completion of the asynchronous load operation.

If the load operation completes successfully, the load status will be LoadStatus.LOADED, which means the resource has loaded its metadata.

If the load operation failed, the load status will be LoadStatus.FAILED_TO_LOAD and the error can be retrieved by calling getLoadError().

This method can be called concurrently and repeatedly, but only one attempt is ever made to perform the load operation. If a load operation is already in progress (LoadStatus.LOADING state) when loadAsync is called, it simply piggy-backs on the outstanding operation and the done loading listener added to the loadable resource is enqueued to be invoked when that operation completes. If the operation has already completed (LoadStatus.LOADED or LoadStatus.FAILED_TO_LOAD state) when loadAsync is called, the done loading listener is immediately invoked when added to the loadable resource.

If a loadable resource has failed to load, calling loadAsync on it subsequently will not change its state. The done loading listener will be invoked immediately when added to the loadable resource. In order to retry loading the resource, retryLoadAsync() needs to be used.

A load operation that is in progress (LoadStatus.LOADING state) can be cancelled by calling cancelLoad().

public ListenableFuture<String> postRequestAsync (String requestUrl)

Executes an asynchronous operation to send a customized request and let the caller handle the response. The request will be sent using the "POST" method. The result is a String object containing JSON.

Parameters
requestUrl the URL of the request
Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if the network request fails

public boolean removeCredentialChangedListener (CredentialChangedListener credentialChangedListener)

Attempts to remove a CredentialChangedListener. Returns true if the listener is successfully found and removed.

Returns
  • true if the listener is removed
Throws
IllegalArgumentException if the listener is null

public boolean removeDoneLoadingListener (Runnable listener)

Removes a done loading listener from the loadable resource.

Parameters
listener the listener to be removed
Returns
  • true if the listener was removed, otherwise false

public boolean removeLoadStatusChangedListener (LoadStatusChangedListener listener)

Removes a LoadStatusChangedListener from the loadable resource.

Parameters
listener the LoadStatusChangedListener to be removed
Returns
  • true if the listener was removed, otherwise false

public void retryLoadAsync ()

Tries to reload the metadata of the loadable resource asynchronously, but only if the resource failed to load previously (LoadStatus.FAILED_TO_LOAD state) or wasn't loaded to begin with ( LoadStatus.NOT_LOADED state).

For more details on the load process see loadAsync().

public ListenableFuture<String> sendRequestAsync (String requestUrl)

Executes an asynchronous operation to send a customized request and let the caller handle the response. The request will be sent using the "POST" or "GET" method based on the length of the URL. The result is a String object containing JSON.

Parameters
requestUrl the URL of the request
Returns
  • a ListenableFuture for tracking when the operation is done and getting the result; also allows cancellation. Calling get() on the returned future may throw an ExecutionException with its cause set to an exception as follows:
    • IOException if the network request fails

public void setCredential (Credential credential)

Sets the credential used to authenticate the user with the Portal. If set after a Portal is loaded anonymously, the credential will be used for subsequent requests but the PortalInfo will remain the anonymous info. To obtain a privileged PortalInfo, the credential must be set before the instance is loaded.

If the credential being set is different from the portal's current credential (or the portal's current credential is null), this will trigger any CredentialChangedListeners that were added with addCredentialChangedListener(CredentialChangedListener)

Do not set new credentials while the portal is still loading as that can lead the portal to be in an undetermined state.

Parameters
credential the credential used to authenticate the user with the portal
Throws
IllegalArgumentException if the Credential is null
IllegalStateException if the credential cannot be set because the Portal has been loaded and already has a credential

public void setRequestConfiguration (RequestConfiguration requestConfiguration)

Sets configuration parameters used for network requests sent using this Portal object. The global RequestConfiguration is used if no RequestConfiguration is set or null is set (see getGlobalRequestConfiguration()).

Parameters
requestConfiguration object containing the parameters to use