com.esri.android.map.ags
Class ArcGISFeatureLayer

java.lang.Object
  com.esri.android.map.Layer
      com.esri.android.map.GraphicsLayer
          com.esri.android.map.ags.ArcGISFeatureLayer

public class ArcGISFeatureLayer
extends GraphicsLayer

ArcGISFeatureLayer is a special type of GraphicsLayer that allows you to display features from a layer hosted by an ArcGIS Server map service or feature service. The layer can be either a spatial layer or a non-spatial table. If the layer is editable, you can add, update and delete features. The following are examples of how you might work with the ArcGISFeatureLayer class.

Java usage:

 //ArcGISFeatureLayer class is used to define the Layer that is added to the 
 //MapView object.
 MapView mv = new MapView(this);
 mv.addLayer(new ArcGISFeatureLayer(url,MODE.SNAPSHOT));
 setContentView(mv);
 

Nested Class Summary

static class	ArcGISFeatureLayer.MODE The feature layer can work under 3 modes.
static class	ArcGISFeatureLayer.Options The options to instantiate the feature layer.
static class	ArcGISFeatureLayer.SELECTION_METHOD The modes used for the select features method.

Constructor Summary

ArcGISFeatureLayer(String url, ArcGISFeatureLayer.MODE mode)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code (see the class description for an example of this usage).

ArcGISFeatureLayer(String url, ArcGISFeatureLayer.MODE mode, UserCredentials credentials)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

ArcGISFeatureLayer(String url, ArcGISFeatureLayer.Options layerOption)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

ArcGISFeatureLayer(String url, ArcGISFeatureLayer.Options layerOption, UserCredentials credentials)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

ArcGISFeatureLayer(String layerDefinition, FeatureSet featureCollection, ArcGISFeatureLayer.Options layerOption)
The constructor is used if you are instantiating the ArcGISFeatureLayer using a feature collection.

ArcGISFeatureLayer(String url, String layerDefinition, ArcGISFeatureLayer.MODE mode)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

ArcGISFeatureLayer(String url, String layerDefinition, ArcGISFeatureLayer.MODE mode, boolean initLayer)
The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code (see the class description for an example of this usage).

ArcGISFeatureLayer(String layerDef, String layerDefinitionOverride, FeatureSet featureCollection, ArcGISFeatureLayer.Options layerOption, boolean initLayer)
This constructor is to be used with a mapnotes layer defined in webmap only.

Method Summary

