Module com.esri.arcgisruntime
Package com.esri.arcgisruntime.portal

Class PortalItem

java.lang.Object
com.esri.arcgisruntime.mapping.Item
com.esri.arcgisruntime.portal.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. Portal items can be kept private to the users that created them, shared with other users in specific groups, or made public and accessible to everyone.

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's details page has the following URL format: https://www.arcgis.com/home/item.html?id=[item_id]. If your portal item is a web map, you can also obtain a URL with the format: https://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id] from the ArcGIS Online Map Viewer. In both cases the [item_id] can be used as the ID to instantiate a portal item.

Alternatively, you can obtain a portal item directly from a portal using a method such as Portal.findItemsAsync(PortalQueryParameters).

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.

ArcGIS portals support various types of portal items, including:

  • Web maps and scenes.
  • Services such as feature, map, scene, image, and OGC services that can be added as layers to a map.
  • Data files that can be uploaded, stored, and downloaded, such as .mmpk or .vtpk files.
  • Applications and tools.
Since:
100.0.0
See Also:

  • Property Details

  • Constructor Details

    • 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 ArcGIS Online map viewer and scene viewer web applications in your portal. The item details page has the following format https://www.arcgis.com/home/item.html?id=[item_id]. The map viewer has the format https://www.arcgis.com/home/webmap/viewer.html?webmap=[item_id] or https://www.arcgis.com/apps/mapviewer/index.html?webmap=[item_id] depending on whether you use the classic map viewer or the new map viewer. The scene viewer has the following format https://www.arcgis.com/home/webscene/viewer.html?webscene=[item_id]. In all cases, you can use the [item_id] 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 Details

    • 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
      Gets unknown data from the source JSON.

      Unknown JSON is a Map of values not defined in the ArcGIS specification used to create this object but found in the source JSON. If the object is written back to JSON, any unknown JSON data is not persisted. The ArcGIS specification may be for a web map, web scene, REST API, and so on.

      Specified by:
      getUnknownJson in interface JsonSerializable
      Returns:
      an unmodifiable Map containing unknown data from the source JSON

    • getUnsupportedJson

      public Map<String,Object> getUnsupportedJson()
      Description copied from interface: JsonSerializable
      Gets unsupported data from the source JSON.

      Unsupported JSON is a Map of values defined in the ArcGIS specification used to create this object but not currently used in this API. If the object is written back to JSON, any unsupported JSON data is persisted. The ArcGIS specification may be from a web map, web scene, REST API, and so on.

      Specified by:
      getUnsupportedJson in interface JsonSerializable
      Returns:
      an unmodifiable Map containing unsupported data from the source 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 portal item.
      Returns:
      the average rating of this item
      Since:
      100.0.0

    • getCommentCount

      public int getCommentCount()
      Gets the number of comments on this portal 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. The property is only returned to users who are the item's owner or the org admin.

      A null folderID means either an error or that the folderID is unknown to the user.

      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

    • getPortal

      public Portal getPortal()
      Gets the ArcGIS portal that contains this portal item.
      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

    • getThumbnailData

      public byte[] getThumbnailData()
      Gets the thumbnail data for this portal item, if this has been set using setThumbnailData(byte[]). Note, to retrieve the thumbnail data that's stored on the portal, use fetchThumbnailAsync() instead of this method.
      Specified by:
      getThumbnailData in class Item
      Returns:
      the thumbnail data, or null if this has not been set using setThumbnailData(byte[])
      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 GIS content type of this portal item.

      A portal item's type cannot be changed once it has an item ID. If you wish to change the type you must create a new PortalItem.

      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

    • 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.
      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 the portal item that you have access to. The result is an unmodifiable list of PortalItemComments for this portal item. This method is only available to authenticated users.
      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 JSON data for this portal item on the portal asynchronously. This call is available to the item owner and the administrator of the organization.
      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

      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:

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

      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. It is not necessary to load the PortalGroup objects that are passed to this method.

      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:

    • 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

    • fetchRelatedItemsAsync

      public ListenableFuture<List<PortalItem>> fetchRelatedItemsAsync(Iterable<PortalItemRelationship> relationships, PortalItemRelationshipDirection direction)
      Executes an asynchronous operation to fetch all related portal items with any of the specified relationships to this portal item.
      Parameters:
      relationships - a collection of relationships
      direction - the direction of the relationships
      Returns:
      a ListenableFuture that returns a collection of portal items that match the specified relationships
      Throws:
      IllegalArgumentException - if relationships is empty or null
      IllegalArgumentException - if direction is null
      IllegalStateException - if this PortalItem does not have a portal item ID
      Since:
      100.11.0

    • fetchRelatedItemsAsync

      public ListenableFuture<List<PortalItem>> fetchRelatedItemsAsync(PortalItemRelationship relationship, PortalItemRelationshipDirection direction)
      Executes an asynchronous operation to fetch all related portal items with the specified relationship to this portal item.
      Parameters:
      relationship - the relationship
      direction - the direction of the relationship
      Returns:
      a ListenableFuture that returns a collection of portal items that match the specified relationship
      Throws:
      IllegalArgumentException - if relationship is null
      IllegalArgumentException - if direction is null
      IllegalStateException - if this PortalItem does not have a portal item ID
      Since:
      100.11.0

    • getLoadStatus

      public LoadStatus getLoadStatus()
      Gets the value of the loadStatus property.
      Specified by:
      getLoadStatus in interface Loadable
      Property description:
      Returns:
      the value of the loadStatus property
      See Also:

    • getLoadError

      public ArcGISRuntimeException getLoadError()
      Gets the value of the loadError property.
      Specified by:
      getLoadError in interface Loadable
      Property description:
      Returns:
      the value of the loadError property
      See Also:

    • 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, add a listener to the Loadable.loadStatusProperty() 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

    • loadStatusProperty

      public ReadOnlyObjectProperty<LoadStatus> loadStatusProperty()
      Description copied from interface: Loadable
      The load status.
      Specified by:
      loadStatusProperty in interface Loadable
      Returns:
      the loadStatus property
      See Also:

    • loadErrorProperty

      public ReadOnlyObjectProperty<ArcGISRuntimeException> loadErrorProperty()
      Description copied from interface: Loadable
      The load error.
      Specified by:
      loadErrorProperty in interface Loadable
      Returns:
      the loadError property
      See Also: