C H A P T E R 3 - File Organization and Naming

C H A P T E R 3

File Organization and Naming

This chapter describes how the Java Wireless Client software source code is organized and describes the naming conventions used for native files.

Source Code Organization

The following list shows the organization of the rest of the Java Wireless Client software source hierarchy. The files are located under the installDir/midp directory.

src/ - Top-level source directory

subsystemX/ - Top-level subsystem directory

subsystem.gmk - The subsystem makefile that combines the library makefiles for this subystem and defines settings common to the subsystem

libraryY/- Top-level library directory

libraryY/lib.gmk - Library makefile. Contains rules and settings specific to this library.

libraryY/include - The libraryY exported native interface

libraryY/classes/ - Exported Java programming language interface

implementationZ/ - Implementation of this library

implementationZ/lib.gmk - Implementation makefile. Contains rules and settings specific to this implementation.

implementationZ/libinfo.gmk - Implementation descriptor. Specifies dependencies on other libraries.

implementationZ/include - Additional native exported interfaces specific to this implementation

implementationZ/classes - Java programming language class files for this implementation

implementationZ/native - Native files for this implementation

SubsystemX represents a Java Wireless Client software subsystem or service such as the record management system or the high-level user interface. LibraryY represents one of the libraries that constitute subsystemX. ImplementationZ is one of the alternative implementations of libraryY. TABLE 3-1 shows the Java Wireless Client software subsystems and their libraries. For libraries with more than one implementation, the alternative implementations are listed.

TABLE 3-1 Java Wireless Client Software Subsystems and Libraries
Subsystem	Libraries	Description
`ams/`	`ams_api`	Public API defined by the MIDP specification for the following: `javax.microedition.midlet. MIDlet` `javax.microedition.midlet. MIDletState` `ChangeException`
	`ams_base`	AMS functionality: Initializes MIDP Runs a MIDlet Registers, unregisters and gets the AMS isolate ID Gets the current foreground isolate ID and display
	`ams_jsr_interface`	Stub interfaces that handle functionality provided by optional packages
	`ams_util`	Miscellaneous AMS utilities: Start and terminate a MIDlet Verify a MIDlet suite Change an isolate's priority
	app_image_gen	Functionality required to generate a binary image from the MIDlet suite classes
	app_image_gen_base	Functionality to create an application image file
	`appmanager_ui`	Application manager UI-related functions: Displays a splash screen Displays a screen to enable MIDlet selection Changes a MIDlet suite's settings Shows a MIDlet suite's information
	appmanager_ui_resources	Export resources (splash screen picture) required by the application manager UI
	`autotester`	Testing functionality provided by `AutoTesterInterface`
	`autotester_base`	Functionality required by the `autotester` library that is common for all implementations
	cdc_application
	example
	`installer`	The classes and functions that install a MIDlet suite
	`jams`	The Java programming language implementation of the AMS (Java AMS)
	jump_application
	`midlet_suite_info`	Simple attribute storage for MIDlet suites
	`mvm`	An MVM-specific API that starts a MIDlet suite in a new isolate
	`nams`	The API for a native AMS (NAMS)
	nams_javacall
	ota	Discovery application and graphical installer MIDlets
	`platform_request`	Native `platformRequest()` function used to start a new process to handle a given URI
	suitestore	Functions that deal with MIDlet suite storage
	verifier
automation/		The internal automation API implementation
configuration/	configuration_xml	Configuration XML data
	properties	Functions that provide access to MIDP properties from the Java platform
	properties_port	Functions that provide access to MIDP properties from the native platform
`core/`	`crc32`	Functions that provide the CRC32 checksum calculation
	`global_status`	Global status constants definitions
	`javautil`	Basic Java platform utility classes (for example, `DateParser`)
	`kni_util`	Common helper functions on top of KNI
	`libc_ext`	ANSI C extensions (for example, `snprintf`)
	`log`	Native and Java platform logging support
	log_base
	`memory`	Native heap memory facility
	`native_thread`	Native threading facility
	`resource_handler`	Functions that provide access to system resources
	`resource_manager`	Native platform resource accounting
	services
	`storage`	Native storage abstraction layer
	`string`	String operations
	suspend_resume
	`timer_queue`	Native timer queue for master mode
	`timezone`	Timezone information
	`vm_services`	Miscellaneous services provided by the VM (current time, current isolate ID, thread wait and signal)
demos/
events/	`eventqueue`	Java platform and native platform events and event queues
	eventqueue_port	Platform-specific event queue implementation
	eventsystem	Event processing-specific functionary (master mode vs. slave mode), the main VM loop, event checking
	input_port
	mastermode_port	Platform-specific master mode implementations
	slavemode_port	Platform-specific slave mode implementations
`highlevelui/`	annunciator	Annunciators (sound, vibration, network indicators)
	armsd_application	ARMSD-specific services
	directfb_application
	fb_application	Linux/FB-specific services
	fb_port
	javacall_application
	keymap	Mapping between key codes, game actions, key names
	lcdlf	UI look and feel
	lcdui	Java platform high-level UI (`display` and `displayables`)
	lfjport	Java platform look and feel porting interface
	lfpport	Platform look and feel porting interface
	nativepti_port	Platform-specific implementation for native predictive text support
	nim_port
	pti_api	Java platform interface to predictive text support (`javapti` and `nativepti` implementations)
	qte_application	Linux Qt-specific services
	win32_application	Win32-specific services
	wince_application