void	addAttachment(int objectId, File file, CallbackListener<FeatureEditResult> callback) Adds an attachment to the feature specified by the ObjectId.
void	addAttachment(int objectId, File file, String mime, CallbackListener<FeatureEditResult> callback) Adds an attachment to the feature specified by the ObjectId.
void	applyEdits(Graphic[] adds, Graphic[] deletes, Graphic[] updates, CallbackListener<FeatureEditResult[][]> callback) Applies edits to the editable feature layer.
void	clear() Clears all selection and removes all graphics from the layer.
void	clearSelection() Clears the current selection.
Graphic	createFeatureWithTemplate(FeatureTemplate template, Geometry geometry) Creates a new feature based on the specified feature SubType and feature template.
Graphic	createFeatureWithType(FeatureType type, Geometry geometry) Creates a new feature based on the specified feature SubType.
void	deleteAttachments(int objectId, int[] attachmentids, CallbackListener<FeatureEditResult[]> callback) Deletes one or more attachments for the feature specified by the input ObjectId.
int	getBufferFactor() Returns the factor used to calculate buffered extent.
String	getCapabilities() Gets the capabilities list of the associated feature service.
String	getDefaultDefinitionExpression() Returns the Metadata describing the default definition expression for the layer as defined by the service.
String	getDefinitionExpression() Returns the current definition expression.
String	getDisplayField() Returns the name of the field that contains the Display Field for the layer.
int	getExpirationInterval() Returns the time interval in seconds that features in the layer will expire when the layer is in ONDEMAND mode.
Field	getField(String fieldName) This method returns the field object when the fieldname is passed in.
Field[]	getFields() The array of fields in the layer.
Geometry.Type	getGeometryType() Gets the type of the geometry holding by the feature layer.
String	getGlobalIdField() Returns the name of the field that contains the GlobalId field for the layer.
ArcGISFeatureLayer.MODE	getMode() Returns the layer mode.
String	getObjectIdField() Returns the name of the field that contains the ObjectID field for the layer.
String[]	getOutFields() The array of field names included in the feature layer based on the ArcGISFeatureLayer.Options.outFields parameter.
PopupInfo	getPopupInfo() Gets the PopupInfo associated with this feature layer.
PopupInfo	getPopupInfo(int sublayerId) Gets the PopupInfo associated with the sub-layer id.
Graphic[]	getSelectedFeatures() Returns the selected features.
Symbol	getSelectionSymbol() Returns the selection symbol for the feature layer.
FeatureTemplate[]	getTemplates() Returns an array of feature templates defined in the feature service layer.
FeatureType	getType(String type)
String	getTypeIdField() Returns the name of the field that contains the SubType field for the layer.
FeatureType[]	getTypes() Returns an array of feature types defined in the feature service layer.
boolean	hasAttachments() True if attachments are enabled on the feature layer.
boolean	isAutoRefreshOnExpiration() True if the layer will refresh automatically when the expiration interval is reached.
boolean	isEditable() Returns true if the feature layer is editable.
boolean	isTable() Returns true if the type of layer is "Table".
void	queryAttachmentInfos(int objectId, CallbackListener<AttachmentInfo[]> callback) Queries for information about attachments associated with the specified ObjectIds.
void	queryFeatures(Query query, CallbackListener<FeatureSet> callback) Query features from the feature layer.
void	queryIds(Query query, CallbackListener<int[]> callback) Query for ObjectIds.
void	recycle() Releases resources referenced by the Layer so that they can be recycled.
void	refresh() Based on the mode of the feature layer, the method call can update the graphics from the associate service or refresh the layer from local cache.
InputStream	retrieveAttachment(int objectId, int attachmentId) Fetches the contents of the specified attachment.
void	selectFeatures(Query query, ArcGISFeatureLayer.SELECTION_METHOD selectionMethod, CallbackListener<FeatureSet> callback) Selects features from the feature layer.
void	setAutoRefreshOnExpiration(boolean autoRefreshOnExpiration) Specifies whether or not the layer will refresh automatically when the expiration interval is reached.
void	setBufferFactor(int bufferFactor) Sets the factor used to calculate buffered extent.
void	setDefinitionExpression(String expression) Sets the definition expression of the feature layer.
void	setExpirationInterval(int expirationInterval) The time interval in seconds that features in the layer will expire when the layer is in ONDEMAND mode.
void	setPopupInfos(Map<Integer,PopupInfo> popUpInfos)
void	setSelectionSymbol(Symbol selectionSymbol) Sets the selection symbol for the feature layer.

Methods inherited from class com.esri.android.map.GraphicsLayer

addGraphic, addGraphics, createSymbolImage, createSymbolImages, getGraphic, getGraphicIDs, getGraphicIDs, getGraphicIDs, getMaxScale, getMinScale, getNumberOfGraphics, getRenderer, moveAllGraphics, removeAll, removeGraphic, setGraphicVisible, setMaxScale, setMinScale, setRenderer, updateGraphic, updateGraphic, updateGraphic, updateGraphic, updateGraphic

Methods inherited from class com.esri.android.map.Layer

getCredentials, getDefaultSpatialReference, getExtent, getFullExtent, getHeight, getID, getName, getOpacity, getResolution, getSpatialReference, getTitle, getUrl, getUrlHashCode, getWidth, isInitialized, isRecycled, isVisible, isWebMapBaselayer, reinitializeLayer, setName, setOnStatusChangedListener, setOpacity, setVisible

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          ArcGISFeatureLayer.Options layerOption)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

Parameters:

url - the the URL of the feature layer service.

