程序包 ohos.aafwk.ability

类 DataAbilityHelper

java.lang.Object

ohos.aafwk.ability.DataAbilityHelper

public class DataAbilityHelper
extends Object

Helps applications to access data.

DataAbilityHelper is a helper class for data operations. It uses IDataAbilityObserver to register an observer for monitoring data. You can call creator(ohos.app.Context) to create a DataAbilityHelper instance without specifying the Uri or call creator(ohos.app.Context,ohos.utils.net.Uri,boolean) to create one with a given Uri.

从以下版本开始:

1

另请参阅:

IDataAbilityObserver, Context, Uri

SystemCapability

SystemCapability.Aafwk#ABILITY

方法概要

限定符和类型	方法	说明
int	batchInsert(Uri uri, ValuesBucket[] values)	Inserts multiple data records into the database.
PacMap	call(Uri uri, String method, String arg, PacMap extras)	Calls the method of the Data ability.
static DataAbilityHelper	create(Context context)	Creates a DataAbilityHelper instance in the given Context without specifying a Uri.
static DataAbilityHelper	create(Context context, Uri uri)	Creates a DataAbilityHelper instance in the given Context with a Uri.
static DataAbilityHelper	create(Context context, Uri uri, boolean tryBind)	Creates a DataAbilityHelper instance in the given Context.
static DataAbilityHelper	create(Context context, Uri uri, boolean tryBind, int flag)	Creates a DataAbilityHelper instance.
static DataAbilityHelper	creator(Context context)	已过时。 This change is effective since API version 7. Use create(Context context) instead.
static DataAbilityHelper	creator(Context context, Uri uri)	已过时。 This change is effective since API version 7. Use create(Context context, Uri uri) instead.
static DataAbilityHelper	creator(Context context, Uri uri, boolean tryBind)	已过时。 This change is effective since API version 7. Use create(Context context, Uri uri, boolean tryBind) instead.
int	delete(Uri uri, DataAbilityPredicates predicates)	Deletes one or more data records from the database.
Uri	denormalizeUri(Uri uri)	Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one.
DataAbilityResult[]	executeBatch(Uri uri, ArrayList<DataAbilityOperation> operations)	Performs batch operations on the database.
String[]	getFileTypes(Uri uri, String mimeTypeFilter)	Obtains the MIME types of files supported.
String	getType(Uri uri)	Obtains the MIME type of the date specified by the given URI.
int	insert(Uri uri, ValuesBucket value)	Inserts a single data record into the database.
Uri	normalizeUri(Uri uri)	Converts the given uri that refers to the Data ability into a normalized Uri.
void	notifyChange(Uri uri)	Notifies the registered observers of a change to the data resource specified by Uri.
InputStream	obtainInputStream(Uri uri)	Obtains the input stream of a file.
OutputStream	obtainOutputStream(Uri uri)	Obtains the output stream of a file.
FileDescriptor	openFile(Uri uri, String mode)	Opens a file in a specified remote path.
RawFileDescriptor	openRawFile(Uri uri, String mode)	This is like openFile(ohos.utils.net.Uri, java.lang.String), open a file that need to be able to return sub-sections of files，often assets inside of their .hap.
ResultSet	query(Uri uri, String[] columns, DataAbilityPredicates predicates)	Queries data in the database.
void	registerObserver(Uri uri, IDataAbilityObserver dataObserver)	Registers an observer to observe data specified by the given Uri.
boolean	release()	Releases the client resource of the Data ability.
boolean	reload(Uri uri, PacMap extras)	Reloads data in the database.
void	unregisterObserver(Uri uri, IDataAbilityObserver dataObserver)	Deregisters an observer used for monitoring data specified by the given Uri.
int	update(Uri uri, ValuesBucket value, DataAbilityPredicates predicates)	Updates data records in the database.

从类继承的方法 java.lang.Object

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

方法详细资料

creator

@Deprecated
public static DataAbilityHelper creator(Context context)

已过时。 This change is effective since API version 7. Use create(Context context) instead.

Creates a DataAbilityHelper instance in the given Context without specifying a Uri.

参数:

context - Indicates the Context object on the OHOS.

返回:

Returns the created DataAbilityHelper instance without a Uri.

从以下版本开始:

1

create

public static DataAbilityHelper create(Context context)

Creates a DataAbilityHelper instance in the given Context without specifying a Uri.

参数:

context - Indicates the Context object on the OHOS.

返回:

