Using Java with Caché Jalapeño
Using Jalapeño Tools
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

Jalapeño includes several tools for tasks such as connecting to the database, generating Caché schema, and creating test data. This chapter discusses how to call these tools from the command line or a script file. The following topics are covered:

Generating Caché Classes with SchemaBuilder
The Jalapeño SchemaBuilder is used to generate Caché classes from your Java source files.
Running SchemaBuilder from the Command Line
To start SchemaBuilder from the command line, use a command of the form:
   java -cp <cachejars> com.jalapeno.tools.SchemaBuilder -f <properties>
where
For example:
   set cachejars=C:/Intersystems/Cache/Dev/java/lib/JDK18
   java -cp .;"%cachejars%/cache-jdbc-2.0.0.jar";"%cachejars%/cache-db-2.0.0.jar"
      com.jalapeno.tools.SchemaBuilder
      -f C:/Dev/MyProject/MyProject.prop
Alternately, you can use the SchemaBuilder -fd switch, which does not take a filename as an argument. Instead, SchemaBuilder attempts to find a file in the current directory with the default name SchemaBuilder.properties. This default file must contain all required connection properties, including a valid password.
Defining SchemaBuilder Properties
SchemaBuilder properties define the parameters that determine how and where the Caché classes are generated. When SchemaBuilder is run from the command line, it reads these properties from a file in the standard java.util.Properties format.
SchemaBuilder properties are grouped into the following categories:
Note:
The properties file must contain all required connection information, including a valid password. If SchemaBuilder cannot find a valid properties file, it will not be able to open a connection to Caché, and will exit with the following error message:
[Cache JDBC] Communication link failure: Access Denied
The examples in the following sections use standard property file syntax, which requires all colons and backslashes to be escaped with a backslash. A backslash may also be used as a line continuation character. For example:
   com.intersys.schemabuilder.classes=\
      C\:/Dev/MyProject/bin/bank1/Account.class;\
      C\:/Dev/MyProject/bin/bank1/Customer.class
See the load() method in java.util.Properties for a detailed discussion of the Properties file format.
Connection Properties
These are the standard parameters required to connect to the Caché database. See the Connection Properties section of the SchemaBuilder Properties Reference for details about each property. Here is an example of how connection properties would be specified in a properties file:
The com.intersys.schemabuilder prefix is optional for connection properties.
Introspection properties
These are properties that determine the methods used to generate the Caché classes. See the SchemaBuilder Introspection Properties section of the SchemaBuilder Properties Reference for details about each property. Here is an example of how introspection properties would be specified in a properties file:
File properties
These properties specify the files that will be used when generating the Caché classes. See the SchemaBuilder File Properties section of the SchemaBuilder Properties Reference for details about each property. Here is an example of how file properties would be specified in a properties file:
Projection properties
These properties define settings for optional generation of projected Java classes. See the SchemaBuilder Projection Properties section of the SchemaBuilder Properties Reference for details about each property. Here is an example of how projection properties would be specified in a properties file:
Calling KillExtent from the Command Line
KillExtent is used to delete all instances of specified classes and their subclasses from the database. It can be called by specifying the classes to be deleted and the namespace where they are located. Standard connection parameters can be specified; otherwise, the default connection parameters are used. The class path must include paths for cache-db-2.0.0.jar and all of the class files to be deleted. For example:
java -cp <Path To class files>;<Path To cache-db-2.0.0.jar>
   com.jalapeno.tools.util.KillExtent
   -namespace Samples
   -class Sample.Employee
   -class Sample.Company
The following example explicitly specifies all five connection parameters:
java -cp <Path To class>;<Path To CacheDB>\cache-db-2.0.0.jar 
   com.jalapeno.tools.util.KillExtent 
   -host localhost
   -port 1972
   -namespace Samples 
   -user _SYSTEM
   -password SYS
   -class Sample.Employee
   -class Sample.Company
