Java
Registry API Specification Document
Changes
in Java Registry API documentation
Changes in Java Registry
API
Purpose
Java Registry API provides information
about the installed Java applications and installation packages together called
as Java entities. The most common Java installation package is the MIDlet
Suite and Java application is the MIDlet. In the future there can be additional
Java applications and installation packages.
Constraints
There
are no exceptions regarding Java Registry API.
API description
Clients of Java
Registry API can check which Java entities are installed on the device and
can obtain information about the installed entities. This API is read-only.
Java entities are identified with unique IDs (UIDs). Each installed Java entity
is represented in the Java Registry by a registry entry. The entries are created
during installation time. A registry entry is identified with the same UID
as the Java entity which is represented by this entity. These registry entries
are abstracted in the Java Registry API. A registry entry contains information
(attributes) about the represented Java entity (for example name, type of
the entity, drive where the entity was installed).
Java Registry API
is a Library API, the implementation units are delivered in a DLL, so many
clients can share the same implementation.
The type of this interface
is a normal method call interface. All the methods in the API are synchronous.
API class structure
The API contains
the following classes:
- The
CJavaRegistry class; this
class must be instantiated by the client to be able to use Java Registry services.
The methods of this class can return the UIDs of stored registry entries and
can access registry entries based on UIDs.
- The
TJavaRegistryEntryType is
an enumeration containing the Java entity types namely the registry entry
types representing the entities.
- The
CJavaRegistryEntry class;
this is the base class of the specific registry entry classes intended for
derivation, contains the common attributes of the derived registry entry classes
-
The
CJavaRegistryPackageEntry is a class of registry entry
representing Java installation packages (for example a MIDlet Suite)
-
The
CJavaRegistryApplicationEntry is a class of registry
entry representing Java applications (for example a MIDlet)
Related APIs
CJavaRegistryCJavaRegistryApplicationEntryCJavaRegistryEntryCJavaRegistryPackageEntryTJavaRegistryEntryType
Using Java Registry API
Check if a registry entry exists
Client
obtains from AppArc an application UID and it would like to know if this represents
a Java application. If the UID is found in Java Registry than this means that
it represents a Java application which is installed on the device.
The
following code snippet describes the above mentioned use case. Application
instantiates
CJavaRegistry class and calls its proper method
to get to know if the entity with the given UID is installed (i.e. contained
by the registry).
#include <javaregistryincludes.h>
using namespace Java; TBool CExample::CheckRegistryEntryExistsL( TUid aUidToBeChecked
) { TBool ret; CJavaRegistry* javaRegistry = CJavaRegistry::NewLC(
); ret = javaRegistry->RegistryEntryExistsL( aUidToBeChecked ); CleanupStack::PopAndDestroy(
javaRegistry ); return ret; }
Related APIs
Get UIDs of stored registry entries
The
registry clients can get the UIDs of the entries stored by the registry. It
is possible to get UIDs of all stored entries or UIDs of a certain type of
stored entries.
Get UIDs of all stored
registry entries
Client would like to have the UIDs
of all entries stored by registry.
The
above mentioned use case is described in the following code snippet. Client
instantiates the
CJavaRegistry class and pass as argument
an RArray<TUid> reference to the GetRegistryEntryUidsL method.
Registry inserts the UIDs of all the stored registry entries in the array
passed as argument to the method.
#include <javaregistryincludes.h>
using namespace Java; void CExample::GetRegistryEntryUidsL( RArray<TUid>&
aAllUids ) { CJavaRegistry* javaRegistry = CJavaRegistry::NewLC( );
javaRegistry->GetRegistryEntryUidsL( aAllUids ); CleanupStack::PopAndDestroy(
javaRegistry ); }
Related APIs
CJavaRegistryGetRegistryEntryUidsLRArray<TUid>
Get
UIDs of certain type of stored registry entries
Client would
like to have the UIDs of a certain type of entries contained in registry.
The
above mentioned use case is described in the following code snippet. The client
instantiates the
CJavaRegistry class and calls the GetRegistryEntryUidsL method
with first argument specifying the type of entries it is interested in (in
this example EMidp2MidletSuite) and the second argument an RArray<TUid> reference
. The UIDs of the registry entries with the given type (package entries) are
inserted in the array passed as second argument of the method.
#include
<javaregistryincludes.h> using namespace Java; void CExample::GetRegistryPackageEntryUidsL(
RArray<TUid>& aPackageUids ) { CJavaRegistry* javaRegistry
= CJavaRegistry::NewLC( ); javaRegistry->GetRegistryEntryUidsL( EMidp2MidletSuite,
aPackageUids ); CleanupStack::PopAndDestroy( javaRegistry ); }
Related APIs
CJavaRegistryEMidp2MidletSuiteGetRegistryEntryUidsLRArray<TUid>
Get registry entries
If the client would
like to get further information related to an installation package or an
installed application, it should retrieve the corresponding entry and use
the associated methods.
Get package
entry
The client would like to know some information related
to an application of a Java installation package and for this reason first
gets the package entry representing this entity and using this entry get the
information of the entity, and using the methods of this entry gets the required
information
The
above mentioned use case is described in the following code snippet. Client
instantiates the
CJavaRegistry class and gets a registry
entry with a given UID using the RegistryEntryL method. For
accessing type specific information the client needs to cast the registry
to its appropriate subtype. Subtype can be decided based on the value of the
type attribute. If the value is between EMidp2MidletSuite and EMidp2Midlet then
the subtype is CJavaRegistryPackageEntry. After the cast
it is possible to get the information of the obtained package entry (the vendor
name in our example).
#include <javaregistryincludes.h>
using namespace Java; void CExample::GetVendorNameL( TUid& aUid, TDes&
aVendorName ) { CJavaRegistry* javaRegistry = CJavaRegistry::NewLC(
); CJavaRegistryEntry* entry = javaRegistry->RegistryEntryL( aUid );
if ( entry->Type() >= EGeneralPackage && entry->Type() < EGeneralApplication
) { CJavaRegistryPackageEntry* packageEntry =
( CJavaRegistryPackageEntry* ) entry; aVendorName.Append( packageEntry->Vendor()
); delete entry; CleanupStack::PopAndDestroy( javaRegistry
); }; else { delete entry; CleanupStack::PopAndDestroy(
javaRegistry ); User::Leave(...); } }
Related APIs
CJavaRegistryCJavaRegistryPackageEntryEMidp2MidletEMidp2MidletSuiteRegistryEntryL
Get application entry
The client would
like to know some information of an application like Java entity and for this
reason first gets the application entry representing this entity and using
this entry could obtain the information of the entity.
The
above mentioned use case is described in the code snippet below. The client
instantiates the
CJavaRegistry class and gets a registry
entry with a given UID using the RegistryEntryL method. For
accessing type specific information the client needs to cast the registry
to its appropriate subtype. The subtype can be decided based on the value
of the type attribute. If the value is greater than EGeneralApplication then
the subtype is CJavaRegistryApplicationEntry. After the cast
it is possible to get the information of the obtained application entry (the
group name in our example).
#include <javaregistryincludes.h>
using namespace Java; void CExample::GetGroupNameL( TUid& aUid, TDes&
aGroupName ) { CJavaRegistry* javaRegistry = CJavaRegistry::NewLC(
); CJavaRegistryEntry* entry = javaRegistry->RegistryEntryL( aUid );
if ( entry->Type() >= EGeneralApplication ) { CJavaRegistryApplicationEntry*
applicationEntry = ( CJavaRegistryApplicationEntry* ) entry;
aGroupName.Append( applicationEntry->GroupName() ); delete
entry; CleanupStack::PopAndDestroy( javaRegistry ); };
else { delete entry; CleanupStack::PopAndDestroy(
javaRegistry ); User::Leave(...); } }
Related APIs
CJavaRegistryCJavaRegistryApplicationEntryEGeneralApplicationRegistryEntryL
Get application attribute
The client
would like to know some application developer defined attributes of a Java
application. In case of MIDlet, the client can fetch attributes defined in
the JAD file and in the manifest of the JAR file.
The
above mentioned use case is described in the following code snippet. The client
instantiates the
CJavaRegistry class and fetches CJavaRegistryApplicationEntry.
To read one attribute you must use method AttributeL and
if you would like to read all attributes, you must use methodAttributesL.
If the requested attribute is not defined, AttributeL returns NULL.
NOTE:
The ownership of the
MJavaAttribute objects referred to by
the returned pointers is not transferred to the client.
MJavaAttribute
has three methods.
Name() returns name of attribute, Value()
returns attribute value and Trusted() returns if attribute
is trusted or not. In case of MIDlet, attribute is trusted if it is present
in JAR manifest, the MIDlet Suite is signed and signature can be verified.
#include
<javaregistryincludes.h> using namespace Java; void CExample::GetGroupNameL(
TUid& aUid, TDes& aGroupName ) { CJavaRegistry* javaRegistry
= CJavaRegistry::NewLC( ); CJavaRegistryEntry* entry = javaRegistry->RegistryEntryL(aUid);
const MJavaAttribute* attribute = entry->AttributeL(_L("Nokia-MIDlet-Category"));
TPtrC& value = attribute->Value().Des(); TBool trusted = attribute->Trusted();
delete entry; CleanupStack::PopAndDestroy( javaRegistry );
} }
Related APIs
AttributeLAttributesLCJavaRegistryCJavaRegistryApplicationEntryMJavaAttributeNULLName()Trusted()Value()
Error
handling
Java Registry API methods may leave with one
of the system-wide error codes.
Memory
overhead
Memory consumption of Java Registry API is
directly proportional with the number of registry entry objects read by the
client. Memory consumption of one registry entry depends from the contained
attributes and their length but usually it is less than 1 Kbyte.
Extensions to the API
Java Registry
API is not intended to be extended.
Glossary
Definitions
| Java
entity |
It is a Java application (or package) which can be installed
on device (i.e. MIDlet Suite, MIDlet) |
|
registry entry
|
It
is an entry of Java Registry representing a Java entity
|