Returns the created DataAbilityHelper instance where Uri is not specified.

从以下版本开始:

7

creator

@Deprecated
public static DataAbilityHelper creator(Context context,
                                        Uri uri)

已过时。 This change is effective since API version 7. Use create(Context context, Uri uri) instead.

Creates a DataAbilityHelper instance in the given Context with a Uri.

参数:

context - Indicates the Context object on the OHOS.

uri - Indicates the database table or disk file to operate.

返回:

Returns the created DataAbilityHelper instance with the specified Uri.

从以下版本开始:

1

create

public static DataAbilityHelper create(Context context,
                                       Uri uri)

Creates a DataAbilityHelper instance in the given Context with a Uri.

参数:

context - Indicates the Context object on the OHOS.

uri - Indicates the database table or disk file to operate.

返回:

Returns the created DataAbilityHelper instance with the specified Uri.

从以下版本开始:

7

creator

@Deprecated
public static DataAbilityHelper creator(Context context,
                                        Uri uri,
                                        boolean tryBind)

已过时。 This change is effective since API version 7. Use create(Context context, Uri uri, boolean tryBind) instead.

Creates a DataAbilityHelper instance in the given Context.

You can use this method to specify the Uri of the data to operate and set the binding relationship between the ability of the Provider process and the associated client process in a DataAbilityHelper instance.

参数:

context - Indicates the Context object on the OHOS.

uri - Indicates the URI of the database table to operate.

tryBind - Indicates the binding relationship between the Provider process and the associated client process in a DataAbilityHelper instance. It determines whether the exit of the corresponding Provider process causes the exit of the client process.

返回:

Returns the created DataAbilityHelper instance.

从以下版本开始:

1

create

public static DataAbilityHelper create(Context context,
                                       Uri uri,
                                       boolean tryBind)

Creates a DataAbilityHelper instance in the given Context.

You can use this method to specify the Uri of the data to operate and set the binding relationship between the ability of the Provider process and the associated client process in a DataAbilityHelper instance.

参数:

context - Indicates the Context object on the OHOS.

uri - Indicates the URI of the database table to operate.

tryBind - Indicates the binding relationship between the Provider process and the associated client process in a DataAbilityHelper instance. It determines whether the exit of the corresponding Provider process causes the exit of the client process.

返回:

Returns the created DataAbilityHelper instance.

从以下版本开始:

7

create

public static DataAbilityHelper create(Context context,
                                       Uri uri,
                                       boolean tryBind,
                                       int flag)

Creates a DataAbilityHelper instance.

You can use this method to specify the Uri of the data to operate, set the binding relationship between the ability of the Provider process and the associated client process in a DataAbilityHelper instance, and specify whether the passed URI is in the OHOS format.

参数:

context - Indicates the Context object on the OHOS.

uri - Indicates the URI of the database table to operate.

tryBind - Indicates the binding relationship between the Provider process and the associated client process in a DataAbilityHelper instance. It determines whether the exit of the corresponding Provider process causes the exit of the client process.

flag - Indicates whether the passed URI is in the OHOS format. If the URI is not in the OHOS format, pass Intent.FLAG_NOT_OHOS_COMPONENT.

返回:

Returns the created DataAbilityHelper instance.

从以下版本开始:

7

release

public boolean release()

Releases the client resource of the Data ability.

You should call this method to releases client resource after the data operations are complete.

返回:

Returns true if the resource is successfully released; returns false otherwise.

从以下版本开始:

1

registerObserver

public void registerObserver(Uri uri,
                             IDataAbilityObserver dataObserver)
                      throws IllegalArgumentException

Registers an observer to observe data specified by the given Uri.

参数:

uri - Indicates the path of the data to operate.

dataObserver - Indicates the IDataAbilityObserver object.

抛出:

IllegalArgumentException - Throws this exception if a parameter value is invalid.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

notifyChange

public void notifyChange(Uri uri)
                  throws IllegalArgumentException

Notifies the registered observers of a change to the data resource specified by Uri.

参数:

uri - Indicates the path of the data to operate.

抛出:

IllegalArgumentException - Throws this exception if a parameter value is invalid.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

unregisterObserver

public void unregisterObserver(Uri uri,
                               IDataAbilityObserver dataObserver)
                        throws IllegalArgumentException

Deregisters an observer used for monitoring data specified by the given Uri.

参数:

uri - Indicates the path of the data to operate.

dataObserver - Indicates the IDataAbilityObserver object.