Also see Deleting Test Data for a description of the ObjectManager.extentManager.killExtent() method.
SchemaBuilder Properties Reference
This section provides a detailed description for each of the SchemaBuilder properties referred to in Generating Caché Schema with SchemaBuilder. Properties are divided into the following categories:
Connection Properties
Connection properties are the JDBC driver parameters used to connect to the Caché database. All of the tools discussed in this chapter use these properties.
The URL
The URL is a string constructed from a JDBC driver name plus the host, port, and user properties. It has the following format:
   <driver>//<host>[<port>]:<namespace>
For example, the sample programs in this book use the following connection string:
  jdbc:Cache://localhost:1972/USER
The cache-db-2.0.0.jar file contains the Caché version of the JDBC driver.
See Creating a Connection Object in Using Java with Caché for a programmatic example that uses the connection string.
host
The server TCP/IP address or Fully Qualified Domain Name (FQDN). The sample programs use "localhost" (127.0.0.1), assuming that both the server and the application are on the same machine.
port
The TCP/IP superserver port number for this connection. Together, the IP address and the port specify a unique Caché server. Your Caché superserver port number is set in the Management Portal under [System Administration] > [Configuration] > [System Configuration] > [Memory and Startup].
namespace
The Caché namespace containing the objects to be used. This namespace must have the Caché system classes compiled, and must contain the objects you want to manipulate. The sample programs use objects from the SAMPLE namespace.
user
The username under which the connection is being made. The sample programs use "_SYSTEM", the default SQL System Manager username.
password
The password associated with the specified username. Sample programs use the default, "SYS".
logfile
Optional. Specifies the name of a JDBC log file to be written when the application attempts to make a connection.
SchemaBuilder Introspection Properties
These properties determine the methods used to generate the Caché classes.
metadata
Specifies the ORM (Object/Relational Mapping) metadata notation to be used in the Java source classes. Possible values are:
The default value is default.
defaultaccesslevel
Specifies the minimum access level that a property must have in order to be included in the generated Caché class. For example, if the required access level is protected, then Private properties will not be included. Possible values are:
The default value is protected.
Also see Limiting Persisted Properties by Access Level in the Using Annotations chapter.
defaultaccesstype
Specifies the least restrictive access type that a property must have in order to be included in the generated Caché class. For example, if the required access type is properties, then only properties that have both get and set accessors will be included. Possible values are:
The default value is properties.
Also see Limiting Persisted Properties by Access Type in the Using Annotations chapter.
exclude
An optional comma-separated list of packages that should be excluded when generating Caché classes. This is the equivalent of applying @Transient to all classes in the specified packages (see Preventing a Class or Property from being Persisted in the Using Annotations chapter.
merge
If this property is true, SchemaBuilder will attempt to merge the generated classes with any pre-existing versions of the same classes in Caché. If this property is false, the previous classes will be deleted when the new ones are generated.
Valid values are true or false. The default value is false.
SchemaBuilder File Properties
These properties specify the files that will be used when generating the Caché classes.
classpath
Specifies the parent directory of directories containing *.class source files to be used.
source
Specifies whether your Java source classes are stored as standard *.class files, or are compressed into *.jar or *.zip files. Valid options are:
The default value is jars.
classes
Specifies a list of the source files that will be used to generate Caché classes. The list can contain either compressed (*.jar and *.zip) files or *.class files, but not both. If the list contains multiple items, they must be separated by semicolons.
SchemaBuilder Projection Properties
These properties specify settings for optional generation of projected Java classes.
defaultjavaprojectionpackage
Projected Java classes will be placed in a package with the name specified by this property.
generationtype
A set of flags that determine which types of projection file will be produced.
Possible flags are:
For example, a value of 10 would indicate that both Interface and POJO (2+8) files should be generated. The default value is "0" (no projection files are generated).
projectiondir
Specifies the base directory that will contain the projected Java files. A subdirectory with the same name as the package will be created within the projection directory. Interface and POJO projections will be placed directly in <projectiondir>\<packagename>. Native projections will be placed in <projectiondir>\<packagename>\cache.