Package com.esri.arcgisruntime.portal

Class PortalItem

  • All Implemented Interfaces:
    JsonSerializable, Loadable
    public final class PortalItem
extends Item
implements JsonSerializable
    Represents an item (a unit of content) stored in an ArcGIS portal. Contains information about the item such as the item's unique ID, the owning Portal, and the type of item it is (PortalItem.Type), for example a web map, a map service, or a tile package.

    The portal item ID can be used along with a portal URL to quickly instantiate a new portal item object. The ID can be determined from the URL of the item details web page or the map viewer URL (for maps only) in your portal. The item details page has the following format: http://www.arcgis.com/home/item.html?id=[item_id]. The webmap viewer has the following format: http://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id]. In both cases the [item_id] can be used as the ID to instantiate a portal item.

    A PortalItem can be used to create an instance of the item for item types supported by this API. For example an ArcGISMap can be created from a PortalItem of type PortalItem.Type.WEBMAP via ArcGISMap(PortalItem) and displayed in an application.

    This class contains metadata about the portal item rather than the content of the item itself. The content for a particular item (such as an ArcGISMap) will be retrieved when the item instance is loaded.

    Since:
    100.0.0
    See Also:
    Basemap.getItem(), GeoModel.getItem(), Layer.getItem()

    • Constructor Detail

      • PortalItem

        public PortalItem​(Portal portal,
                  String itemId)
        Creates a portal item object for a specified portal and a specified item ID.

        Use this constructor to instantiate a PortalItem from an existing item using its unique ID.

        The portal item ID can be determined from the URL of the item details web page or the map viewer URL (for maps only) in your portal. The item details page has the following format: https://www.arcgis.com/home/item.html?id=[item_id]. The webmap viewer has the following format: https://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id]. The webscene viewer has the following format: https://www.arcgis.com/home/webscene/viewer.html?webscene=[item_id]. In all cases, the [item_id] can be used as the ID to instantiate a portal item.

        Parameters:
        portal - the portal the item belongs to
        itemId - the ID for the item
        Throws:
        IllegalArgumentException - if portal is null or if itemId is null or empty
        Since:
        100.0.0

      • PortalItem

        public PortalItem​(Portal portal,
                  PortalItem.Type type,
                  String title,
                  String description,
                  String snippet,
                  Iterable<String> tags)
        Constructor for use if you wish to add a new item to a portal. Pass the resultant object to PortalUser.addPortalItemAsync(PortalItem, PortalItemContentParameters, PortalFolder) to add the item. You must do this to populate the PortalItem with a portal item ID, which is necessary before calling many of the methods on this object.
        Parameters:
        portal - the portal to which the item will be added
        type - the type of the item
        title - the title of the item
        description - the description of the item, or null if none
        snippet - the summary description snippet of the item, or null if none
        tags - the tags associated with the item, or null if none
        Throws:
        IllegalArgumentException - if portal, type or title is null
        IllegalArgumentException - if title is an empty string
        Since:
        100.0.0

    • Method Detail

      • fromJson

        public static PortalItem fromJson​(String json,
                                  Portal portal)
        Creates a PortalItem from a JSON string.
        Parameters:
        json - the JSON string
        portal - the Portal object for use by the PortalItem
        Returns:
        the PortalItem
        Throws:
        IllegalArgumentException - if portal is null or json is null or empty
        Since:
        100.0.0

      • toJson

        public String toJson()
        Description copied from interface: JsonSerializable
        Serializes this object to a JSON string. Note that unknown JSON is omitted from the serialized string.
        Specified by:
        toJson in interface JsonSerializable
        Returns:
        a JSON string

      • getUnknownJson

        public Map<String,​Object> getUnknownJson()
        Description copied from interface: JsonSerializable
        If this object was created from JSON, this method gets unknown data from the source JSON. Unknown JSON is a Map of values that were in the source JSON but are not known by the Runtime and therefore not exposed in the API.
        Specified by:
        getUnknownJson in interface JsonSerializable
        Returns:
        an unmodifiable Map containing unknown JSON data. The keys are Strings containing names. The types of the values depend on the types of tokens within the JSON as follows:
        • a Map<String, Object> represents an object in the JSON
        • a List<Object> represents an array in the JSON
        • a String represents a string in the JSON
        • a Double represents a number in the JSON
        • a Boolean represents true or false in the JSON
        • null represents null in the JSON

      • getUnsupportedJson

        public Map<String,​Object> getUnsupportedJson()
        Description copied from interface: JsonSerializable
        If this object was created from JSON, this method gets unsupported data from the source JSON. Unsupported JSON is a Map of values that are supported by webmaps and known to the version of the webmap specification the API supports (see system requirements), but are not explicitly exposed through the Runtime API.
        Specified by:
        getUnsupportedJson in interface JsonSerializable
        Returns:
        an unmodifiable Map containing unsupported JSON data. The keys are Strings containing names. The types of the values depend on the types of tokens within the JSON as follows:
        • a Map<String, Object> represents an object in the JSON
        • a List<Object> represents an array in the JSON
        • a String represents a string in the JSON
        • a Double represents a number in the JSON
        • a Boolean represents true or false in the JSON
        • null represents null in the JSON

      • getAccess

        public PortalItem.Access getAccess()
        Gets the access level of this item.
        Returns:
        the access level of this item
        Since:
        100.0.0

      • getAverageRating

        public float getAverageRating()
        Gets the average rating of this item.
        Returns:
        the average rating of this item
        Since:
        100.0.0

      • getAccessAndUseConstraintsHtml

        @Deprecated