layerOption - the option parameters. Sets to null to use the default options.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          ArcGISFeatureLayer.Options layerOption,
                          UserCredentials credentials)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

Parameters:

url - the the URL of the feature layer service.

layerOption - the option parameters. Sets to null to use the default options.

credentials - the user credentials for accessing a secure feature layer.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          ArcGISFeatureLayer.MODE mode)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code (see the class description for an example of this usage).

Parameters:

url - the the URL of the feature layer service.

mode - the feature layer mode.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          String layerDefinition,
                          ArcGISFeatureLayer.MODE mode)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

Parameters:

url - the the URL of the feature layer service.

layerDefinition - The definition of the layer represented in a JSON String. The structure is the same as the information returned by REST for a layer in a feature or map service.

mode - the feature layer mode.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          String layerDefinition,
                          ArcGISFeatureLayer.MODE mode,
                          boolean initLayer)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code (see the class description for an example of this usage).

Parameters:

url - the the URL of the feature layer service.

layerDefinition - The definition of the layer represented in a JSON String. The structure is the same as the information returned by REST for a layer in a feature or map service.

mode - the feature layer mode.

initLayer - set to true to initialize the the layer, or the layer will not initialized.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String url,
                          ArcGISFeatureLayer.MODE mode,
                          UserCredentials credentials)

The constructor is used if you are instantiating the ArcGISFeatureLayer using Java code.

Parameters:

url - the the URL of the feature layer service.

mode - the feature layer mode.

credentials - the user credentials for accessing a secure feature layer.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String layerDefinition,
                          FeatureSet featureCollection,
                          ArcGISFeatureLayer.Options layerOption)

The constructor is used if you are instantiating the ArcGISFeatureLayer using a feature collection.

The feature layer, when initialized with a feature collection object has the following behavior:

Edits are applied on the client not posted to the server.

The feature layer generates a unique ObjectId for new features.

All queries are done on the client side.

Does not support operations that need to be performed on the server, e.g. attachment, appyEdit.

You need to explicitly call clear() to release all cached feature collection when not needed.

Parameters:

layerOption - the option parameters. Sets to null to use the default options.

layerDefinition - The definition of the layer represented in a JSON String. The structure is the same as the information returned by REST for a layer in a feature or map service.

featureCollection - A collection of features. The spatial reference of the features must be same as the map's.

ArcGISFeatureLayer

public ArcGISFeatureLayer(String layerDef,
                          String layerDefinitionOverride,
                          FeatureSet featureCollection,
                          ArcGISFeatureLayer.Options layerOption,
                          boolean initLayer)

This constructor is to be used with a mapnotes layer defined in webmap only.

Parameters:

layerDef - the definition of the map notes layer represented in a JSON String. The structure is the same as the information returned by REST for a layer in a feature or map service.

layerDefinitionOverride - the definition of the feature layer represented in a JSON String. The structure is the same as the information returned by REST for a layer in a feature or map service.

featureCollection - the mapnotes layer

layerOption - option parameters.

initLayer - set to true to initialize the the layer, or the layer will not initialized.

Method Detail

getDefinitionExpression

public String getDefinitionExpression()

Returns the current definition expression.

Returns:

the definition.

See Also:

setDefinitionExpression(String)

setDefinitionExpression

public void setDefinitionExpression(String expression)

Sets the definition expression of the feature layer. Only the features that match the definition expression are displayed. A definition expression limits the features available for display and queries by applying constraints to the layer's attribute fields. Setting a definition expression is useful when the dataset is large and you don't want to bring everything to the client for analysis. This method is typically called before adding the layer to the map. If the method is called after the layer is added to the map the layer will refresh itself to reflect the new definition expression.

Parameters:

expression - the definition expression.

getDefaultDefinitionExpression

public String getDefaultDefinitionExpression()

