Version 5 Development

Overview

Version 5 code is being introduced into the v4 and v4.5 systems via modules. This document addresses both the issues involved in doing that, and the development conventions and standards for v5 code in general.

Package naming

All new packages will have a prefix of com.partnersoft.v5.* and are always in lowercase. This firmly distinguishes the v5 API from other versions; we will continue this if we ever get to v6 with a v6 designator.

The platform is subdivided into major sub-platforms, which we call “frameworks”. They are as follows:

• boots - core launching, cog, scripting, logging, Update, Help!, Workbench, etc.
• kilt - sql, forms, guis, web services, etc.
• map - rover, publishing, viewing, the Map Viewer
• haversack - distributed data editing and mapping
• macleod - hosted server and related services

These are further subdivided by the Java runtime the code will work in. These roughly correspond to operating systems or Java environments:

• core - any supported Java environment,
• javase - Java Standard Edition (the full environment used in Windows, Mac OS, etc.),
• ios - Apple iOS via Google’s j2objc, and
• android - Google Android.

Note that this isn’t the same as the operating system (OS); operating-system-specific code goes in subpackages named os.FOO where FOO is the operating system name:

• windows
• mac
• linux
• ios
• android

Non-framework modules must follow the same rules, but packages go under com.partnersoft.v5.modules.MODULE where MODULE is the name of the module in lowercase.

So - to distill - packages in frameworks follow this naming pattern:

com.partnersoft.v5.FRAMEWORK.RUNTIME.FOO.BAR...

and OS-specific code goes in something like:

com.partnersoft.v5.FRAMEWORK.RUNTIME.os.OPERATINGSYSTEM...

and module code goes in something like:

com.partnersoft.v5.modules.MODULE...

and module OS-specific code goes in:

com.partnersoft.v5.modules.MODULE.os.OPERATINGSYSTEM...

V5.x inclusion in v4.x releases

All code must be written to be compatible with BOTH 4.4 and 4.5 branches.

The v5 in the package naming should prevent any conflicts between class names etc. Third-party code is more problematic; we need to work with the third-party code already standard in v4.x.

Module naming

Module names need to be very predictable. Use these guidelines:

• strict capitalization by word, not StUDlyCAPs (e.g. DisspatchMobileInterface and not DisSPatchMobileInterface, MysqlSqlDriver not MySQLSQLDriver).
• FooLibrary - a code library, usually a third-party one, e.g. AntlrLibrary
• FooBarDriver - a driver for a specific pluggable subsystem, e.g. TrimbleGpsDriver, OracleSqlDriver
• FooTest - a test module associated with another module, e.g. TrimbleGpsDriverTest
• Foo - a framework module, e.g. Boots, Kilt, Macleod
• FooApplication - a module containing an application, which in our system is probably a combination of tools and mapsets - e.g. FieldDesignerApplication
• FooProduct - product-level stuff; might not have much if any actual code, but instead just define which modules are associated, e.g. FieldDesignerProduct
• FooDevelopment - design and other developer-type documentation (javadoc, etc.). E.g. BootsPlatformDevelopment
• FooManual - a user manual, e.g. FieldDesignerProductManual
• FooService - a module containing documentation and tools for performing a service, e.g. SystemRecoveryService
• FooInterface - a module containing a software-to-software (not software-to-user) interface, e.g. MultiSpeakAccountingInterface
• FooMapset - a simple mapset application, not big enough to deserve the Application suffix

We can retain our simple names for modules like Tracing, Gps, etc. Ideally if you look at an alphabetical listing of modules, you should see associated modules next to the modules associated with them - e.g. Gps, GpsMapset, GpsTest, GpsMapsetTest, etc.

Subversion storage

V5 code lives in standard v4-style modules in http://developer.partnersoft.com/modules/branches/5/.

When code is branched for testing, projects, or release, modules are placed in subdirectories based on the original code branch - so e.g.

modules/releases/4.13/5/FOO modules/releases/4.13/5/BAR modules/releases/4.13/4/BAZ modules/releases/4.13/4/WOBBLE