Main Page | Modules | Namespace List | Class Hierarchy | Data Structures | Directories | File List | Namespace Members | Data Fields | Globals

Bundle Manager


Detailed Description

The Bundle Manager is a system framework designed to coordinate and control the installation, and removal of software components, including applications and shared libraries, for various target subsystems, including the ALP native application format.

It is intended that the Bundle Manager provide the mechanism to install and track applications for other executable systems, as a 68K compatiblity environment, or Java apps.

The Bundle Manager APIs operate on three levels:

Bundle Indexes: every bundle present in the system has a unique index number, and index values will not be re-used. These indexes are stored in variables of type AlpBundle. You'll use bundle indexes to iterate over available bundles, retrieve metadata, and generally work across multiple bundles.

Bundle Refs: in order to operate on the contents of a bundle, it must be opened. This gives back a handle, stored in a variable of type AlpBundleRef. Many operations can only be performed on a bundle if it is open. (Generally, the contents of a bundle are only accessible while it is open. Other information, such as metadata, can be accessed if it isn't open.) You'll use bundle refs to work within a particular bundle. Opening a bundle to get a ref is a potentially expensive operation (consuming time, memory, limited resources, etc.) so you want to do this only when you have to.

Bundle Names: each bundle has a supplied name of some sort. Bundles can be retrieved by name. However, there can be conflicts (bundles of the same name, perhaps installed on separate locations on the system). If there are conflicts, one bundle is always 'elected' to respond to the name, based on conflict resolution rules. The name of a bundle is text, and is intended as a symbolic reference. You'll use bundle names to retrieve a bundle by a symbolic name, probably as part of the your program's resource material.

There are some other concepts used by the Bundle Manager:

Schemes: each type of bundle is considered a distinct 'scheme'. The ALP native appliacation format is the 'bar' scheme.

Stores: each bundle is stored in a particular location (perhaps a folder in a file-system). A 'store' is a name for such a location.

Images: one of the characteristics of a bundle is that it can be put into a flattened format for transmitting off of the device, to a another device, "beamed" via IR, attached to e-mail, downloaded off the web, etc. An "image" is flat file containing a bundle.

Metadata: information about a bundle is called "metadata". This includes material retrieved from the bundle's header/manifest/etc., as well as dynamic information about the actual use of the bundle (ref-count, system paths, etc.) Metadata for a bundle can be retrieved without opening the bundle.

Properties: a property is generic (but structured) material associated with a bundle. In the case of ALP native bundles, the properties are retrieved from arbitray XML in the bundle's manifest. Properties are intended for customization by the developer, representing arbitray information about a bundle. Various ALP components may rely on particular properties, such as the Application Manager using the "application" property. Properties for a bundle can be retrieved without opening the bundle.

URLs: various naming concepts used by the Bundle Manager are designed to be represented as text, which can be fitted together into standard URL syntax. To give a quick example of some of the possibilities:

                bar:com.access.apps.memo
                bar:com.access.apps.memo/ListView.xml
                bar:com.access.apps.memo/libalp_memo.so?main
                bar:com.access.apps.memo/^p/application/icon

These represent scheme:name/path?entry, as will be described in the API reference. Generally, you don't need to use URLs with the Bundle Manager APIs, however there are a few routines which benefit from them, and give a lot of flexibility if they are used.

ALP native bundles

ALP native bundles are represented as folders or bar files which contain a Manifest.xml at its root.

The Manifest must have an outer-most <manifest> element, which can have these attributes:

name: this attribute is required, and contains the name of the bundle. It should not start with "bar:", as that part of the name is implied.

version: this attribute is optional, and if present should be an integer. If not present, the bundle version is considered to be 0.

arch: this attribute is optional, and if present should be a string indicating which architecture this bundle is intended for.

desired_filename: this attribute is optional, and if present indicates the file name which should be used to convert the bundle to an image file. The name given will have the ".bar" extension appended to it.

searchpath: this attribute is optional. If present, it should be a string in the form of a set of colon separate path prefixes, potentially containing "^l" to indicate a locale fill-point. This affects how localized resources are searched for. If not present, it defaults to /rsc/^l/:/.

textdomain: this attribute is optional. If present, it defines the gettext omain applied by default to code running from this bundle. It should be a string potentially containing "^n" or "^N". The former is mapped to the bundle name without scheme ("com.companyname.appname"), while the latter is mapped to the complete bundle name ("bar:com.companyname.appname"). If not present, this attribute defaults to bar-^n.

bindtextdomain: this attribute is optional. If present, it defines the directory the gettext domain is bound to. It should be a string which defines a path relative to the base of the bundle. If not present, this attribute defaults to rsc.

The rest of the manifest should be in this form:

  <manifest name="foo.bar" searchpath="/share/%L/:/">
   <a>
     <b>1</b>
     <c>2</c>
   </a>
   <a>
     <x></x>
   </a>
   <other>
      <somevalue/>
   </other>
  </manifest>

Any elements within the manifest at the third level ("b", "c", and "x" in the above example) will be registered as bundle "properties", specifically:

   property "a", #0, key "b" -> "1"
                     key "c" -> "2"
   property "a", #1, key "x" -> ""
   property "other", #0, key "somevalue" -> ""

Any second-level elements not containing third-level elements, or any elements otherwise not conforming, will be ignored for the purpose of generating bundle properties. They won't prevent the bundle from being accepted, however.

Two properties have specific impact on the support for native bundles:

    <reference>
      <to>bundle-name</to>
      <optional/>
    </reference>

Any "reference" properties present will indicate that this bundle has a dependency on another bundle, particularly regarding use of shared libraries exported by the other bundle. The other bundle will automatically be opened when this bundle is opened. If the "optional" element isn't present, then this bundle cannot be opened if the one it is dependant on isn't present.

    <export>
       <library>somelib.so</library>
       <as>lib_somelib.so.3</as>
    </export>

Or

    <export>
       <classpath>lib/myclass.jar</classpath>
    </export>

The "library" syntax will cause a library exported from this bundle to be available whenever the bundle is open. The optional "as" element changes the name used for the exported version of the library.

The "classpath" syntax adds an entry (either a folder or .jar file) to the CLASSPATH environment variable while the bundle is open.

Either "export" element can be repeated to export multiple things.

The resource files associated with ALP native bundles map directly to the contents of the bundle's folder. A path starting with a slash is a "fixed path", and matches only that exact file within the bundle: /rsc/MyView.xml. A path starting without a slash is looked up through the locale search path, which can translate "MyView.xml" into "/rsc/en_US/MyView.xml", as appropriate.

Note that the use of a leading slash to distinguish fixed paths from localized paths means that you might need to use two slashes in URL syntax:

   bar:com.access.apps.memo//my/filename

There is one "magic" resource syntax specifically supported by ALP native bundles: the translation syntax is:

   ^t/Some string

This "path" will be retrieved by taking the part of the path after the slash, and feeding it through gettext() to perform a translation to the current locale. The result of the translation is considered the "contents" of the resource.

In URL syntax:

   bar:com.access.apps.memo/^t/MemoPad


Modules

 Private


Generated on Sat Dec 16 20:29:50 2006 for hiker-0.9 by  doxygen 1.4.4