Returns the Metadata describing the default definition expression for the layer as defined by the service. The default definition expression limits the features available for display and query. You cannot override this value but you define additional filters on the default expression using the setDefinitionExpression(String) method. For example, if the default definition expression is set to display data where "STATE_NAME = 'California'" you could use setDefinitionExpression to only display a subset of the features in California e.g., "COUNTY='San Diego'".

getSelectionSymbol

public Symbol getSelectionSymbol()

Returns the selection symbol for the feature layer. If no symbol is specified, features are drawn using the layers's renderer.

Returns:

the symbol for highlight feature.

setSelectionSymbol

public void setSelectionSymbol(Symbol selectionSymbol)

Sets the selection symbol for the feature layer. If no symbol is specified, features are drawn using the layers's renderer.

Parameters:

selectionSymbol -

getBufferFactor

public int getBufferFactor()

Returns the factor used to calculate buffered extent. When in ONDEMAND mode, you have a choice to fetch the features within current extent or buffered extent. The buffer is calculated as: width = extent.width * bufferFactor * 2 + 1); height = extent.height * (bufferFactor * 2 + 1);

By default it is 1 (100%).

setBufferFactor

public void setBufferFactor(int bufferFactor)

Sets the factor used to calculate buffered extent. When in ONDEMAND mode, you have a choice to fetch the features within current extent or buffered extent. The buffered extent is calculated as: width = extent.width * bufferFactor * 2 + 1); height = extent.height * (bufferFactor * 2 + 1);

By default it is 1 (100%).

getMode

public ArcGISFeatureLayer.MODE getMode()

Returns the layer mode.

getFields

public Field[] getFields()

The array of fields in the layer.

Returns:

the field array.

getField

public Field getField(String fieldName)

This method returns the field object when the fieldname is passed in.

Parameters:

fieldName - name of the Field

Returns:

the Field object

isAutoRefreshOnExpiration

public boolean isAutoRefreshOnExpiration()

True if the layer will refresh automatically when the expiration interval is reached.

setAutoRefreshOnExpiration

public void setAutoRefreshOnExpiration(boolean autoRefreshOnExpiration)

Specifies whether or not the layer will refresh automatically when the expiration interval is reached. Default is false. This is used only in ONDEMAND mode.

getExpirationInterval

public int getExpirationInterval()

Returns the time interval in seconds that features in the layer will expire when the layer is in ONDEMAND mode. Setting this to 0 will cause the features to not expire.

Returns:

interval in seconds

setExpirationInterval

public void setExpirationInterval(int expirationInterval)

The time interval in seconds that features in the layer will expire when the layer is in ONDEMAND mode. Setting this to 0 will cause the features to not expire.

Parameters:

expirationInterval - interval in seconds

refresh

public void refresh()

Based on the mode of the feature layer, the method call can update the graphics from the associate service or refresh the layer from local cache.

selectFeatures

public void selectFeatures(Query query,
                           ArcGISFeatureLayer.SELECTION_METHOD selectionMethod,
                           CallbackListener<FeatureSet> callback)

Selects features from the feature layer. The selection method defines how query results are passed to the selection. The feature layer will highlight the current selection if a selection symbol has been defined. Whenever possible, the feature layer will perform the query operation on the client side.

Parameters:

query - The input query.

selectionMethod - the selection mode.

callback - The function to call when the method is completed or on error.

getSelectedFeatures

public Graphic[] getSelectedFeatures()

Returns the selected features.

Returns:

the selected features.

clearSelection

public void clearSelection()

Clears the current selection.

addAttachment

public void addAttachment(int objectId,
                          File file,
                          CallbackListener<FeatureEditResult> callback)

Adds an attachment to the feature specified by the ObjectId. Only applicable if isEditable() and hasAttachments() are true.

Parameters:

objectId - The ObjectId of the feature to which the attachment is added.

file - The path of the attachment on the device.

callback - The path of the attachment on the device.

addAttachment

public void addAttachment(int objectId,
                          File file,
                          String mime,
                          CallbackListener<FeatureEditResult> callback)

Adds an attachment to the feature specified by the ObjectId. Only applicable if isEditable() and hasAttachments() are true.

Parameters:

