Package com.esri.arcgisruntime.portal

Class Portal

  • All Implemented Interfaces:
    RemoteResource, Loadable
    public final class Portal
extends Object
implements Loadable, RemoteResource
    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.

    Since:
    100.0.0

    • Constructor Detail

      • Portal

        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 https://www.arcgis.com for ArcGIS Online, or https://<host>:<port>/arcgis for an on-premises portal.
        Throws:
        IllegalArgumentException - if the portalUrl is null or empty
        Since:
        100.0.0

      • Portal

        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 https://www.arcgis.com for ArcGIS Online, or https://<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
        Since:
        100.0.0

    • Method Detail

      • isLoginRequired

        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
        Since:
        100.0.0

      • setCredential

        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.

        Specified by:
        setCredential in interface RemoteResource
        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
        Since:
        100.0.0

      • getCredential

        public Credential getCredential()
        Gets the credential set on this portal instance.
        Specified by:
        getCredential in interface RemoteResource
        Returns:
        the credential, or null if none has been set
        Since:
        100.0.0

      • getPortalInfo

        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
        Since:
        100.0.0
        See Also:
        PortalInfo

      • getUser

        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
        Since:
        100.0.0
        See Also:
        PortalUser

      • getSharingUrl

        public String getSharingUrl()
        Gets the sharing URL, that is, the URL of the root REST resource for the portal. For example https://www.arcgis.com/sharing/rest for ArcGIS Online, or https://<host>:<port>/arcgis/sharing/rest for an on-premises portal.
        Returns:
        the sharing URL
        Since:
        100.0.0

      • setCulture

        public void setCulture​(String culture)
        Sets a code that specifies the culture-specific formatting to use when accessing portal content.

        The culture code provides localized content when viewing featured groups or items, adding or updating an item, and so on. If not explicitly set, the culture used by the device/machine is used. Set it to null if you want to see portal content in the language corresponding to the culture set in the portal/organization settings.

        The format for culture code is based on a language code and a country code separated by a dash. Example: "en-US". For the list of cultures, see Supported languages.

        Parameters:
        culture - the culture code to use, or null to see portal content in the language corresponding to the culture set in the portal/organization settings
        Since:
        100.9.0

      • getCulture

        public String getCulture()
        Gets a code that specifies the culture-specific formatting to use when accessing portal content.

        The culture code provides localized content when viewing featured groups or items, adding or updating an item, and so on. If not explicitly set, the culture used by the device/machine is used.

        The format for culture code is based on a language code and a country code separated by a dash. Example: "en-US". For the list of cultures, see Supported languages.

        Returns:
        the culture code currently in use, or null if none
        Since:
        100.9.0

      • getUri

        public String getUri()
        Gets the portal URL.
        Specified by:
        getUri in interface RemoteResource
        Returns:
        the portal URL
        Since:
        100.0.0

      • getRequestConfiguration

        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.
        Specified by:
        getRequestConfiguration in interface RemoteResource
        Returns:
        the RequestConfiguration object or null if none is set
        Since:
        100.0.0
        See Also:
        RequestConfiguration

      • addCredentialChangedListener

        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
        Since:
        100.0.0

      • removeCredentialChangedListener

        public boolean removeCredentialChangedListener​(CredentialChangedListener credentialChangedListener)
        Attempts to remove a CredentialChangedListener. Returns true if the listener is successfully found and removed.
        Parameters:
        credentialChangedListener - the listener to be removed
        Returns:
        true if the listener is removed
        Throws:
        IllegalArgumentException - if the listener is null
        Since:
        100.0.0

      • fetchLoginTypeForUrlAsync

        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:
        Throws:
        IllegalArgumentException - if url is null or empty
        Since:
        100.0.0

      • fetchFeaturedGroupsAsync

        public ListenableFuture<List<PortalGroup>> fetchFeaturedGroupsAsync()
        Executes an asynchronous operation to fetch the featured groups for the organization. The result is an unmodifiable list of PortalGroup objects. These are fully populated and have a load status of LoadStatus.LOADED.

        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 PortalInfo.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:
        Since:
        100.1.0

      • fetchFeaturedItemsAsync

        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 PortalInfo.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:
        Since:
        100.1.0

      • fetchHomePageFeaturedContentAsync

        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 PortalInfo.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:
        Since:
        100.1.0

      • fetchLicenseInfoAsync

        public ListenableFuture<LicenseInfo> fetchLicenseInfoAsync()
        Executes an asynchronous operation to fetch the current user's LicenseInfo including the entitlements and extensions.
        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:
        Since:
        100.7.0

      • findItemsAsync

        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.

        If you are considering using this method to find items that belong to a group, see PortalGroup.findItemsAsync(PortalGroupContentSearchParameters) for a description of how that method, which uses a Group Content Search operation that's designed specifically for finding items that belong to a group, differs from this method which uses a general-purpose Search operation.

        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:
        Throws:
        IllegalArgumentException - if queryParameters is null
        Since:
        100.0.0

      • findGroupsAsync

        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 collection of PortalGroup objects. These are fully populated and have a load status of LoadStatus.LOADED.
        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:
        Throws:
        IllegalArgumentException - if queryParameters is null
        Since:
        100.0.0

      • postRequestAsync

        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:
        Since:
        100.0.0

      • sendRequestAsync

        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:
        Since:
        100.0.0

      • getLoadStatus

        public LoadStatus getLoadStatus()
        Description copied from interface: Loadable
        Returns the LoadStatus of the loadable resource.
        Specified by:
        getLoadStatus in interface Loadable
        Returns:
        the LoadStatus of the loadable resource

      • cancelLoad

        public void cancelLoad()
        Description copied from interface: Loadable
        Cancels loading metadata for the object.

        Cancels loading the metadata if the object is loading, and always invokes the done loading listener.

        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 Loadable.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.

        Specified by:
        cancelLoad in interface Loadable

      • loadAsync

        public void loadAsync()
        Description copied from interface: Loadable
        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 Loadable.addDoneLoadingListener(java.lang.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 Loadable.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, Loadable.retryLoadAsync() needs to be used.

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

        Specified by:
        loadAsync in interface Loadable

      • retryLoadAsync

        public void retryLoadAsync()
        Description copied from interface: Loadable
        Loads or retries loading metadata for the object asynchronously.

        Will retry loading the metadata if the object's load status is LoadStatus.FAILED_TO_LOAD. Will load the object if it is not loaded. Will not retry to load the object if the object is loaded.

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

        Specified by:
        retryLoadAsync in interface Loadable

      • addDoneLoadingListener

        public void addDoneLoadingListener​(Runnable listener)
        Description copied from interface: Loadable
        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 Loadable.addLoadStatusChangedListener(LoadStatusChangedListener) method instead.

        Specified by:
        addDoneLoadingListener in interface Loadable
        Parameters:
        listener - a Runnable that is invoked upon completion of the load operation

      • removeDoneLoadingListener

        public boolean removeDoneLoadingListener​(Runnable listener)
        Description copied from interface: Loadable
        Removes a done loading listener from the loadable resource.
        Specified by:
        removeDoneLoadingListener in interface Loadable
        Parameters:
        listener - the listener to be removed
        Returns:
        true if the listener was removed, otherwise false

      • addLoadStatusChangedListener

        public void addLoadStatusChangedListener​(LoadStatusChangedListener listener)
        Description copied from interface: Loadable
        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 Loadable.addDoneLoadingListener(Runnable) method.

        Specified by:
        addLoadStatusChangedListener in interface Loadable
        Parameters:
        listener - the LoadStatusChangedListener to be added

      • removeLoadStatusChangedListener

        public boolean removeLoadStatusChangedListener​(LoadStatusChangedListener listener)
        Description copied from interface: Loadable
        Removes a LoadStatusChangedListener from the loadable resource.
        Specified by:
        removeLoadStatusChangedListener in interface Loadable
        Parameters:
        listener - the LoadStatusChangedListener to be removed
        Returns:
        true if the listener was removed, otherwise false

      • isPKCESupported

        public boolean isPKCESupported()
        Returns a boolean that defines if PKCE (proof key code exchange) is supported with this portal. PKCE is supported for portal version 10.9 and higher if OAuth is supported.
        Returns:
        a boolean that defines if PKCE is supported with this portal
        Since:
        100.12.0