Building a Facets Application
In this module we get to grips with the fundamentals of actually building a simple program that makes use of the Facets class library to work with the repository and the objects in it. Since all Facets programs are Java programs, they need to be compiled exactly the same way any other Java program is compiled, with javac. Additionally the compiler that you use to compile the Facets program needs to be able to find the classes that Facets uses, this means that your compiler must be able to find the Facets jars in it's classpath.
Configuration for Development
Depending on how your development and deployment environments are set up there are a number of different ways in which you can develop the sample programs. If your development and deployment environment are on the same machine, deployment is simple, just copy the classes or jar files that you produce into the appropriate directory on your system and you are finished.
In the event that the development and deployment environments are on two or more different machines then deployment involves copying the jar or class files onto the deployment machines, and you must ensure that they are in the correct directories on those machines.
In some cases the development and deployment environments are not only on different machines, but also have different operating systems. This is not a problem at all, since Java is a write once, run (almost) anywhere language. This means you can potentially build your programs on one machine , test them on a second and deploy them on a third, all with different operating systems. Of course, the only caveat is that both Java and Facets must support the operating system that you wish to test and deploy your applications on.
Because a Facets program is just a standard Java program built against the Facets jar files, you can use any standard command line tool or IDE to build Facets programs. If you are using a command line java compiler invoked by either make or Ant, you only need to remember to define your classpaths correctly (either in the makefile or the Ant configuration file) for your build process to work as usual. In the event that you make use of an IDE you just need to add the required jar files to your project the same way you would add any other jar file that you require.
Classes for Building
When the Java compiler compiles your programs into Java byte code it is going to require access to the class libraries that ship with Facets . The compiler needs them to ensure that the methods you invoke on various objects do in fact exist and to check the signatures of these methods. In the "fill in the blank" directory of your Facets installation on you will find a large number of jar files. Not all of these jars are required when building a Facets program, since many of them are only needed by Facets itself. To build a Facets program, some of the following jars should be on your compilers classpath
- gsjadmin.jar
- gsjbaseapi.jar
- gsjconversion.jar
- gsjjdo096.jar
- gsjquery.jar
- gsjsecure.jar
- gsjserver.jar
- gsjserverorb.jar
- gsjtransport.jar
To compile a simple program for Facets you would probably require the following jars
- gsjjdo096.jar
- gsjserver.jar
- gsjbaseapi.jar
The list of jars shown above is the absolute minimum number required to build a basic Facets program. As your knowledge of Facets progresses you will find that your will start taking advantage of the many of useful classes contained in the Facets libraries, at that point, you may find that you will have to add additional jars to your compilers classpath. The list below indicates what jars contain which classes
| Jar Name | Contents |
| gsjadmin.jar | com.gemstone.persistence.admin.* com.gemstone.persistence.sysadmin.* com.gemstone.persistence.security.* |
| gsjbaseapi.jar | com.gemstone.persistence.admin.* com.gemstone.persistence.vm.* com.gemstone.persistence.statistic.* com.gemstone.persistence.naming.* |
| gsjconversion.jar | classes associated with the conversion of instances of classes |
| classes associated with the conversion of Facets from Version 2 to 3 | |
| classes associated with the conversion of Facets from Version 3 to 3 | |
| gsjjdo096.jar | javax.jdo.* |
| javax.transaction.* | |
| gsjquery.jar | com.gemstone.persistence.query.* |
| gsjsecure.jar | com.gemstone.persistence.security.* |
| gsjserver.jar | this jar contains the majority of the classes that are needed to build a standard Facets application |
| gsjserverorb.jar | contains the classes for the Facets implementation of the CORBA 2 standard |
| com.gemstone.persistence.CORBA.* | |
| com.gemstone.persistence.PortableServer.* | |
| org.omg.* | |
| gsjtransport.jar | contains various classes associated with remoting portions of Facets |
Building a small Facets Application
The file below contains a small Java program that connects to the default repository by retrieving the singleton SessionFactory, creating a session, storing an object and then exiting. You can also download either a makefile or an Ant file for building the program, although the classpath settings in either the makefile or the Ant file must be changed to point to the directory that contains your Facets jar files.
| Filename | Description | |
| FacetsSample1.java | Contains the source code for a small Facets Java program that connects to the default repository. |  |
| makefile | A traditional makefile that builds this program |  |
| build.ant | An Ant build file to build this program | |