`i18n/`	`i18n_main`	Functions that provide character conversion and access to locale-specific information
	`i18n_port`	Interface to platform-specific character converters
links/	classes
	i3test
	native
`lowlevelui/`	`graphics`	PutPixel and platform graphics implementations
	`graphics_api`	Java platform low-level UI (drawing primitives, fonts, images)
	`graphics_util`	Common services for PutPixel and platform graphics
	`platform_graphics_port`	Porting interface for platform graphics
media/	reference
mmapi/	classes
nuts/	include
	reference
porting_demos/
`protocol/`	`cdc_application`
	file	Internal file access
	`gcf`	Base networking classes
	`http`	HTTP connections
	`https`	HTTPS connections
	`serial`	Serial port connections
	`serial_port`	Serial port connection porting interface
	`socket`	Socket connections
	`socket_notify`	Network event notification facility
	`ssl`	SSL connections
	`ssocket`	Server socket connections
	`udp`	Datagram connections
push/	nativepush_port	A native (external) push implementation
	push_api	The Java platform push API and implementation
	push_gcf
	push_server	A low-level push implementation. An interface to subsystems providing resources on which push can be registered.
	push_timer	A platform-specific alarm-based push implementation
restricted_crypto/	reference
`rms/`	`record_index`	RMS index (linear, tree)
	`record_store`	Native interface to RMS
	`rms_api`	Java platform interface to RMS
	`rms_base`	Basic RMS utilities
	`rms_exc`	Java platform RMS exceptions
`security/`	`crypto`	Interfaces to crypto functions and the exportable implementation classes
	`file_digest`	Classes used to create an unpredictable digest of a file
	`internal_api_protection`	Classes used to protect public internal APIs from unauthorized use
	`midp_permissions`	Policy used for grouping MIDP permissions
	`native_dialog_port`	Switch library used for native permission dialogs
	`permission_dialog`	Classes used to enable the user to grant or deny a running MIDlet suite a MIDP permission
	`pki`	The PKI certificate API
	`publickeystore`	Trusted public key storage
	`secure_random`	Functions that provide unpredictable random data. Each implementation is device specific.
ssl/	reference
test/	common
tool/	chameleon
	fontgen
	imageutil
	jadtool
	l10ngen
	mekeytool
	upgradel10n

See the Build Guide for instructions about how to add a directory for your platform, as well as subsystems and libraries.

When you add a new library to the existing subsystem, put the exported native interface of this library into a subdirectory named include. Then add one or more implementations of this interface into the respective subdirectories.

Naming Convention for Native Files

Subsystems and libraries use the following naming conventions.

Files whose names end with the _md suffix contain implementations of functions that use system-specific mechanisms that are likely to differ from device to device. The _md suffix stands for "machine dependent." The functions in these files are not public.

Native files in libraries that belong to the low-level UI and high-level UI subsystems are named with the library-specific prefixes shown in TABLE 3-2.

TABLE 3-2 Native File Library Prefix Examples
Library	Prefix
graphics_api `graphics` graphics_util platform_graphics_port annunciator armsd_application directfb_application fb_application javacall_application keymap lcdlf (lfjava, lfplatform implementations) lfjport lfpport qte_application wince_application win32_application	gxapi_ `gx_` (shared include files) `gxj_` (putpixel) `gxp_` (platform_graphics) gxutl_ gxpport_ anc_ armsdapp_ `directfbapp_` (unsupported) fbapp_ jcapp_ keymap_ lcdlf_ (lfj_, lfp_) lfjport_ lfpport_ qteapp_ `winceapp_` (unsupported) win32app_

JavaCall API Directory Structure

The JavaCall API is distributed in the javacall and javacall-com subdirectories under the main Java Wireless Client software directory. These subdirectories contain the header files that define the JavaCall API as well as a full implementation for Windows.

javacall and javacall-com have similar internal structures. The JavaCall API header files are contained in javacall/interface and javacall-com/interface. Each header file contains a set of related functions. The header files for MIDP live in subdirectories of javacall/interface/midp. Header files for optional APIs are contained in directories corresponding to their defining JSR. For example, the JavaCall API for Bluetooth functionality is contained in javacall-com/interface/jsr82_bt.

Optional APIs might have more than one header file that defines the corresponding JavaCall API. For example, the PIM and FileConnection APIs defined by JSR 75 are represented by these headers:

javacall-com/interface/jsr75_pim_fc/javacall_pim.h

javacall-com/interface/jsr75_pim_fc/javacall_fileconnection.h

The JavaCall API includes an implementation for Windows in javacall/implementation/win32 and javacall-com/implementation/win32. The source files are organized in a structure similar to the structure for the header files. For example, javacall/implementation/win32/midp/lcd.c is the implementation of the JavaCall API defined in javacall/interface/midp/javacall_lcd.h.