Setting Up

This article teaches you how to set up the JsaPar library for use in your own Java project. This article assumes that you already have knowledge of Java, Eclipse and Maven. If not, please read the following articles before continuing reading this article.

Prerequisites

Before using the JsaPar library in your Java project, you have to include the Java ARchive file (JAR) of the JsaPar library into your project. Because every developer uses its own prefered development environment (e.g. Eclipse, Netbeans, IntelliJ, JDeveloper, et cetera) we only describe how to set up the library within an (empty) project using the Eclipse development environment. Using Eclipse means that there are also several ways in how to add the JAR file to an (empty) Eclipse project. The most common ways to do this is: manually or by using a build manager like Apache Maven. Choose which way you prefer. After you have set up the library within your Java project, you can start reading the getting started article in which the basic API calls of the JsaPar library are introduced.

Adding the library to your Eclipse project manually

First download the latest JsaPar library JAR. You can download the latest JsaPar library JAR file from the developers website (http://jsapar.tigris.org/servlets/ProjectDocumentList). The file you need is called something like 'jsapar-1.6.0-binaries.zip'. When time progresses, the actual filename can contain a higher version number, so be aware to always get the latest/highest version available of the library. After the download completed, open the ZIP archive and locate the subdirectory 'lib' within the archive. Now unzip this 'lib' directory to a temporary location on your drive. If you have no program installed that can open and unzip this ZIP archive, give 7-Zip a try. Now you should have a file called 'jsapar-1.6.0.jar' in your temporary directory.

Now start your Eclipse environment and create a new java project by going to File > New > Java Project. Create a new folder named 'lib' in your project folder. This stands for "libraries" and will contain the JsaPar library JAR later on. The 'lib' folder should now be visible in your project and you should have the following situation as depicted in figure 1.

Figure 1: Initial situation.

Copy the JsaPar library JAR (i.e. jsapar-1.6.0.jar) you unzipped earlier into the temporary directory to the 'lib' folder in your Eclipse project by copy-pasting it to that folder. Do a refresh of your project by right clicking on the project name and select Refresh. Unfold the 'lib' folder in your Eclipse project and you should see that the folder now contains the JsaPar library JAR file as depicted in figure 2.

Figure 2: Added JsaPar library JAR under lib folder.

Before you can reference this newly added Java library from your own code within your own project, you have to add it to your Build path. You do this by right clicking on the JsaPar JAR under the 'lib' folder and select Build Path > Add to Build Path. Figure 3 illustrates this step.

Figure 3: Adding the JAR to the Build Path.

A new folder appears within the Eclipse package explorer called the Referenced Libraries folder. This means that the JsaPar library JAR is stored (under the 'lib' folder) and referenced within the project, so that you can actually use the library from your own code, as depicted in figure 4.

Figure 4: The JsaPar JAR is now stored and referenced within the Eclipse project.

Now make sure that you clean and refresh your Eclipse project to make sure that the JsaPar library can be addressed from your own Java code. You're ready setting up the JsaPar library to be used in your Eclipse project. You can now start reading the getting started article.

Note: if you are having difficulties setting up your JsaPar library to work with your own java code, please consult the troubleshooting section at the end of this page for assistance in solving your problem.


Adding the library to your Eclipse project using a build manager

Adding the JsaPar library JAR file to your (empty) Eclipse project using a build manager works a bit different than manually adding the JAR file. The difference is that you no longer have to download and add the library to the 'lib' folder yourself. The build manager (Maven) does that for you. The only thing you have to tell the build manager is which JAR file you want to use (dependency) and where to download that JAR file from (i.e. the location). There is no manual processing anymore, the build manager will take care of it. Well, that is only partially true, because the build manager must be able to download the JAR file from a local or central repository. So it needs access to a local or central repository and next to that, the JAR file must be available within this repository. That means that the specified package name, file name and version number must match the stored JAR file within the (remote) Maven repository. For now it isn't mandatory to understand all of this. Later on you will grasp the inner workings better after you have successfully completed the steps described below. If you want to know more about Maven, please consult the Apache Maven website and read the online available documentation. It is too extensive to discuss the build manager workings here. Therefore we will limit the explanation of the build management process to getting you starting with Maven and the JsaPar library, because that is indeed our main goal.

There are two situations in which you can add the JsaPar library to your Maven/Eclipse project. The first situation is when you start with a completely new project without any Maven settings. The second situation is when you already have an Eclipse project with Maven settings. We will discuss the first situation only (i.e. you start with a new project) because that describes the complete process from beginning to end.

Important:
Before we start creating a new project that has Maven capabilities, make sure you have Maven installed on your system and included in your classpath. Next to that, make sure you have set your environment variables for Maven too! You will also need to install the Maven plugin in Eclipse. This Eclipse plugin is called 'm2e plugin' and is available on the Eclipse marketplace (please visit: http://eclipse.org/m2e/). This plugin will help you to edit the Maven specific POM file easier. How to install Maven and the Maven-Eclipse plugin is beyond the scope of this article. Note: in the latest versions of Eclipse, this plugin is already included. In the steps below we assume you have set up the Maven application and the Maven-Eclipse plugin successfully. 


Now start your Eclipse environment and create a new Java project with Maven support by going to File > New > Other... as depicted in figure 5.

Figure 5: Creating a new Java project with Maven support.

You are prompted with a dialog window, as depicted in figure 6, in which you unfold the Maven tree and select the item Maven Project and press Next.

Figure 6: Select Maven Project from the Maven tree.

You will then see another dialog window, as depicted in figure 7, that doesn't need your attention, so just leave everthing as is and press Next.

Figure 7: Skip this dialog window.
In the following dialog window, as depicted in figure 8, you need to select the archetype* for your project. This is just a collection of templates for specific Maven projects. Select the archetype 'maven-archetype-quickstart' and press Next.

Figure 8: Select the Maven archetype.
* Tip: If you want to know more about the Maven archetypes then read the article 'introduction to archetypes' on the Maven website here.
    
Another dialog window appears, as depicted in figure 9. Here you specify the archetype parameters**: GroupId, ArtifactId and Version. These parameters are very important because by specifying these parameters you make your project JAR uniquely. A common practise is that you specifiy the GroupId as the reverse order of a domain name you control. For the ArtifactId you specify a name you want your JAR file to be named. For the version number, when initially started, you specify version '0.0.1-SNAPSHOT'. As you can see, the Package name is automatically filled in when you specify the GroupId and ArtifactId. Now click Finish to create your Java project with Maven support.

Figure 9: Specifying the archetype parameters.
** Tip: If you want to know more about the naming conventions of the Maven archetypes then read the article 'Guide to naming conventions on groupId, artifactId and version' on the Maven website here.

Finally you will see that the Java project is created and that there is (probably) one warning displayed within the Problems tab, as depicted in figure 10.

Figure 10: The created Java project with Maven support.

This happens frequently and is caused by the mismatch between the generated settings from the Maven archetype and the actual version of the Java Virtual Machine installed on your machine.
The complete warning description is: "Build path specifies execution environment J2SE-1.5. There are no JREs installed in the workspace that are strictly compatible with this environment.".
This sounds as if something is wrong, when actually this warning can easily be ignored because this is just a matter of selecting the correct installed JVM version. So if you really want to start with a fresh and warning free project environment, you have two choices:
1. Set the project settings to the correct and current installed JVM, or
2. Install another JVM version that matches the current project settings.

Which one you choose depends on restrictions you might have when working in a production/company environment. If this is the case, ask the architect on your project which settings for you apply. If you are working standalone and/or have no restrictions, you have the luxury to choose which option you pick. Mostly option 1 is the quickest that will solve the "problem".
Option 2 is chosen when you really depend on class compliance of the JVM.

Note: Within Eclipse there is a note on the Properties settings for 'Java Compiler', which says: "When selecting 1.5 compliance, make sure to have a compatible JRE installed and activated (currently 1.8). Configure the 'Installed JREs' and 'Execution Environments', or change the JRE on the 'Java Build Path'.".  

For now, we assume that option 1 is your best choice. This means that we are going to adjust the settings of our newly created Java project to meet the compliance level of the current installed JVM.

In Eclipse, select the root of your project (in this example it is 'myjarname') in the Package Explorer and select from the Eclipse menu: Project > Properties, as depicted in figure 11.

Figure 11: Selecting the properties of your Java Project.
A dialog window appears for your project properties. Select within the list of items on your left side the 'Java Build Path' option, if not already selected. Within this properties window, select the 'Libraries' tab, as depicted in figure 12.

Figure 12: Select the Java Build Path and the Libraries tab.
In the libraries list you see the item 'JRE System Library [J2SE-1.5]', select this option and see that on your right side the 'Edit...' button highlights. Press this 'Edit...' button, as depicted in figure 13.

Figure 13: Select the JRE system library.
Another dialog window appears, as depicted in figure 14. You can see that the 'Execution environment' of the System library is set to JavaSE-1.5 (jdk1.8.0).

Figure 14: Incorrect set execution environment.

In order to get rid of the warning in your project, you have to set the 'Execution environment' of the System library to the current and installed version on your system. This means, in this situation, that the 'Execution environment' must be set to JavaSE-1.8 (jdk1.8.0), as you can see in figure 15.

Figure 15: Correct set execution environment.
Now the Execution environment of your Java project is set to the correct and installed Execution environment. In other words: the project settings match with the installed JVM. You can now press Finish in this dialog window and OK in the properties dialog window.
Notice that the moment you pressed OK and the properties dialog windows disappears, the warning in the Problems tab disappears too, as depicted in figure 16.

Figure 16: No more warnings within the Java project.

You now have a Java project with Maven support that is ready to be set up with the JsaPar library. The next step is to actually include the JsaPar library so that you can start developing using this fine, small and easy to use library.

In order to use the JsaPar library within your Java project you have to tell the build manager Maven on what Maven dependencies your project depends. You specify this dependency of the JsaPar library within a specific Maven project file called the POM file. POM stands for "Project Object Model" and is actually an XML file with a certain structure so that the Maven build manager can process this type of file.

Tip: If you want to know more about the Maven POM file and all of its details, please consult the POM reference documentation here.  


Open the POM file in Eclipse by double clicking it or pressing function key F3 when the POM file is selected in the Package Explorer of Eclipse. You now see the following screen as depicted in figure 17.

Fig 17: The opened POM file.
As you can see, there are several tabs concerning this POM file that can be selected, like: Overview, Dependencies, Dependency Hierarchy, Effective POM and pom.xml. To specify another dependency select the Dependencies tab, as depicted in figure 18.

Fig 18: Maven dependencies in the POM file.

To add the JsaPar library to the POM file, you must know for sure that you meet the following conditions:
- you need to know the exact GroupId, ArtifactId and Version information of the dependency you want to include to your project POM file, and
- you need to be sure that the actual JAR file with these specific dependency settings is stored in a remote* Maven repository.

* Tip: it isn't always possible or necessary to have the JAR file be downloaded from a remote repository because, for example: due to legal restrictions, you cannot find these JAR files in public/remote Maven repositories. Therefore, you can also insert the JAR file locally into your own repository. More information about those situations and how to insert a JAR file into your local Maven repository can be read in the Maven documentation article 'Guide to installing 3rd party JARs' which can be found here.

To make sure that we end up with the correct Maven dependency settings for the JsaPar library and that the library can be downloaded from a public/remote Maven repositoy, we look up the JAR file we want using the general name of the JAR file. For the JsaPar library this is: jsapar. When searching for the general name jsapar, we find in the central Maven repository that the JAR file is available, as depicted in figure 19. You can search for this general name in the search engine of the central Maven repository located at: http://search.maven.org/ or you can search in another well known Maven repository search engine located at: http://mvnrepository.com/


Fig 19: Searching the Central Maven Repository for: jsapar
The the latest version of the JsaPar library JAR has the following Maven dependency settings:

GroupId: org.tigris.jsapar
ArtifactId: jsapar
Version: 1.6.2

Now press the Add... button within Eclipse to add another dependency to the POM file. You are prompted with a dialog window in which you can specifiy the dependency settings of the JsaPar library, as depicted in figure 20.

Fig 20: Adding the Jsapar dependency.
Press OK to close this dialog window. To complete the process of adding the JsaPar dependency you have to save the POM file. The moment you save the POM file, you will notice that in the lower right corner of Eclipse the text appears "Building workspace (50%)" and a percentage to indicate the progress of completion of the task, as depicted in figure 21. This means that the JsaPar library JAR is being downloaded from the central Maven repository to your own local Maven repository.

Fig 21: The JsaPar JAR is being downloaded from the central Maven repository.

You're ready setting up the JsaPar library to be used in your Eclipse project using the build manager Maven. You can now start reading the getting started article.

Note: if you are having difficulties setting up your JsaPar library to work with your own java code, please consult the troubleshooting section below for assistance in solving your problem.


Troubleshooting common setup problems

Some developers experience that they cannot reference the JsaPar library from their code in Eclipse after they have completed the setup steps described above. If this is also your situation, maybe the described steps below provides you with the solution of your problem. If the described steps below cannot solve your problem with the JsaPar library, please consult a colleague or find your specific solution at www.stackoverflow.com. The author of the JsaPar library (or some other person) will help you in answering all of your JsaPar related questions on that Q&A website.

Java Virtual Machine issues.
First of all make sure that you have installed the correct Java Virtual Machine on your system. There are versions for 32-bit and 64-bit operating systems. Although you cannot use 64-bit versions of the JVM on a 32-bit operating system, the opposite is possible!
When multiple JVMs are installed on your system, do you use the correct one for your development? Some programs need a different JVM than the latest JVM.  So be sure you check that your JVM is set as the default JVM you want to use. 
Do you use a Java Development Kit or Java Runtime Environment version of your installed JVM? There is also a difference in using a JDK or JRE version of the JVM, especially in the development process you sure want to use the JDK JVM. Make sure you are using a JRE version of the JVM for Eclipse itself and a JDK version of the JVM for development purposes!

Operating system issues.
Are the environment variables set correctly in your operating system?
For Java you need to set the following environment variables:
- JAVA_HOME
- CLASSPATH
- PATH
For Maven you need to set the following environment variables:
- M2_HOME
- MAVEN_OPTS (optional)
- PATH
For Eclipse you don't need to set any environment variables.

How to set the environment variables for Maven for your operating system is described in detail in the installation instructions on the download page of Maven, which can be found here.
How to set the PATH and CLASSPATH environment variable for your operating system is described in detail in the java tutorials, which can be found here


Eclipse/Development issues.
Compile target compliance level set to at least 1.5 in Eclipse.
Correct reference from your java code in the import statements? org.jsapar.*
Correct workspace selected?

Maven build manager issues.
Conf settings
JsaPAr library JAR in repository? (downloaded from remote to local maven repository)
Latest version of JsaPar JAR included in repository?
Dependency not set or not set correctly within maven POM file?

If the above mentioned clues didn't ring a bell to get you in the right direction of solving your problem(s), maybe some other issues might be of influence. Just search the website www.stackoverflow.com for answers to questions that might help solve your problem(s) too.