public String getAccessAndUseConstraintsHtml()
        Deprecated.
        As of 100.4.0, replaced by Item.getTermsOfUse().
        Gets a description of any access and use constraints for this item. This may include HTML markup.
        Returns:
        the access and use constraints
        Since:
        100.0.0

      • getCommentCount

        public int getCommentCount()
        Gets the number of comments on this item.
        Returns:
        the number of comments on this item
        Since:
        100.0.0

      • getCulture

        public String getCulture()
        Gets the item locale (language and country) information.
        Returns:
        the item locale
        Since:
        100.4.0

      • getRatingCount

        public int getRatingCount()
        Gets the number of ratings on this item.
        Returns:
        the number of ratings on this item
        Since:
        100.0.0

      • getViewCount

        public int getViewCount()
        Gets the number of times this item has been viewed.
        Returns:
        the number of times this item has been viewed
        Since:
        100.0.0

      • getOwner

        public String getOwner()
        Gets the username of the owner of this item.
        Returns:
        the username of the owner of this item
        Since:
        100.0.0

      • getFolderId

        public String getFolderId()
        Gets the ID of the folder in which the owner has stored this item.
        Returns:
        the ID of the folder in which the owner has stored this item; an empty string indicates the owner's root folder; null indicates the folder is unknown
        Since:
        100.0.0

      • getGuid

        @Deprecated
public String getGuid()
        Deprecated.
        As of 100.5.0, use Item.getItemId() as a unique ID for items on a portal.
        Gets the GUID of this item.
        Returns:
        the GUID of this item
        Since:
        100.3.0

      • getPortal

        public Portal getPortal()
        Gets the portal this item belongs to.
        Returns:
        the portal this item belongs to
        Since:
        100.0.0

      • getServiceUrl

        public String getServiceUrl()
        Gets the URL of the service this item represents. Applies only to items that represent web-accessible resources such as map services.
        Returns:
        the URL of the service this item represents; an empty string if the item doesn't represent a web-accessible resource
        Since:
        100.3.0

      • getSize

        public long getSize()
        Gets the size of this item.
        Returns:
        the size of this item in kilobytes
        Since:
        100.0.0

      • getThumbnailFileName

        public String getThumbnailFileName()
        Gets the filename of the thumbnail for this item. This is actually a relative path that may contain a folder name as well as a filename, for example "thumbnail/thumbnail.jpg".
        Returns:
        the filename of the thumbnail for this item, or null if there's no thumbnail
        Since:
        100.0.0

      • getType

        public PortalItem.Type getType()
        Gets the type of this item.
        Returns:
        the type of this item
        Since:
        100.0.0

      • getTypeName

        public String getTypeName()
        Gets the type name for this item.

        Most generally the type name is the string representation of the Type returned by getType(). However if the type is unknown, the type name is set with the type found in the portal item JSON. This allows the API to deal with new portal item types added since the latest API release.

        Returns:
        the type name for this item
        Since:
        100.0.0

      • isCommentsEnabled

        public boolean isCommentsEnabled()
        Indicates if comments are allowed on this item.
        Returns:
        true if comments are allowed on this item
        Since:
        100.3.0

      • setAccessAndUseConstraintsHtml

        @Deprecated
