This chapter describes how to setup DidiSoft OpenPGP Library for Java in your project and application. It assumes that you have already downloaded and unpacked the evaluation or production version on your development machine.
Table of contents
1. Library files
2. Add the library to the Eclipse IDE
3. Add the library to the NetBeans IDE
4. Embed the library into a single JAR file (command line or Swing/SWT application)
5. Include the library into a Web application (WAR)
6. Maven
1. Library files
The library consists of three JAR files located in the /Library folder in the distribution zip archive (/Bin in previous versions). They must be included in your project and application CLASSPATH:
- pgplib-3.0.0jar
- bcpg-jdk15on-15-lw.jar
- bcprov-jdk15on-15-lw.jar
Note: The two jar files that start with bc* are from the BouncyCastle open source library in a no-conflict mode. This means that you can safely use other versions of the BouncyCastle library in the same project without any class collisions.
2. Add the library to the Eclipse IDE
First you have to unpack the library into a folder. Then follow the steps bellow in order to include the library JAR files into your Eclipse projects:
1. Right click on your project in the ‘Package Explorer‘ view in Eclipse
2. Select ‘Properties‘ from the popup menu
3. Select ‘Java Build Path‘ from the left navigation list
4. Select the ‘Libraries‘ tab on the right side of the window
5. Click the ‘Add External JARs‘ button if the library is unpacked outside your project folder or the ‘Add JARs‘ button if they are in your project tree
6. Navigate to and select the library JAR files
3. Add the library to the NetBeans IDE
Assuming that you have unpacked the library into a folder please follow the steps bellow in order to include the library JAR files into your NetBeans projects:
1. Right click your project in the ‘Projects’ list view
2. Select ‘Properties‘ from the popup menu
3. Select ‘Libraries‘ from the left navigation list
4. Click the ‘Add JAR/Folder‘ button
5. Select the library jar files and then click the ‘OK‘ button
4. Embed the library into a single JAR file
If you are building a desktop console or Swing/SWT Java application you may want to distribute it as a single JAR file. Here is how to embed the library jar files into a single JAR file with the Eclipse IDE export function.
1. Right click on your project in the ‘Package Explorer‘ view in Eclipse
2. Select ‘Export…‘ from the popup menu
3. Select ‘Java/Runnable JAR file‘ in the Export dialog then click the ‘Next‘ button
4. Select ‘Package required libraries into generated JAR‘ in the ‘Library handling‘ options
5. Click the ‘Finish‘ button and you are ready
5. Include the library into a Web application (WAR)
The usual way to include the library jar files into a Web application is to copy the jar files into the WEB-INF/lib folder of the web application. One disadvantage of this approach is that if you make hot deploys of the web application it will begin to fail with strange exceptions.
The reason for these exceptions is that the library JAR files are bundled with the web application. Hence after an application stop/start, they are loaded in another class loader, while the BouncyCastle security provider was already registered with a class loader that is unavailable, because it has been destroyed after the web application has stopped.
The solution to this situation is to ship the application without the library JAR files.
They must be placed in a folder shared for all applications running on the Application server.
Below are listed the shared folders for some application servers.
Glassfish
<glassfish folder>/domains/domain1/lib/
Tomcat 6.x
$CATALINA_BASE/lib/
Tomcat 5.x
<tomcat folder>/shared/lib/
WebSphere (WAS)
<was folder>/lib
WebLogic
<weblogic folder>/common/lib
JBoss
<JBoss folder>/server/<configuration>/lib
Note: If you application server is not mentioned here, please refer to your application server documentation in order to located the shared jar’s folder.
Using the library in Maven build
As of version 3.1.2 the library can be used in your project Maven build
Summary
This chapter described how to use the library in your Java project and how to deploy it afterwards. If you encounter any difficulties please do not hesitate to contact our technical support.
If you have succeeded installing the library you can continue with the examples that demonstrate the features of the library.
