There are three main ways to obtain the OpenShift Java Client library for use in your applications.
If you are not using an Apache Maven based project, or not familiar with building Maven Based projects from source, the easiest way to use this library would be to download the pre-compiled JAR file.
To do this you can visit the Maven Central Repository and do a search for "openshift-java-client", or you can click this link and then look for the version that you are interested in using and click on the "jar" link under the Download header on the right side of the page.
Next you will need to add the JAR file that you have downloaded to your project. This can be accomplished by placing the JAR file in the appropriate folder within your application, and then adding it as a dependency within your IDE.
In Eclipse this can be accomplished by going to Project Properties->Libraries->Add Jar, and then selecting the JAR file that you downloaded previously and placed within your project structure. Make sure that you select the correct options when you compile your project so that the JAR file will be bundled as a dependency within your application.
If you are using a Maven based project, the easiest way to use this library in your application is to add it as a dependency in your pom.xml file.
To do this, you need to visit the Maven Central Repository and pick which version you want to use from this page. Once you have chosen a version, click on the version number that is displayed under the "Latest Version" heading.
On the left side of the page, under "Dependency Information" you will see a box with the heading of "Apache Maven". You will need to copy the xml that is provided in that box and add it into the dependencies section of your pom.xml file. Sample XML code is provided below for the 2.5.0.Final version.
<dependencies>
<dependency>
<groupId>com.openshift</groupId>
<artifactId>openshift-java-client</artifactId>
<version>2.5.0.Final</version>
</dependency>
</dependencies>
Once you have added the dependency you can build your project and the OpenShift Java Client will be downloaded and installed.
The last and most exciting way to get the OpenShift Java Client library is to download the source code and build it yourself. While adding it to your pom.xml file is the easiest and best way if you are using a Maven based project, building it yourself will give you a certain level of satisfaction and accomplishment.
First, make sure that you have Apache Maven installed by visiting the download page. We recommend using the newest stable version that is available. If you are using OS X you can use Macports or Homebrew to install it, or if you are using Linux use your included package manager such as YUM, APT.
The next step is to get the code. The best way to get it would be to fork the repository on github and then clone it to your workstation. Please see the Join Us section of the website for help updating your local working copy with upstream changes. Alternatively you can also download a zip file from github.
Once you have Maven installed and the source code downloaded you will need to open up a terminal and cd (change directory) to the location in which the source code resides. You will then need to type the command mvn clean package. This will clean the project (if you have issued the command before and have leftovers) and then build the project, including downloading any dependencies that are defined in the pom.xml file.
Maven will also run a few unit-tests to make sure that everything works after building the project. This is a basic set of functional tests and should not take very long to complete. Once it is finished you should have a new directory called target. If you cd (change directory) into the new target directory and run ls -lah you will see something similar to the below files:
total 680 drwxr-xr-x 10 user staff 340B Jan 28 23:02 . drwxr-xr-x 10 user staff 340B Jan 28 23:01 .. drwxr-xr-x 4 user staff 136B Jan 28 23:01 classes drwxr-xr-x 4 user staff 136B Jan 28 23:01 generated-sources drwxr-xr-x 3 user staff 102B Jan 28 23:02 maven-archiver -rw-r--r-- 1 user staff 134K Jan 28 23:02 openshift-java-client-2.5.0.Final-sources.jar -rw-r--r-- 1 user staff 204K Jan 28 23:02 openshift-java-client-2.5.0.Final.jar drwxr-xr-x 2 user staff 68B Jan 28 23:02 surefire drwxr-xr-x 4 user staff 136B Jan 28 23:02 surefire-reports drwxr-xr-x 6 user staff 204B Jan 28 23:01 test-classe
The file with the .jar extension, that is not -sources.jar is the one that you want to use. The version will be whatever the version of code that you downloaded or checked out is, and is defined in the pom.xml file of the project in the "Artifact Information" section as seen below:
<!-- Artifact Information --> <groupId>com.openshift</groupId> <artifactId>openshift-java-client</artifactId> <version>2.5.0.Final</version> <packaging>jar</packaging> <name>OpenShift Java Client</name> <url>http://openshift.redhat.com</url> <description>OpenShift Java Client</description>
Lastly you will need to add the JAR file that you have downloaded to your project. This can be accomplished by viewing your projects properties in your favorite IDE and adding this file as a dependency, or sometimes by placing it in a "libs" directory inside of your project.
If you would like to run the full integration tests you can run the command mvn clean verify -Pintegration-tests, it will take quite awhile so be patient, but remember that it is not required to build and use the library. It is covered more in the Join Us section of this website.
The last and most exciting way to get the OpenShift Java Client library is to download the source code and build it yourself. While adding it to your pom.xml file is the easiest and best way if you are using a Maven based project, building it yourself will give you a certain level of satisfaction and accomplishment.
First, make sure that you have Apache Maven installed by visiting the download page. We recommend using the newest stable version that is available. If you are using OS X you can use Macports or Homebrew to install it, or if you are using Linux use your included package manager such as YUM, APT.
The next step is to get the code. The best way to get it would be to fork the repository on github and then clone it to your workstation. Please see the Join Us section of the website for help updating your local working copy with upstream changes. Alternatively you can also download a zip file from github.
Once you have Maven installed and the source code downloaded you will need to open up a terminal and cd (change directory) to the location in which the source code and the pom.xml resides. You will then need to type the command mvn clean install. This will clean the project, build the project, including downloading any dependencies that are defined in the pom.xml file, and then install it into your local Maven repository usually located at ~/.m2.
Once the package is installed, you can use it by inserting the following dependency in your projects pom.xml file.
<dependencies>
<dependency>
<groupId>com.openshift</groupId>
<artifactId>openshift-java-client</artifactId>
<version>2.5.0.Final</version>
</dependency>
</dependencies>
Where 2.5.0 is the version that was built and installed. If you make any changes to the source code you should increment the minor or major version, depending on the depth of the change that you have made. It is also a Maven convention to use version-SNAPSHOT for any non-finalized version of the library. So the dependency you add in your local project's pom.xml file when testing updated version of the library may look more like this:
<dependencies>
<dependency>
<groupId>com.openshift</groupId>
<artifactId>openshift-java-client</artifactId>
<version>2.5.1-SNAPSHOT</version>
</dependency>
</dependencies>
Maven will also run a few unit-tests to make sure that everything works after building the project. This is a basic set of functional tests and should not take very long to complete. Once it is finished you should have the library installed in your ~/.m2 directory as stated above.
If you would like to run the full integration tests you can run the command mvn clean verify -Pintegration-tests, it will take quite awhile so be patient, but remember that it is not required to build and use the library. It is covered more in the Join Us section of this website.