抛出:

IllegalArgumentException - Throws this exception if a parameter value is invalid.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

insert

public int insert(Uri uri,
                  ValuesBucket value)
           throws DataAbilityRemoteException

Inserts a single data record into the database.

参数:

uri - Indicates the path of the data to operate.

value - Indicates the data record to insert. If this parameter is null, a blank row will be inserted.

返回:

Returns the index of the inserted data record.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

batchInsert

public int batchInsert(Uri uri,
                       ValuesBucket[] values)
                throws DataAbilityRemoteException

Inserts multiple data records into the database.

参数:

uri - Indicates the path of the data to operate.

values - Indicates the data records to insert.

返回:

Returns the number of data records inserted.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

IllegalArgumentException - Throws this exception if a parameter value is invalid.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

delete

public int delete(Uri uri,
                  DataAbilityPredicates predicates)
           throws DataAbilityRemoteException

Deletes one or more data records from the database.

参数:

uri - Indicates the path of the data to operate.

predicates - Indicates filter criteria. You should define the processing logic when this parameter is null.

返回:

Returns the number of data records deleted.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

update

public int update(Uri uri,
                  ValuesBucket value,
                  DataAbilityPredicates predicates)
           throws DataAbilityRemoteException

Updates data records in the database.

参数:

uri - Indicates the path of data to update.

value - Indicates the data to update. This parameter can be null.

predicates - Indicates filter criteria. You should define the processing logic when this parameter is null.

返回:

Returns the number of data records updated.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

query

public ResultSet query(Uri uri,
                       String[] columns,
                       DataAbilityPredicates predicates)
                throws DataAbilityRemoteException

Queries data in the database.

参数:

uri - Indicates the path of data to query.

columns - Indicates the columns to query. If this parameter is null, all columns are queried.

predicates - Indicates filter criteria. You should define the processing logic when this parameter is null.

返回:

Returns the query result.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

executeBatch

public DataAbilityResult[] executeBatch(Uri uri,
                                        ArrayList<DataAbilityOperation> operations)
                                 throws DataAbilityRemoteException,
                                        OperationExecuteException

Performs batch operations on the database.

参数:

uri - Indicates the path of data to operate.

operations - Indicates a list of database operations on the database.

返回:

Returns the result of each operation, in array.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

OperationExecuteException - Throws this exception if an operation exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

IllegalArgumentException - Throws this exception if a parameter value is invalid.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

openFile

public FileDescriptor openFile(Uri uri,
                               String mode)
                        throws DataAbilityRemoteException,
                               FileNotFoundException

Opens a file in a specified remote path.

参数:

uri - Indicates the path of the file to open.

mode - Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, or "rwt" for read and write access that truncates any existing file.

返回:

Returns the file descriptor.

抛出:

FileNotFoundException - Throws this exception if the file is not found.

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri or mode is null.

从以下版本开始:

1

openRawFile

public RawFileDescriptor openRawFile(Uri uri,
                                     String mode)
                              throws DataAbilityRemoteException,
                                     FileNotFoundException

This is like openFile(ohos.utils.net.Uri, java.lang.String), open a file that need to be able to return sub-sections of files，often assets inside of their .hap.

参数:

uri - Indicates the path of the file to open.

mode - Indicates the file open mode, which can be "r" for read-only access, "w" for write-only access (erasing whatever data is currently in the file), "wt" for write access that truncates any existing file, "wa" for write-only access to append to any existing data, "rw" for read and write access on any existing data, or "rwt" for read and write access that truncates any existing file.

返回:

Returns the RawFileDescriptor object containing file descriptor.

抛出:

FileNotFoundException - Throws this exception if the file is not found.

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalStateException - Throws this exception if the dataAbility does not exist.

NullPointerException - Throws this exception if uri or mode is null.

从以下版本开始:

3

getFileTypes

public String[] getFileTypes(Uri uri,
                             String mimeTypeFilter)
                      throws DataAbilityRemoteException

Obtains the MIME types of files supported.

参数:

uri - Indicates the path of the files to obtain.

mimeTypeFilter - Indicates the MIME types of the files to obtain. This parameter cannot be null.

1. "*/*": Obtains all types supported by Data abilities.

2. "image/*": Obtains files whose main type is image of any subtype.

3. "*/jpg": Obtains files whose subtype is JPG of any main type.

返回:

Returns the matched MIME types. If there is no match, null is returned.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

