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.

Use cases

Most important
use cases of Java Registr...


Most important use cases of Java Registry API

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)

Class Structure of Java Registry API


Class Structure of Java Registry API

Related APIs
  • CJavaRegistry
  • CJavaRegistryApplicationEntry
  • CJavaRegistryEntry
  • CJavaRegistryPackageEntry
  • TJavaRegistryEntryType

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.

Client checks if registry entry exists


Client checks if registry entry exists

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

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.

Client gets from registry
the UIDs of al...


Client gets from registry the UIDs of all stored entries

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
  • CJavaRegistry
  • GetRegistryEntryUidsL
  • RArray<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.

Client gets from registry the UIDs of a...


Client gets from registry the UIDs of a certain type of entries

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
  • CJavaRegistry
  • EMidp2MidletSuite
  • GetRegistryEntryUidsL
  • RArray<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

Client gets from registry a package entr...


Client gets from registry a package entry to be able to obtain the attributes of package like entity

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
  • CJavaRegistry
  • CJavaRegistryPackageEntry
  • EMidp2Midlet
  • EMidp2MidletSuite
  • RegistryEntryL

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.

Client gets an application entry from th...


Client gets an application entry from the registry to be able to obtain the properties of an application like 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
  • CJavaRegistry
  • CJavaRegistryApplicationEntry
  • EGeneralApplication
  • RegistryEntryL

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.

Client gets
an package entry from the re...


Client gets an package entry from the registry to be able to read application attributes

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
  • AttributeL
  • AttributesL
  • CJavaRegistry
  • CJavaRegistryApplicationEntry
  • MJavaAttribute
  • NULL
  • Name()
  • 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

Abbreviations

None

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

References