![]() |
Deploying Cloudscape Applications
|
Reference Manual |
Loading Classes from a DatabaseYou can store application logic in a database and then load classes from the database. Application logic, which can be used by both Cloudscape (for database-side methods and stored objects) and your application, includes Java class files and other resources. Storing application code simplifies application deployment, since it reduces the potential for problems with a user's class path. In an embedded environment, when application logic is stored in the database, both the user application and Cloudscape can access classes loaded by the Cloudscape class loader from stored jar files. NOTE: You can publish stored classes in a synchronized system. For more information about publishing stored classes, see the Cloudscape Synchronization Guide. Class Loading OverviewYou store application classes and resources by storing one or more jar files in the database. Then your application can access classes loaded by Cloudscape from the jar file and does not need to be coded in a particular way. The only difference is the way in which you invoke the application. Here are the basic steps:
NOTE: If you are interested in making changes to jar files stored in the database or changing the database jar "class path" of your application without having to re-boot, read Dynamic Changes to Jar Files or Database Jar Class Path. Signed Jar FilesFor information about how Cloudscape handles signed jar files, see Signed Jar Files Create Jar Files for Your ApplicationInclude any Java classes in a jar file intended for Cloudscape class loading except:
A running Cloudscape system can load classes from any number of jar files from any number of schemas and databases. Create jar files intended for Cloudscape database class loading the same way you create a jar file for inclusion in a user's class path. For example: jar cf tours.jar JBMSTours\*.class Various IDEs have tools to generate a list of contents for a jar file based on your application. If your application requires classes from other jar files, you have a choice:
Include the class files and resources needed for your application. Choose Between Database-Level and System-Level Class Loading
Add the Jar File or Files to the DatabaseUse the COM.cloudscape.tools.dbclasses utility (aliased as dbclasses) to add, update, and remove jar files in a database. When you add a jar file to a database, you give it a Cloudscape jar name, which is an SQL92Identifier. See the Cloudscape Tools and Utilities Guide for reference information about the utility. NOTE: Once a jar file has been stored, you cannot modify any of the individual classes or resources within the jar file. Instead, you must replace the entire jar file. NOTE: Adding, removing, or replacing a jar file invalidates all stored prepared statements in the database. You can use the utility on the command line or within an SQL-J statement. On the command line, you delimit the Cloudscape jar name with the schema name if it is not the default (APP). Within an SQL-J statement, you supply the schema name as a parameter to the method separately. ExamplesSee the Cloudscape Tools and Utilities Guide for reference information about the utility and complete syntax. Adding Jar Files
-- SQL-J statement
-- SQL-J statement -- from the command line
-- SQL-J statement Removing Jar Files
-- SQL-J statement -- from the command line Replacing Jar Files
-- SQL-J statement -- from the command line Enable Database Class Loading with a PropertyOnce you have added one or more jar files to a database, you must set the database jar "class path" by including the jar file or files in the cloudscape.database.classpath property to enable Cloudscape to load classes from the jar files. This property, which behaves like a class path, specifies the jar files to be searched for classes and resources and the order in which they are searched. If Cloudscape does not find a needed class stored in the database, it can retrieve the class from the user's class path. (Cloudscape first looks in the user's class path before looking in the database.) Separate jar files with a colon (:).
See cloudscape.database.classpath in Tuning Cloudscape for more information about the property. NOTE: Cloudscape's class loader looks first in the user's class path for any needed classes, and then in the database. To ensure class loading with the database class loader, remove classes from the class path. Force Cloudscape Class Loading for the ApplicationTypically, in an embedded environment, you want both Cloudscape and the application to use classes loaded by the same class loader. However, you can choose to have only Cloudscape use classes loaded by the Cloudscape class loader, and have your application use those classes loaded by the JVM class loader from the class path. To choose this option, you must understand the implications of using different class loaders for each. Remember Figure 3-5? It showed how both Cloudscape and the application use the same classes (those loaded by the JVM from the class path). Because they use the same classes, they can pass entire objects back and forth. When they use different class loaders, they use different classes, and therefore cannot pass entire objects back and forth. Class Loading: Database-Side Only vs. Database- and Application-SideYou can do one of the following things:
NOTE: You can choose this option in a client/server scenario; however, the same limitations apply as in an embedded environment (described above).
NOTE: You cannot choose this option in a client/server scenario. Enabling Cloudscape Class Loading for Database-Side Logic ExecutionEnabling Cloudscape loading for execution of database-side logic means that Cloudscape uses classes loaded by Cloudscape retrieved from stored jar files. You automatically enable class loading for database-side logic execution by setting the cloudscape.database.classpath property (see Enable Database Class Loading with a Property). Class Path Class Loading for Application-Side Logic ExecutionCloudscape does not automatically load classes from the database for use by the application. When Cloudscape does not load classes for use by the application, the client application uses classes loaded by the JVM from the user's class path, not those loaded by the Cloudscape class loader. This leads to potential ClassCastExceptions. If two different class loaders (in this case, the one used by Cloudscape and the one used by the class path class loader) load the same class, the JVM does not recognize them as the same class and will throw a ClassCastException if the application and Cloudscape attempt to pass entire objects back and forth. Figure 3-11 Application-side logic loaded from the class path, database-side logic loaded from the database. If the application retrieves objects from Cloudscape or stores objects in the database, a ClassCastException results. Allowing two different class loaders is acceptable when the application does not retrieve entire objects from, or store entire objects in, the database. That is, it does not use the setObject and getObject methods of JDBC to send or retrieve user-defined Java data types from the database. The application can work with objects in a Cloudscape database only as follows:
The following is an excerpt from an application that will generate a ClassCastException if embedded Cloudscape uses Cloudscape class loading but the application uses class path class loading, even if the copy of the class in the class path is identical to the one stored in the database: ResultSet rs = s.executeQuery( "SELECT City FROM Cities WHERE city_id = 1"); while (rs.next()) { mycity = (JBMSTours.City) rs.getObject(1); In a client/server environment, no error is generated if both the application and Cloudscape are using the same versions of the classes, because the object is serialized and re-created at the client with the application class. Cloudscape Class Loading for Client-Side Logic ExecutionIn situations in which class path loading for client-side logic execution is not appropriate, enable Cloudscape class loading for the client application. Doing so ensures that all classes are loaded by the same class loader. Figure 3-12 Both the application and Cloudscape loading classes from the database Cloudscape provides an application bootstrap program that forces Cloudscape class loading for application-side logic. The program is called COM.cloudscape.util.DBClassLoad. Typically, you would invoke your class like this: java COM.cloudscape.util.DBClassLoad databaseConnectionURL databaseConnectionURL refers to the database in which the classes are stored. In cases when user authentication is turned on and you are using database-level class loading, you will probably not want to put the user name and password on the command line in the database connection URL. In that case, you can invoke the class like this:
For more information, see the javadoc for COM.cloudscape.util.DBClassLoad. Code Your Applications the Way You Normally WouldIn your applications, you cause classes to be loaded the way you normally would: In your applications, you load resources the way you normally would, using the standard java.lang.Class.getResourceAsStream, a mechanism that allows an application to access resources defined in the class path without knowing where or how they are stored. You do not need to make any changes to the way code interacts with Cloudscape and its JDBC driver. An application can safely attempt to boot Cloudscape, even though it is already running, without any errors. Applications connect to Cloudscape in the usual manner. NOTE: The method getResource is not supported. Dynamic Changes to Jar Files or Database Jar Class PathIn some situations, you can see changes to a class dynamically. That is, when you add or replace a jar file within an SQL-J statement or change the database jar "class path" (the cloudscape.database.classpath property), Cloudscape is able to load the new classes right away without your having to reboot. RequirementsCertain conditions must be met for this to be true:
If these requirements are not met, you will have to reboot to see the changes. NotesWhen you are changing the cloudscape.database.classpath property, all classes loaded from database jar files are reloaded, even for a jar file that hasn't changed. Remember that the user's class path is searched first. Any existing prepared statements will use the previously loaded classes unless they require class loading, in which case they will fail with a ClassNotFound error. Cached objects do not match objects created with newly loaded classes. For example, an in-memory Customer object will not match a new Customer object if the Customer class has been reloaded, and it will raise a ClassCastException. The issues are the same as those discussed in Class Path Class Loading for Application-Side Logic Execution. |
|
![]() Cloudscape Version 3.6 For information about Cloudscape technical support, go to: www.cloudscape.com/support/.Copyright © 1998, 1999, 2000 Informix Software, Inc. All rights reserved. |