objectId - The ObjectId of the feature to which the attachment is added.

file - The path of the attachment on the device.

mime - the content-type to send the file. e.g. text/plain. When mime is omitted the content-type is determined by the file extension of the attachment. By default the content-type is "application/octet-stream".

callback - The path of the attachment on the device.

deleteAttachments

public void deleteAttachments(int objectId,
                              int[] attachmentids,
                              CallbackListener<FeatureEditResult[]> callback)

Deletes one or more attachments for the feature specified by the input ObjectId. Only applicable if isEditable() and hasAttachments() are true.

Parameters:

objectId - The ObjectId of the feature from which the attachment is removed.

attachmentids - The ObjectId of the feature from which the attachment is removed.

callback - This listener will be called when the operation is complete or on error.

queryAttachmentInfos

public void queryAttachmentInfos(int objectId,
                                 CallbackListener<AttachmentInfo[]> callback)

Queries for information about attachments associated with the specified ObjectIds.

Parameters:

objectId - The ObjectId of the feature upon which the attachment information is queried.

callback - This listener will be called when the operation is complete or on error.

applyEdits

public void applyEdits(Graphic[] adds,
                       Graphic[] deletes,
                       Graphic[] updates,
                       CallbackListener<FeatureEditResult[][]> callback)

Applies edits to the editable feature layer. Only applicable for layers in a feature service.

For new features, the applyEdit will submit all the features to server side. If succeed, all of the new features will be updated with the OID and GID and will be added to the layer graphics.

For updating and deleting, the graphics will be adjusted based on the response.

Parameters:

adds - Apply edits to the feature layer. Only applicable for layers in a feature service.

deletes - Array of features to be deleted. Features must have valid ObjectIds.

updates - Array of features whose geometry and/or attributes have changed. Features must have valid ObjectIds. The geometry of features is typically modified using the Editing tools. Attributes are modified using the Attribute Inspector.

callback - This listener will be called when the operation is complete or on error.

isEditable

public boolean isEditable()

Returns true if the feature layer is editable. If the layer is editable the following operations can be performed.

Add new features.

Modify the geometry and attributes of existing features.

Delete features. You need to wait until the layer initialization is done before calling this method.

Returns:

true if it is editable or false otherwise.

queryFeatures

public void queryFeatures(Query query,
                          CallbackListener<FeatureSet> callback)

Query features from the feature layer. Layer definition and time definition are honored. Whenever possible the feature layer will perform the query on the client.

Parameters:

query - The input query. The query object has the following restrictions to avoid conflicts between layer and map properties.

outFields specified by the query object are overridden by the outFields specified in the feature layer constructor.

The returnGeometry value specified by the query object is ignored and true is used.

The outSpatialReference set by the query object is ignored and the map's spatial reference is used.

callback - The function to call when the method has completed.

queryIds

public void queryIds(Query query,
                     CallbackListener<int[]> callback)

Query for ObjectIds. There is no limit on the number of ObjectIds that are returned from the server. Like queryFeatures this operation will perform queries on the client (browser) whenever possible.

Parameters:

query - The input query. The query object has the following restrictions to avoid conflicts between layer and map properties.

outFields specified by the query object are overridden by the outFields specified in the feature layer constructor.

The returnGeometry value specified by the query object is ignored and true is used.

The outSpatialReference set by the query object is ignored and the map's spatial reference is used.

callback - The function to call when the method has completed.

createFeatureWithTemplate

public Graphic createFeatureWithTemplate(FeatureTemplate template,
                                         Geometry geometry)

Creates a new feature based on the specified feature SubType and feature template. Note, the new feature is only available on the device at this point, it is not committed to the server.

Parameters:

template - the feature template to use while creating the feature.

geometry - the geometry to create the Graphic.

Returns:

the Graphic with the given geometry and the template.

createFeatureWithType

public Graphic createFeatureWithType(FeatureType type,
                                     Geometry geometry)

Creates a new feature based on the specified feature SubType. Note, the new feature is only available on the device at this point, it is not committed to the server. This method uses the first template in the feature type.