NullPointerException - Throws this exception if uri or mimeTypeFilter is null.

从以下版本开始:

1

call

public PacMap call(Uri uri,
                   String method,
                   String arg,
                   PacMap extras)
            throws DataAbilityRemoteException

Calls the method of the Data ability.

参数:

uri - Indicates the Data ability of the method to call.

method - Indicates the method to call.

arg - Indicates the parameter of the String type.

extras - Indicates the parameter of the PacMap type. If a custom Sequenceable object is put in the PacMap object and will be transferred across processes, you must call BasePacMap.setClassLoader(ClassLoader) to set a class loader for the custom object. If the PacMap object is to be transferred to a non-OHOS process, values of primitive types are supported, but not custom Sequenceable objects.

返回:

Returns the return result of the called method.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

NullPointerException - Throws this exception if uri or method is null.

从以下版本开始:

1

getType

public String getType(Uri uri)
               throws DataAbilityRemoteException

Obtains the MIME type of the date specified by the given URI.

参数:

uri - Indicates the path of the data to operate.

返回:

Returns the MIME type that matches the data specified by uri.

抛出:

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

1

normalizeUri

public Uri normalizeUri(Uri uri)
                 throws DataAbilityRemoteException

Converts the given uri that refers to the Data ability into a normalized Uri. A normalized URI can be used across devices, persisted, backed up, and restored.

To transfer a normalized URI from another environment to the current environment, you should call this method again to re-normalize the URI for the current environment or call denormalizeUri(ohos.utils.net.Uri) to convert it to a denormalized URI that can be used only in the current environment.

参数:

uri - Indicates the Uri object to normalize.

返回:

Returns the normalized Uri object if the Data ability supports URI normalization; returns null otherwise.

抛出:

DataAbilityRemoteException - Throws this exception if the remote process exits.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

3

另请参阅:

denormalizeUri(ohos.utils.net.Uri)

denormalizeUri

public Uri denormalizeUri(Uri uri)
                   throws DataAbilityRemoteException

Converts the given normalized uri generated by normalizeUri(ohos.utils.net.Uri) into a denormalized one.

参数:

uri - Indicates the Uri object to denormalize.

返回:

Returns the denormalized Uri object if the denormalization is successful; returns the original Uri passed to this method if there is nothing to do; returns null if the data identified by the normalized Uri cannot be found in the current environment.

抛出:

DataAbilityRemoteException - Throws this exception if the remote process exits.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

3

另请参阅:

normalizeUri(ohos.utils.net.Uri)

reload

public boolean reload(Uri uri,
                      PacMap extras)
               throws DataAbilityRemoteException

Reloads data in the database.

参数:

uri - Indicates the position where the data is to reload. This parameter is mandatory.

extras - Indicates the PacMap object containing the additional parameters to be passed in this call. This parameter can be null. If a custom Sequenceable object is put in the PacMap object and will be transferred across processes, you must call BasePacMap.setClassLoader(ClassLoader) to set a class loader for the custom object.

返回:

Returns true if the data is successfully reloaded; returns false otherwise.

抛出:

DataAbilityRemoteException - Throws this exception if the remote process is abnormal.

从以下版本开始:

4

obtainInputStream

public InputStream obtainInputStream(Uri uri)
                              throws DataAbilityRemoteException,
                                     FileNotFoundException

Obtains the input stream of a file. You must have correctly implemented the Ability.openFile(Uri, String) method before using this method.

参数:

uri - Indicates the path of the file to open.

返回:

Returns the input stream of the file.

抛出:

FileNotFoundException - Throws this exception if the file is not found.

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalArgumentException - Throws this exception if a parameter value is invalid.

IllegalStateException - Throws this exception if the specified URI does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

5

obtainOutputStream

public OutputStream obtainOutputStream(Uri uri)
                                throws DataAbilityRemoteException,
                                       FileNotFoundException

Obtains the output stream of a file. You must have correctly implemented the Ability.openFile(Uri, String) method before using this method.

参数:

uri - Indicates the path of the file to open.

返回:

Returns the output stream of the file.

抛出:

FileNotFoundException - Throws this exception if the file is not found.

DataAbilityRemoteException - Throws this exception if a remote process exception occurs.

IllegalArgumentException - Throws this exception if a parameter value is invalid.

IllegalStateException - Throws this exception if the specified URI does not exist.

NullPointerException - Throws this exception if uri is null.

从以下版本开始:

5