public void setAccessAndUseConstraintsHtml​(String accessAndUseConstraintsHtml)
        Deprecated.
        As of 100.4.0, replaced by Item.setTermsOfUse(String).
        Sets a description of any access and use constraints for this item. This may include HTML markup.
        Parameters:
        accessAndUseConstraintsHtml - the access and use constraints
        Since:
        100.0.0

      • setThumbnailData

        public void setThumbnailData​(byte[] thumbnailData)
        Sets the thumbnail data for this portal item.
        Specified by:
        setThumbnailData in class Item
        Parameters:
        thumbnailData - a byte array representing the thumbnail. The recommended image size is 200 pixels wide by 133 pixels high. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB.
        Since:
        100.0.0

      • fetchDataAsync

        public ListenableFuture<InputStream> fetchDataAsync()
        Executes an asynchronous operation to fetch the portal item data. The result is an InputStream object. You are responsible for closing the InputStream after using it.

        Note that reading the InputStream causes network activity and must not be done on the Android UI thread.

        Specified by:
        fetchDataAsync in class Item
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        Since:
        100.0.0

      • fetchThumbnailAsync

        public ListenableFuture<byte[]> fetchThumbnailAsync()
        Executes an asynchronous operation to fetch the thumbnail for this portal item. The result is a byte[] containing the thumbnail data, or null if there is no thumbnail for this portal item.
        Specified by:
        fetchThumbnailAsync in class Item
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        Since:
        100.0.0

      • fetchCommentsAsync

        public ListenableFuture<List<PortalItemComment>> fetchCommentsAsync()
        Executes an asynchronous operation to fetch the comments for this portal item. The result is an unmodifiable list of PortalItemComments for this portal item.
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        Since:
        100.0.0

      • fetchGroupsAsync

        public ListenableFuture<PortalItemGroups> fetchGroupsAsync()
        Executes an asynchronous operation to fetch the groups this portal item belongs to. Includes only the groups that the calling user can access. The result is a PortalItemGroups containing PortalGroup objects that are fully populated and have a load status of LoadStatus.LOADED.
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        Since:
        100.0.0

      • updateItemPropertiesAsync

        public ListenableFuture<Void> updateItemPropertiesAsync()
        Executes an asynchronous operation to update any portal item properties that have been changed (using the setter methods). This causes the values that have been changed to be updated on the portal.
        Specified by:
        updateItemPropertiesAsync in class Item
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        Since:
        100.0.0

      • updateDataAsync

        public ListenableFuture<Void> updateDataAsync​(String jsonContent)
        Executes an asynchronous operation to update the portal item content data. Also updates the portal item properties stored on the portal to match those stored within this PortalItem object.
        Parameters:
        jsonContent - content data, in JSON format, to replace the item's existing content data
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        Since:
        100.0.0

      • shareWithAsync

        public ListenableFuture<Void> shareWithAsync​(boolean everyone,
                                             boolean organization)
        Executes an asynchronous operation to modify the sharing of this portal item. The access property of the item is changed depending on the parameters passed and also whether the item has been shared with groups, as follows:
        • if 'everyone' is true, the item is shared with everyone and the access property is PortalItem.Access.PUBLIC
        • if 'everyone' is false and 'organization' is true, the item is shared with all users in the organization and the access property is PortalItem.Access.ORGANIZATION
        • If 'everyone' and 'organization' are both false and the item has not been shared with any groups, the item is not shared with anyone and the access property is PortalItem.Access.PRIVATE
        • If 'everyone' and 'organization' are both false and the item has been shared with some groups, the access property is PortalItem.Access.SHARED

        The groups an item has been shared with are not affected by this method.

        Parameters:
        everyone - true to share this item with everyone
        organization - true to share this item with all users in the organization
        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 one of the following exceptions:
        Throws:
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        Since:
        100.0.0
        See Also:
        shareWithGroupsAsync(Iterable)

      • shareWithGroupsAsync

        public ListenableFuture<List<PortalGroup>> shareWithGroupsAsync​(Iterable<PortalGroup> groups)
        Executes an asynchronous operation to share this portal item with a number of groups. These groups are added to the existing set of groups the item is shared with. Use fetchGroupsAsync() to find out which groups the item is shared with. Use unshareGroupsAsync(Iterable) to stop sharing with particular groups.

        Note that sharing with groups has an effect even when the item is shared more widely (PortalItem.Access.PUBLIC or PortalItem.Access.ORGANIZATION). Sharing the item also with a group causes the item to be found when searching for items within that group.

        It's not necessary to load the PortalGroup objects that are passed to this method.

        The result of the operation is an unmodifiable list of PortalGroups, one for each group with which the item could not be shared, empty if all groups were shared with successfully.

        Parameters:
        groups - the groups to be shared with; must not be null or empty
        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 groups is null or empty
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        Since:
        100.0.0
        See Also:
        shareWithAsync(boolean, boolean)

      • unshareGroupsAsync

        public ListenableFuture<List<PortalGroup>> unshareGroupsAsync​(Iterable<PortalGroup> groups)
        Executes an asynchronous operation to stop sharing this portal item with a number of groups. These groups are removed from the set of groups the item is shared with. Use fetchGroupsAsync() to find out which groups the item is shared with.

        It's not necessary to load the PortalGroup objects that are passed to this method.

        The result of the operation is an unmodifiable list of PortalGroups, one for each group for which the item could not be unshared, empty if all groups were unshared with successfully.

        Parameters:
        groups - the groups to stop sharing with; must not be null or empty
        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 groups is null or empty
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        Since:
        100.0.0
        See Also:
        shareWithAsync(boolean, boolean)

      • unshareAsync

        public ListenableFuture<Void> unshareAsync()
        Executes an asynchronous operation to stop all sharing of this portal item. This sets the access property of the item to PortalItem.Access.PRIVATE and makes the item accessible to only the item owner. Removes all groups from the set of groups the item is shared with.
        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:
        IllegalStateException - if this PortalItem does not have a portal item ID
        ArcGISRuntimeException - if the current LicenseLevel is too low for this operation (LicenseLevel.BASIC or higher is required to edit portal content)
        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