Parameters:

type - the type of feature to create.

geometry - the geometry to create the Graphic.

Returns:

the Graphic with the given geometry and the template (defined in the type).

isTable

public boolean isTable()

Returns true if the type of layer is "Table". The type of a feature layer can be "Graphic Layer" or "Table".

getTypes

public FeatureType[] getTypes()

Returns an array of feature types defined in the feature service layer. Only applicable for ArcGIS Server feature service layers.

Returns:

the array of FeatureType.

getType

public FeatureType getType(String type)

getTemplates

public FeatureTemplate[] getTemplates()

Returns an array of feature templates defined in the feature service layer. Only applicable for ArcGIS Server feature service layers.

Returns:

the array of FeatureTemplate.

getOutFields

public String[] getOutFields()

The array of field names included in the feature layer based on the ArcGISFeatureLayer.Options.outFields parameter. If none are specified, in the ArcGISFeatureLayer.Options class then the feature layer will return all fields and this methods will return null. If "*" was specified in the ArcGISFeatureLayer.Options class this method will return ["*"]. If some field names are set in the ArcGISFeatureLayer.Options class, but the ObjectId field was not included it will be included in the feature layer and will also be returned in this String array.

Returns:

the name of the fields

See Also:

ArcGISFeatureLayer.Options

getObjectIdField

public String getObjectIdField()

Returns the name of the field that contains the ObjectID field for the layer.

Returns:

the name of the field.

getTypeIdField

public String getTypeIdField()

Returns the name of the field that contains the SubType field for the layer.

Returns:

the name of the field.

getDisplayField

public String getDisplayField()

Returns the name of the field that contains the Display Field for the layer.

Returns:

the name of the field.

getGlobalIdField

public String getGlobalIdField()

Returns the name of the field that contains the GlobalId field for the layer.

Returns:

the name of the field.

hasAttachments

public boolean hasAttachments()

True if attachments are enabled on the feature layer. Use the queryAttachmentInfos(int, CallbackListener) method to determine if the feature has attachments. If the layer is editable (isEditable()) and supports attachments the following operations can be performed.

Add attachments to features.

Delete existing attachments.

retrieveAttachment

public InputStream retrieveAttachment(int objectId,
                                      int attachmentId)
                               throws Exception

Fetches the contents of the specified attachment. Please make sure call the InputStream.close() after you get the data.

Parameters:

objectId - the ObjectId of the feature to which the attachment belongs.

attachmentId - the ID of the attachment to fetch.

Throws:

Exception

clear

public void clear()

Clears all selection and removes all graphics from the layer.

getGeometryType

public Geometry.Type getGeometryType()

Gets the type of the geometry holding by the feature layer. You should not call this method until the layer is initialized.

Returns:

the geometry type or null if not initialized.

getCapabilities

public String getCapabilities()

Gets the capabilities list of the associated feature service. It is a comma separated list of supported capabilities - e.g. "Query, Editing". Only available if the feature service is published using ArcGIS Server version 10 or greater. You cannot call this method until the layer is loaded.

When the Feature layer is instantiated without an associated feature service (e.g. FeatureCollection Mode), the method will always return null.

Returns:

the comma separated capabilities or null if the associated server doesn't support it.

getPopupInfo

public PopupInfo getPopupInfo()

Gets the PopupInfo associated with this feature layer.

Returns:

PopupInfo

getPopupInfo

public PopupInfo getPopupInfo(int sublayerId)

Gets the PopupInfo associated with the sub-layer id.

Overrides:

getPopupInfo in class Layer

Parameters:

sublayerId - you should only set 0 for the feature layer.

Returns:

PopupInfo

setPopupInfos

public void setPopupInfos(Map<Integer,PopupInfo> popUpInfos)

Overrides:

setPopupInfos in class Layer

recycle

public void recycle()

Description copied from class: Layer

Releases resources referenced by the Layer so that they can be recycled.

Overrides:

recycle in class Layer