Shared versus Bundled Libraries
Many BlackBerry® developers will be familiar with the shared library concept with both its advantages and disadvantages. A shared library can be created in the BlackBerry JDE from a Jar file, or from source in the BlackBerry® Java® Plug-in for Eclipse®. Creating a shared library in Eclipse is done by editing your project's BlackBerry_Application_Descriptor.xml file and setting the Application type to Library:
Libraries built using this technique are fully obfuscated, which could be important to you, but deploying these libraries can become complicated. If more than one application uses this library, and both are installed on a device, the libraries will overwrite each other - so it's important that changes between versions do not introduce compatibility problems. One technique that is sometimes used, is to build the library with a unique name for each application that uses it. That effort will grow significantly if many applications use the same library. A version based naming system could also be used, with dynamic loading of the installed libraries using Class.forName().
Shared libraries do use less space since there is only a single instance of the code on the device, and are necessary if any use of Persistent Store APIs are involved. See the Persistent Store Best Practices guide for details.
Bundled libraries do not have the same intrinsic obfuscation, or support for Persistent Store, but they are considerably easier to deploy. In fact, this approach includes the library jar inside the application modules themselves so that they are not separately named or deployed. The Analytics, Ad Services and Payment Services SDKs use this approach. These libraries are built in the BlackBerry Java Plug-in for Eclipse just as if they were a normal application, keeping the Application type set to Application.
An application that uses the library just needs to import the Jar file into it's build path, making sure to check the Export option for the library so that it is included in the build.
When the Jar is added and the project is built all the cod files are from the same application, there are just more of them, so you will deploy the application the same way as you would normally.
Releasing a Library for BlackBerry Java Development
When creating a library for use in BlackBerry Java Development, you have the choice of several approaches. Of course you can release the source with a suitable license, or you can release a package with the library built in advance. If you release a package then you have a choice between the cod (a shared library) or the jar (a bundled library), following the instructions and caveats detailed above.
Given the problems with deployment that occur with using a shared library approach, it's recommended to use that approach only when necessary. Instead, build your library as an Application, include a 3rd party obfuscation step if you desire, and release the Jar file to be incorporated into the end project.
Build and release your JavaDoc™ files with the Jar as well so that developers using the library can use code hinting and code completion while developing.
It's important to note that when releasing a compiled library you need to be clear about what version of software it was written for, as it will be forward compatible but not backward compatible. For example, if you build your library in BlackBerry SDK 5.0, it can be packaged into applications written for 5.0, 6.0 and newer, but not versions older than 5.0. Include this information in the package you release (with the JavaDocs).
Using a 3rd Party library Jar
If you are going to use a 3rd party library Jar, it's best to make sure it's going to work before investing too much time with it. Make sure the library was written for BlackBerry Java or J2ME (not J2SE). Also, make sure you know what BlackBerry SDK it was designed to work with if it was built using BlackBerry Java APIs.
You will want to Preverify the Jar to make sure that it's going to work, and to create a build of it that doesn't use advanced Java language features, if it was built with a 1.6 class file spec for example.
Find the preverify tool in the bin directory of your component back, such as:
Run the preverify tool on the Jar, passing in the BlackBerry SDK jar on the classpath:
"preverify -classpath ../lib/net_rim_api.jar ThirdPartyLibrary.jar"
The new Jar will be created in the ./output directory. Add this Jar to your project in Eclipse and remember to check the Export option as shown above.