CHAPTER ELEVEN Database Connectivity (JDBC) y y y y

Database client/server methodology Java s JDBC APL JDBC s drivers The JDBC-ODBC bridge

In the information age, the database is a tool used to collect and manipulate data. While the database system is well-suited to the storage and retrieval of data, human beings need some sort of front end application in order to see and use the data stored. In developing database front-end applications, programmers face the challenge of the heterogeneous nature of the computers in most companies. For example, you may find that the art and marketing departments have Macintosh systems, the engineers have high-end Unix workstations, and the sales department people are using PCs. This chapter will look at Java as the way to solve the Tower of Babel of database front ends by providing a single and consistent application programming interface: the Java Database Connectovotu (JDBC) API. First, we will briefly review database models, and then we will examine how to use the JDBC API to connect Java applications andapplects to database servers. RDBMS Models In a relational database management system (RDBMS), data is stored as rows of distinct information in tables. A structured language (Structured Query Language, or SQL) is used to query (retrieve), store, and change the

data. SQL is an ANSI standard, and all major commercial RDBMS vendors provide mechanisms for issuing SQ: commands. NOTE The evolution of relational data storage began in 1970 with the work of Dr. E.F.Cdd. Codd s rules for relational modeling of data formed the basis for the development of systems to manage data. Today, RDBMSs are the result of Codd s vision. Single-Tier Database Design The early RDBMS applications were developed based on an integrated model of user interace code, application code, and database libraries. This single binary model ran only on a local machine, typically a mainframe. Figure 11.1 illustrates the monolithic single-tier database design. Multitier Database Design In a multitier design, the client communicates with an intermediate server that provides a layer of abstraction from the RDBMS. Figure 11.3 illustrates a three-tier database design. The intermediate layer is designed to handle multiple client requests and manage the connection to one or more database servers. The intermediate-tier design provides several advantages over the two-tier design. The middle tier has the following characteristics: y It is multithreaded to manage multiple client connections simultaneously. y This tier can accept connections from multiple client connections simultaneously. y This tier can accept connections from clients on a varity of vendorneutral protocols (from HTTP to TCP/IP), then marshal the requests to the appropriate clients. y Developers can program the middle tier with a set of business rules that manage the manipulation of the data. Business rules might include any. Thing from restricting access to certain portions of data

to making sure that data is properly formatted before being inserted or updated. The tier prevents the client from becoming too heavy by centralizing process intensive tasks and abstracting data representation to a higher level. Having the tier in the middle isolates the client application from the database system and frees a company to switch database systems without needing to rework the business rules. The tier can asynchronously provide the client with the status of a current data table or row. For example, suppose that a client application had just completed a query of a particular table. If a subsequent action by another distinct client changed that data, the first client could receive notification from an intelligent middle-tier program. The tier can provide significant security benefits by handing the real database behind a gateway system.

The JDBC API Java offers several benefits to the developer creating a front-end application for a database server. Just having a common development platform is a big advantage, because programmers are no longer required to write to the many platforms a large corporation may have. Also, a single Java program can satisfy the requirements of a large corporate customer. In addition, there is a cost associated with the deployment and maintenance of the hardware and software of any system (client) the corporation owns. Microsoft Windows, Macintosh, and Unix desktopclients (fat clients) can cost corporations between $10,000 and $15,000 per installation seat. Java technology makes it possible to use a smaller system footprint. These systems are based on a Java chip set and can run any and all Java programs from a built-in Java technology makes it possible to use a smaller system footprint. These systems are based on a

java chip set and can run any and all Java program from a built-in Java operating system. Java-based clients (thing clients) that operate with a minimum of hard resources and yet run the complete Java environment can cost less than $2,500 per seat. According to various studies, the savings for a corporation moving 10,000 fat client systems to thin clients could be a much as $100 million annually. For the developer, Java-based database applications and applets represent a huge market opportunity. Most medium-sized to large organization use databases for some portion of their business operations; many use databases for every aspect of their business, from human resources to front-line customer sales.

The JDBC API is designed to allow developers to create database front ends without needing to continually rewrite their code. Despite standards set by the ANSI committee, each database system vendor has a unique way of connecting to its system. Features of the JDBC API The JDBC API was first introduced with release 1.1 of the JDK. JDBC provides application developers with a single API that is uniform and database independent. The API provides a standard to write to, as well as a standard that takes all of the various application designs into account. The API s database independence is due to a set of Java interfaces that are implemented by a driver. The driver takes care of translating the standard JDBC calls into the specific calls required by the database it supports. The application is written once and moved to the various drivers. The application remains the same; the drivers change. Drivers may used to develop the middle tier of a multitier database design, as illustrated in Figure 11.4.

The connection, Statement, and ResultSet interfaces are implemented by the driver vendor, but these interfaces specify the methods that the application developer can use. They allow the developer to create statements and retrieve results without having to think about where the objects are coming from or worry about what specific driver the application will use. The following sections descuss the Driver and Application layers in more detail. The Driver Layer Driver is an interface. Each vendor supplies a class that implements this interface. The other important class is the DriverManager Class, which sits above the Driver and Application layers. The Driver Manager class is responsible for loading and unloading drivers and making connections through drivers. The Driver Manager class also provides features for logging and database loging timeouts. The Driver Interface Every JDBC application must have at least one JDBC driver implementation. The Driver interface allows the DriverManager and JDBC Application layers to exist independentity of the particular database used. A JDBC driver is an implementation of the dDriver interface class. Drivers use a string to locate and access databases. The syntax of this string is similar to a URL string and is referred to as a URL. The purpose of a JDBC URl string is to separate the application developer from the driver developer. JavaSoft defines the following goals for driver URLs: y The name of the driver-access URL should devine the type of database being used. y The user (application developer should be free from any of the administration of creating the database connection. Therefore,

any database connection information (host, port, database name, user access, and passwords) should be encoded in the URL. y A network naming system may be used so that the user does not need to specifically encode the exact hostname and port number of the database.

The URL syntax used by the World Wide Web supports a standard syntax that satisfies these goals. JDBC URLs have the following systax and structure: Jdbc:<subprotocol>:<subname> Where <subprotocol> defines the type of driver, and <subname> provides the network encoded name, as in: Jdbc:oracle:products In this example, the database driver is an Oracle driver and the subname is a local database called products. This driver is designed to know how to use the subname when making the connection to the Oracle database. A network naming service may also be specified as the subprotocol, rather than using a specific database driver name. In this case, the subprotocol would define the naming service: Jdbc: localnaming:human-resources In this example, the subprotocol defines a local service that can resolve the subname human-resources to a database server. This approach can be very useful when the application developer wants to isolate the user from the actual location, name, database username, and database password. This URL specifies a driver named local naming; this could be a Java program that contains a simple flat-file lookup, translates human-resources into hrdatabase1.eng:888/personne1, and knows to use the username

user and password matilda. The details of the connection are kept hidden from the user. Typically, the application developer will know specifically where the database is located and may not wish to use network indirection to locate the database. In this case, the URL may be expanded to include the location of the host and specific port and database information: Jdbc:msgl://dbserver.eng:1112g/bugreports In this example, and msql database driver type is used to locate a server named dbserver in the eng domain and attempt to connect to a database server on port 1112 that contains a bugreports database, using the default username and password to connect. NOTE Subprotocol names will eventually overlap, and there will need to be a registry of reserved names. For mor information about registering a JDBC subprotocol name, consult the JDBC subprotocol name, consult the JDBC Spectification.

The Driver interface specifies several methods. From a practical programming point of view, the two most important methods look like this: Public Connection connect (String url, properties info) throws SQLException Checks the subprotocol name of the URL string passed for a match with this driver. If there is a match, the driver should then attempt to make a connection to the database using the information passed in the remainder of the URL. A successful database connection will return an instance of the driver s implementation of a Connection interface. The SQLException should be thrown only if the driver recognizes the

URL subprotocol but cannot make the database connection. Anull is returned if thenURL does not match a URL the driver expected. The username and password are included in a instance of the Properties container class. Public Boolean acceptsURL (String url) throws SQLException Explicitly asks the driver if the URL is valid. Note that, typically, the implementation of this method checks only the subprotocol specifies in the URL, not whether the connection can be made. Both of these methods throw SQLException if there is trouble with the remote database. The Driver connect( ) method is the most important method, and is called by DriverManager to obtain a Connection object. The Connection object is the starting point of the JDBC Application layer (see Figure 11.5, shown earlier). The Connection object is used to create Statement objects that peform queries. The Driver Connect () method typically performs the following steps: y y y y Checks to see if the given URL string is valid. Opens a TCP connection to the host and port number specified. Attempts to access the named database table (if any). Returns an instance of a Connection.

The DriverManager Class The DriverManager class is actually a utility class used to manage JDBC drivers. The class provides methods to obtain a connection through a driver, register and deregister drivers, set up logging, and set login timeouts for database access. The important DriverManager methods are listed below. Since they ae static, they may be referenced through the interface. SQLException is thrown if there is trouble with the remote databased.

Public static synchromized Connection get Connection (String url, properties info) throws SQLException Attempts to return a reference to an object implemented from the connection interface. The method sweeps through a vector of stored Driver classes, passing the URL string and properties object info to each in turn. The first Driver class that returns a Connection is used. Info is a reference to a reference to a properties container object of tag/value pairs, typically username/password. This method allows several attempts to make an authorized connection for each dreiver in the vector. Public static synchronized Connection getConnection (String url) throws SQLException Calls get Connection (url, info) with an empty Properties object (info). Public static synchronized Connecton getConnection (String url, String user, String password) throws SQLException Creates a Properties objects (info), stores the user and passwork strings into it, and then calls get Connection (url, info). Public static synchronized void registerDriver (java.sql.Driver driver).throws SQLException Stores the instance of the Driver interface implementation into a vector of drivers, along with an instance of security Context, that identifies where the driver came from. Public static void setlog writer (java.io.printWriter out) Sets a private static java. Io. PrintWriter reference to the Print Writer object passed to the method.

TIP The driver implemention can make use of two static object references that are stored through set Type methods and accessed by the driver through get type methods: and integer that specifies login timeout and a PrintStream object used to log driver information.

Drivers are registered with the DriverManager class, either at initialization of the DriverManager class or when an instance of the driver is created. When the Driver Manager clas is loaded, a section code (in the class) is run, and the class names of drivers listed in a Java property named jdbc. Drivers are loaded. This property can be used to define a list of colon-separated driver class names, such as: Jdbc.drivers=imaginary.sql.Driver:oracle.sql.Driver:weblogic.sql.Driver Each driver name is a class name (including the package declaration) that the DriverManager will attempt to load, and link the named class: Class. For Name(driver); If the jdbc. Drivers property is empty (unspecified), then the application programmer must create an instance of a Driver class. In both cases, the Driver class implementation must explicity register itself with the DriverManager by calling: DriverManager. registerDreiver (this); Here is a sgment of code from the imaginary Driver (for the Mini-SQL database). The Driver registers itself whenever an instance of the imaginary driver is created:

Public class iMsqlDriver implements java.sql.Driver { Static { Try

{ New iMsqlDriver( ); } Catch (SQLException e) { e.printStackTrace( ); } /** y y y y Constructs a new driver and registers it with Java.sql. DriverManager. registerDriver ( ) as specified by the JDBC protocol. /

Public iMsqlDriver( )throws SQLException { Java.sql.DriverManager.registerDriver(this); }

The primary use of Driver Manager is to get a Connection object referencthrough the Connection () method: Connection conn=unll; Conn = DriverManager. Get Connection ( jdbc:Sybase://dbserver;8080/billing , dbuser, dbpasswd); This method goes through the list of registered drivers and passes the URL string and parameters to each driver in turn through the driver s connect ( ) method. If the driver supports the subprotocol and subname information, a Connection object reference is returned.

The DriverManager class is not required to create JDBC applications; it is possible to get a Connection object directly from the driver. For example, if a driver class name is XxxDriver, then the code below can be used can be used to get a connection from the driver: Connection conn; Conn = new XxxDriver( ). Connect(*jdbc:Sybase://dbserver:8080/billing*, props); However, this means of obtaining a connection is not as clean, and leaves the application developer dependent on the Driver implementation class to provide security checks. Also, the driver class is now hardcoded into the software, so the advantages of JDBC s vendor independence are lost.

The Application Layer The Application layer encompasses three interfaces that implemented at the Driver layer but are used by the application developer. In Java, the interface defines methods that must be implemented by the specific classes. For the application developer, this means that the specific Driver class implementation is irrelevant; simply coding to the standard JDBC APIs will be sufficient. (Of course, this is assuming that the driver is JDBCcompliant, which means that the database is at least ANSI SQL-2 Entry Level.) The three main interfaces are connection, statement, and ResultSet. A Connection object is obtained from the driver implementation through the DriverManager.get Connection () method call. Once a connection object is returned, the application developer may create a Statement object to issue SQL against the database. If the SQL that was submitted was a SELECT query, then the result set is rturned in a ResultSet object.

The Connection Interface The Connection interface representsa session with the database connection provided by the Driver. Typical database connections include the ability to control changes made to the actual data stored through transactions. On creation, JDBC connections are in an auto-commit modethere is no rollback possible. So after getting a connection object from the driver, the developer should consider setting auto-commit to false with the set AutoCommit (Boolean b) method. When auto-commit is disabled, the Connection will support both Connect ion. Commit ( ) and Connection. Rollback ( ) method calls. The level of support for transaction isolation depends on the underlying support for transactions in the database. NOTE A transaction is a set of operations that are completed in order. A commit action makes the operations store (or change) data in the database. A rollback action undoes the previous transaction before it has been committed. A portion of the Connection interface definition follows. As usual, SQLException is thrown in case of trouble with the remote database. Statement createStatement () throws SQLException The Connection object implementation will return an instance of an implementation of a Statement object. The Statement object is then used to ussue queries. PreparedStatement prepareStatement (String sql) throws SQLException The Connection object implementation will return as instance of a PreparedStatement object that is configured with the sql string passesd. The driver may then send the statement to the database, if the database (driver ) handles precompiled statements. Otherwise, the driver may wait until the PreparedStatement is executed by an execue method. CallableStatement prepareCall (String sql) throws SQLException The Connection object implementation will return an instance of a Callable

Statement. CallableStatements are optimized for handling stored procedures. The driver implementation may send the sql string immediately when prepareCall ( ) is complete or may wait until an execute method occurs. Void setAutoCommit (Boolean autoCommit) throws SQLException Sets a flag in the driver implementation that enables commit/rollback (falsed) or makes all transactions commit immediately (true). Void commit ( ) throws SQLException Makes all changes made since the beginning of the current transaction (either since the opening of the Connection or since the last commit ( ) or rollback ( ) ). Void rollback ( ) throws SQLException Drops all changes made since the beginning of the current transaction. The primary use of the Connection interface is to create a statement: Connection conn; Statement stmt; Conn = DriverManager. getConnection (url); Stmt = C. createStatement ( ); Conn = DriverManager. Get Connection (url); Stmt = c. createStatement ( ); This statement may be used to send SQL statements that return a single result set in a ResultSet object reference. Statements that need to be called a number of times with slight variations may be executed more efficiently using a PreparedStatement. The Connection interface is also used to create a callableStatement whose purpose is to execute stored procedures. Most of the time, the developer knows the database schema beforehand and creates the application based on the schema. However, JDBC provides an interface that may be used to dynamically determine the schema of a

database. The Connection interface getMeta Data ( ) method will return a DatabaseMetaData object. The instance of the class that implements the interface provides information about the database as a whole, including access information about tables and procedures, column names, data types, and so on. The implementation details of DatabaseMetaData are dependent on the database vendor s ability to return this type of information. The Statement Interface A statement is the vehicle for sending SQL queries to the database and retrieving a set of results. Statements can be SQL updates, inserts, deletes, or queries; statements may also create or drop tables. The Statement interface provides a number of methods designed to ease the job of writing queries to the database. The important Statement methods are listed below. As usual, SQLException is thrown if there is a problem with the remote database. ResultSet executequery (String sql) throws SQL Exception Executes a single SQL query and return the results in an object of type ResultSet. Int Executeupdate (String sql) throws SQL Exception Executes a single SQL query that returns a count of rows affected rather than a set of results. Boolean execute (String sql) throws SQLException A general way to execute SQL statements that may return multiple result sets and/or update counts. This method is also used to execute stored procedures that return out and inout parameters. The getResultSet ( ), get UpdateCount ( ), and getMoreResults () methods are used to retrieve the data returned. (This method is less likely to be used than executeUpdate ( ) and executeQuery().) NOTE The in paratameters are parameters that are passed into an operation. The out parameters ae parameters passed by reference; they are expected to return a result of the reference type. The inout parameters are out

parameters that contain an initial value that may change as a result of the operation. JDBC supports all three parameter types.

ResultSet getResultSet ( ) throws SQL Exception Returns the result of a statement execution as a ResultSet object. Note that if there are no results to be read or if the result is an update count, this method returns null. Also note that once read, the results are cleared. Int getUpdateCount ( ) throws SQLException Returns the status of an Update, an Insert, or a Delete query; a stored procedure; or a DDL statement. The value returned is the number of rows affected. A 1 is returned if there is no update count or if the data returned is a result set. Once read, the update count is cleared. Boolean getMoreResults ( ) throws SQL Exception Moves to the next result in a set of multiple results/update counts. This method returns true if the next result is a ResultSet object. This method will also close any previous ResultSet read. Statement methods may or may not return a ResultSet object, depending on the Statement method used. The executeUpdate( ) method, for example, is used to execute SQL statements that do not expect a result (except a row count status): Int rowCount; rowCount = stmt. executeUpdate C DELETE FROM Customer WHERE Customer ID = McG10233 ); SQL statements that return a single set of results can use the executeQuery ( ) method. This method returns a single ResultSet object. The object represents the row information returned as a result of the query: ResultSet results; Results = stmt. executeQuery ( SELECT * FROM Stock );

SQL statements that execute stored procdures (or trigger a stored procedure) may return more than one set of results. The execute ( ) method is a genera-purpose method that can return either a single result set or multiple result sets. The method returns a Boolean flag that is used to determine wheather there are more result sets. Because a result set could contain either data or the count of an operation that returns a row count, the getResultSet ( ), getMoreResults ( ), and getUpdateCount() methods are used. Here is an example: // Assume SQLString returns multiple result sets // returns true if a ResultSet is returned Int count; ResultSet results; If (stmt. Execute (SQLstring)) { Results = stmt. getResultSet(); //false, an UpdateCount was returned } Else { Count = stmt. getUpdateCount(); } //Process the first results here . . . . //Now loop until there are no more results or update counts do { //Is the next result a ResultSet?

If (stmt.getMoreResults()) { Results **stmt. getUpdateCount(); } Elsi { Count = stmt. getUpdateCount (); } //Process next results (if any) here .. } While ((results !=null) && (count != -1)); The Preparedstatement Interface The PreparedStatement interface extends the Statement interface. When there is a SQL statement tha requires repetition with minor varications, the PreparedStatement Provides the mechanism for passing a precompiled SQL statement that uses parameters. Public interface preparedstatement extends Statement PreparedStatement parameters are used to pass into a SQL statement, so they are considered in parameters and are filled in by using set Type methods: // Assume pricelist is an array of prices that needs //to be reduced for a 10% off sale, and reducedItems // is an array of item IDs Int reducation = 10;

preparedStatement ps = conn. prepareStatment ( UPDATE Catalog SET Price = ? WHERE ItemID = ? ); // Do the updates in a loop For (int I =0; I < reducedItems. Length; i++) { //Note that the set Type methods set the value of the //parameters noted in the SQL statement with question //marks (?). They are indexed, starting from I to n. Ps . SetFloat (1, (pricelist[i]*((float)(100-reduction)/100))); Ps. setString (2, reduced Items [i]; If (ps. executeUpdate () ==0) { Throw new ApplicationSpecificException (*No Item ID: * + reducedItems [i]); } }

NOTE The set Type methods fill the value of parameters (marked by question marks) in a PreparedStatement. These parameters are indexed from 1 to n. Parameters hold their current values until either a new set Type method is called or the method clearParmeters() is called for. The PreparedStatement

object. In addition to the execute methods inherited from Statement, PreparedStatement declares the set Type methods listed in Table 11.1Each method takes two arguments: a parameter index and the primitive or class type, as shown in Table 11.1.

The CallableStatement Interface The CallableStatement interface is used to execute SQL stored procedures. CallableStatement inherits from the PreparedStatement interface, so all of the execute and set Type methods are available. The syntax of stored procedure varies among database vendors, so JDBC defines a standard way to call stored procedures in all RDBMSs. Public interface CallableStatement extends PreparedStatement The JDBC uses an escape syntax that allows parameters to be passed as in parameters and out parameters. The syntax also allows a result to be returned. If this syntax is used, the parameter must be registered as an out parameter. Here is an example of a CallableStatement with an out parameter: CallableStatement cs = conn. prepareCall ( {call getQuote(?, ?)) ); Cs.setString (1, stockName) // java. Sql. Types defines SOL data types that are returned //as out parameters Cs. registerOutParameter (2,Types.FLOAT); Cs. executeUpdate(): Float quote = cs. getFloat (2); callableStatement defines a set of get Type methods that convert the SQL types returned from the database to Java types. These methods match the set Type methods declared by Prepared Startement and are listed in Table 11.2

NOTE The get Type methods access in each column as the result of query. Each column can be accessed by either its position in the row, numbered from 1 to n columns, or by its name, like custID.

The ResultSet Interface The ResultSet interface defines methods for accessing tables of data generated as the result of executing a Statement. ResultSet column values may be accessed in any order- they are indexed and may be selected by either the name or the number (from 1 to n) of the column. ResultSet maintains the position of the current row, starting with the first row of data returned. The next () method moves to the next row of data. A partial look at the ResultSet interface follows. Vendors that implement this interface have the option of caching the results on the remote side, so there is the possibility of a communication problem. For this reason, the methods listed below throw SQLException. Boolean next ( ) throws SQLException Positions the ResultSet to the next row. The ResultSet row position is initially just before the first row of the result set. ResultSetMetaData getMetaData ( ) throws SQLException Returns an object that contains a description of the current result set, including the number of columns, the type of each column, and properties of the results. Void close ( ) throws SQLException Normally a ResultSet is closed when another SQL statement is executed, but it may be desirable to release the resources earlier. As with the callableStatement interface discussed earlier, the resulting data can be read through get Type ( ) methods. Note, however, that values can be accessed either via column names or column numbers; callable statements

can use only column numbers. Recall that column numbers begin at 1.Here is an example: //Pass a query to the statement object ResultSet rs = Stmt.executeQuery ( SELECT* FROM Stock WHERE quantity = 0 ); // Get the results as their Java types // Note that columns are indexed by an integer starting with 1, // or by the name of column, as in ItemID System.out.println ( stock replenishment list ); While (rs.next()) { System.out.println (*Item ID: +rs.getString ( ItemID )); System .out.println (*Next ship date: +rs.getDate (2)); System.out.printly (**); } The ResultSetMetaData Interface Besides being able to read data from a ResultSet object, JDBC provides an interface to allow the developer to determine what type o data was returned. The ResultSetmetaData interface is similar to the DatabaseMetaData, it is unlikely that many developers will use this interface, because most applications are written with an understanding of the database schema and column names and values. However, ResultSetMetaData is useful in dynamically determining the MetaData of a ResultSet returned from a stored procedure.

NOTE SQL LONGVARBINARY and LONGVARCHAR data types can be of arbitrary size. The getBytes ( ) and getString ( ) methods can read types up to the limits imposed by the driver. The limits can be read through the Statement. getMaxFile Size ( ) method. For larger blocks of data. (Streams must be read immediately following the query execution-they are automatically closed at the next get of a ResultSet.) You can also send lage blocks of data by using java. Io. Output Stream as a parameter. When a statement is executed. The JDBC driver makes repeated calls to read and transmit the data in the streams.

JDBC Applications versus Applets You may be wondering whether a Java applet or application would work best for your database front-end development. Each has its advantages and disadvantages. JDBC Applications Because Java applications are developed as stand-alone executables, the user is expected to have access to the program executable (class file) and the Java interpreter locally. For an intranet-based database front end, this strategy offers the benefits of faster startup (class fills are local) and local disk utilization. In addition, java applications are trusted and are allowed greater flexibility with socket connections-making it possible for the client program to access multiple database systems on remote servers. Java applications are becoming more prevalent as tools become available for GUI development and speed improvements are made possible through just-in-time (JIT) compilers/interpreters. Applications can also reduce or eliminate issues with browser security models and the differences in the browser s implementation of Java widgets.

JDBC Applets The process of executing a JDBC applet includes downloading the necessary Java applet code (including JDBC drivers and application layer software), automatically checking security restrictions on the code, and running the applet. As with other types of applets, JDBC applets have the benefits of being easy to modify, easy to use and capable of including exbedded help links. However, like other types of applets, JDBC applets also are severely constrained by the browser environment they cannot access any local files, connect to arbitrary hosts, or load or run drivers that contain native methods (C language calls). Additionally, there is a considerable performance hit involved in loading applet code across an Internet (WAN) connection. Some of these constraints may be lifted or reduced with the introduction of trusted applets and browsers that accept them. Trusted applets may be code signed with a cryptographic key or may be stored in a trusted location. If the browser environment believes that the applet s source is trusted, then for security purposes, it may be treated like an application, although there may still be limits regarding the location of databases on a network that are not related to the Java security manager. A typical use of JDBC applets might be for training within a large organization, where the data being delivered is not critical and access can be limited to a two-tier model. Another use may be the simple presentation of a limited amount of data to the Internet community, when the security of the data message is not paramount. Another alternative is the use of a three-tier model. In this approach, the applet is loaded from a middleware tier that provides both the HTML page and HTTP server, and a multithreaded application (Java, C, or C++) that supports socket connections for multiple clients and, in turn, contacts remote database systems. Calls to the third tier can be managed by developing a custom (proprietary) protocol, by using Remote Method invocation (RMI), or

by using an Object Request Broket (ORB). RMI is discussed in Chapter 12, and ORB is covered in Chapter 13. Security Considerations The JDBC API follows the standard Java security model. In short, applications are considered trusted code, and applets are considered untrusted. In general, the job of writing a secure JDBC driver is left to the driver vendor. The JVM employs its own well-documented security checks for untrusted applets, including the aforementioned restrictions. However, if JDBC driver vendors want to extend the model by adding features to their driver-for example, allowing multiple applets to use the same TCP socket connection to talk to a database- then it becomes the responsibility of the vendors to check that each applet is allowed to use the connection. In addition to maintaining the integrity of the Java security model, both the JDBC driver vendor and JDBC application developer need to keep in mind that the JDBC API defines a means of executing database calls and does not define a network security model. The data sent over the net work to the database and the resulting table information (for example, to request customer credit and card information) are exposed and can be read by any terminal that is capable of snooping the network.

A JDBC Database Example As an example of the concepts presented in this chapter, we ll work with a hypothetical database that stores information related to a large catalog ordering system. This simple database includes a table Customer, which has the following schema: Customer ID Last Name First Name VARCHAR VARCHAR VARCHAR

Phonenumber Street Address Street Address Zipcode

VARCHAR VARCHAR VARCHAR VARCHAR

Here is the definition of a simple Customer object with two primay methods, inserNewCustomer ( ) and getCustomer ( ): Public Customer (Connection conn) The constructor for the class. The Customer constructor receives a Connection object, which it uses to create Statement references. In addition, the constructor creates a PreparedStatement and three CallableStatements. Public String insertNewCustomer (String Lname, String fname, String Pnum, String addr, String zip) throws insertFailed Exception, SQLException Creates a New customer record, including a new ID. The ID is created through a stored procedure that reads the current list of customer IDs and creates a new reference. The method returns the new ID created or thows an exception if the insert failed. Public Customer Info getCustomer (Sting custID) throws selectException, SQLException Returns an object that contains the data in the Customer table. An exception is thrown if the customer ID passes does exist or is not properly formatted, or if the SQL statement fails. Public static synchronized boolen validateZip (String zip) throws SQL Exception A utility method to validate the zip code. A true value is returned if the zip code exists in the ZipCode table in the database. Public static synchronized boolen validatate a customer ID. If the ID exists, the method retrns true. The source for Customer. Java follows. It is also included on the CD-ROM in javadevhdbk\ch11\Customer.java.

List 11.1

Customer.java // Customer record class // This class is used to store and access cutomer data from the // database Import java.sql.*;

Public class Customer { Private Connection conn; Private PreparedStatement insertNewCustomer; Private CallableStatement checkZip; Public static CallableStatement checkup; Public static CallableStatement check ID; // Customer constructor: store a local copy of the // Connection object Create statements for use later Public Customer (Connection c) { Conn = c; Try { insertNewCustomer = conn. prepareStatement (*INSERT INTD Customers VALUES (?, ?, ?, ?, ?, ?,) ); getNewID = conn.prepareCall( {call getNewID (?)} );

checkId = conn.prepareCall ( {call checked (?, ?)} ); checkZip = conn.prepareCall ( {call checkZip (?, ?)} ); } Catch (SQLException e) { System.out.println( Cannot create statements ); } } // Method for createing a new Customer record. // The customer ID is generated by a stored procedure // call on the database Public string insertNewCustomer (Sting lname, String fname, String pnum, String addr, String zip) Throws insertFailedException, SQLException { String new ID; // Get a new customer ID through the stored procedure If ((newID = getNewID ())**null) { Throw new insertFailedException( could not get new ID ); }

// Insert the new customer ID insertNewCustomer.setString (1, newID); insertNewCustomer.setString (2, lname); insertNewCustomer.setString (3, fname); insertNewCustomer.setString (4, pnum); insertNewCustomer.setString (5, addr); insertNewCustomer.setString (6, zip); // Exceute the statement If (insertNewCustomer. executeUpdate( ) ! =1) { Throw new inserFailedException ( could not insert ); } Return (newID); } // Get a single customer record with this ID //Note: this method maps the returned data onto a // Customer info container object Public Customer Info getCustomer (String custID) Throws selectException, SQLException { // Check the ID first If (lvalidateID (custID))

{ Throw new selectException ( no customer with ID: + custID; } // Create the select statement Statement stmt** conn.createStatement( ); // Get the results ResultSet rs** stmt. executeQuery ( SELECT* FROM Customer WHERE CustID = + custID); Rs. Next ( ); // Create a CustomerInfo container object Customer Info info ** new Customer Info( ); // Pupulate the Customer Info object // Columns are indexed starting with 1 Info. CustomerID = rs.getString( 1); Info.LastNamed = rs.getString (2); Info.FirstName = rs. getString (3); Info.PhoneNumber = rs. getString (4); Info.StreetAddress = rs.getString (5); Info.Zip = rs. getString (6); Return (info); }

// Method for validation of a customer s zip code // This method is public so that it can be called from //a user interface Public static synchronized Boolean validateZip (String zip) Throws SQLException { // Make call to stored procedure to validate zip code checkZip.setString (1,zip); checkZip. registerOutParameter (2, types.BIT); checkZip. executeUpdate( ); return (chedckZip.getBoolean (2)); } // Method for validating a customer ID // This method is public so that it can be called from // a user interface Public static synchronized Boolean validateID(String id) Throws SQL Exception { // Make call to stored procedure to validate // customer ID checkId. setString (1.id); checked.registerOutParameter (2, Types.BIT);

checked. executeUpdate( ); return (checkId.getBoolean (2)); } // Method for retrieving a new customer ID from the database Private String getNewID ( ) throws SQLException { // Make call to stored prodecure to get // customer ID from DB getNewID.registerOutParameter (1,Types. VARCHAR); getNewID.executeUpdate ( ); return getNewID.getString(1); } } // Exceptions // insertFailedException is a general exception for // SQL insert problems Class insertFailedException(String reason) { Super (reason); } Public insertFailedException( ) {

Super (reason); } Public insertFailedException( ) { Supert( ); } // selectException is a general exception for SQL select problems class select Exception extends SQLException { Publdic selectException(String reason) { Super (reason); } Public selectException ( ) { Super ( ); } } TIP The Customer Info class is a simple container object. Classes make it easier to pass a complete customer record to and from and from any method that manipulates the Customer table in the database. Data can be stored in the container class and passed as a single object reference, rather than having to pass each element as a single reference.

The following code can be found in javadevhdbk\ch11\Customer Info.java.

List 11.2

CustomerInfo.java // A container object for the Customer table public class Custome Info { String Customer ID; String Last Name; String FirstName; String PhoneNumber; String Street Address; String Zip; }

Finally, to test the simple Customer class, here is a simple Java application that illustrates loading a Sybase driver, then making a connection, and passing the connection object returned to a new instance a Customer object. The following code can be found on the CD-ROM in javadevhdbk\ch11\Example.java.

List 11.3

Example.java

// A simple Java application that illustrates the use of // DriverManager, // Driver, Connection, Statement and ResultSet Import java.sql.*;

Public class Example { Connection SybaseConn; // main Public static void main (String arg[ ]) { // Look for the URL. Username and password If (arg.length < 3) { System.out.println ( Example use:*); System.out.println (*java Example <url> <username> <password> ); System.exit(1); } // Create an instance of the class Example ex ** new Example ( ); // Initialize the connection Ex.testdb( ); } // method to initialize the database connection // The Connection object reference is kept globlly Public void initdb(String url, String user, String passwd)

{ // Try to open the database and get connection Try { // Note that this example that // Java property jdbc.drivers // that is loading the appropriate driver (s) for // the URL passed in the getConnection call. // It is possible to explicitly create an // instance of driver as well, for example: // new Sybase. Sql.Driver( ); or // Class. For Name ( Sybase.sql.Driver );

//Create a connection sybaseConn ** passwd); } Catch (SQLException e) { System.out.println(*Database connection failed;*); System.out.println(e.getMessage( )); System.exit(1) } DriverManager.getConnection(url, user,

} // Simple method to test Customer class methods Public void testdb ( ) { String custID = null; // Create the instance of the Customer class Customer cust ** new Customer (sybaseConn); Try { // Now insert a new Customer custID ** cust.insertNewCustomer ( Jones , Bill , 555-1234 , 5Main Street , 01234 ); } Catch (SQLException e) { System.out.println( Insert failed: ); System.out.println(e.getMessage( ) ); System.exit(1); } Try { // Read it back from the database

CustomerInfo info = cust.getCustomer(custID); } Catch (SQLException e) { System.out.println( Read failed ); System.out.println(e.getMessage()); System.exit(1); } } }

This example illustrates the use of the callablesatements to the callableStatements to issue stored procedure calls that validate the zip and validate the customer ID, and the PreparedStatement to issue an Insert SQL statement with parameters that will change with each insert. This example also illustrates code that will run with any JDBC driver that will support the stored procedures used in the Customer class. The driver class names are loaded from the jdbe. Drivers property so code recompilation is not required. JDBC Drivers One of the real attractions of the JDBC API is the ability to develop applications knowing that all the major database vendors are working in parallel to create drivers. A number of drivers are available both from database venfores from third-party developers. In most cases. It is wise to shop around for the best features, cost, and support.

TIP JDBCE drivers are being released from so many vendors and at such a rapid rate that a definitive list is just not practical and would be obsolete by the time it was printed. For information on current driver vendors, their product names, and what databases they support, a good source is http://splash.javasoft.com/jdbc/jdbc.divers.html.

Types of Drivers Drivers come in a variety of flavous according to their construction and the type of database they are intended to support. JavaSoft categorizes database drivers four ways: y AJDBC-ODBC bridge driver, shown in Figure 11.6, implemented with ODBC binary code, and in some cases, a client library as well. The bridge drivers is made up of three parts: a set of C librarie that connects the JDBC to the ODBC driver manager, the ODBC driver manager, and the ODBC driver. (See the next section for more information about the JDBC-ODBE bridge.) y A native library-to-Java implementation, as shown in Figure11.7. This driver uses native C language library calls to translate JDBC to the native client library. The drivers use C language libraries that provide vendorspecific functionality and tie these libraries (through native method calls ) to the JDBC. These drivers were the first available for Oracle, Sybase, Informix, DB2, and other client-library-based RDBMSs. y A network-protocol Java driver, as shown in Figure11.8.JDBC calls are translated by this driver into a DBMS-independent protocol and sent to a middle-tier server over a socket. The middle-tier server over a socket. The middle-tier code contacts a varit of databases on behalf of the client. This approach is becoming the most popular and is by far the most flexible. This approach also deals specifically with issues realtig to network security, including passing data through firewalls.

y A native-protocol Java driver, as shown in Figure 11.9 JDBC calls converted directly to the network protocol used by the DBMS server. In this driver scenario, the database vendor supports a network socket, and the JDBC driver communicates over a socket connection directly to the database server. The client side code can be written in Java. This solution is very practical for intranet use. However, because the network protocol is defined byf the vendor and is typically proprietary, the driver usually comes only from the database vendor.

The JDBC-ODBC Bridge The JDBC-ODBC bridge is a JDBC driver that provides translation of JDBC calls to ODBC operations. There are a number of DBMSs that support ODBC, When a company the size of Microsoft creates a standard for database access, there are sure to be vendors that follow, and in fact there are more than 50 different ODBC drivers available. As mentioned earlier in this chapter, both JDBC and ODBC are based on the X/Open CLI, so the translation between JDBC and ODBC is relatively straightforward. ODBC is a client-side of libraries and a drive that is a specific to the client s operating system and, in some cases, machine architecture. From the developer s perspective, using a JDBC-ODBC bridge driver is an easy choice-applications will still speak directly to the JDBC interface classes, so it is exactly the same as using any other JDBC driver. However, the implementation of a JDBC-ODBC bridge requires that the developer be aware of what is required to run the application. Because ODBC calls are made using binary C calls, the client must have a local coy of the ODBC driver, the ODBC driver manager, and the client-side libraries. For these reasons, JavaSoft makes the recommendation that the JDBCODBC bridge not be used for web-based database access. For intranet access, the developer must distribute the Java program to the client machines as either a Java application or Java applet (whdich would run as a trusted source fro the local client file system).

Summary The interest in Java has created a number of new strategies for moving data between the database system and the front end user. In this chapter, the JDBC API was presented as the dprimary technique for connecting Java applications to database systems. The JDBC solves the dproblem of connecting a single application to a multitude of database systems by isolating the interface that the developer use and the driver that is used to connect to the database. As alternative database connectivity strategies, both RMI (Remove Method Invocation) and CORBA (Common Object Request Broker Architecture) can be used to connect client applications to databases. RMI is the subject of Chapter 12, and CORBA is covered in Chapter 13.

CHAPTER TWELVE Persistence and Remote Method Invocation      Object persistence and serialization RMI basics Callbacks in RMI Dynamic class loading in RMI Remote object activation

Java 2 includes support for object persistence and for making method calls on remote objects. This chaptr explains these two concepts, discusses Java s support for them, and shows how they are related. The final section of the chapter covers the new features of Remote Method Invocation (RMI) that were introduced with JDK release 1.2.

Object Persistence A Java object ordinarily lasts no longer than program that created it. An object may case to exist during runtime if it is reaped by the garbage collector. If it avoids that fate, it still goes away when the user terminates the brower (for an applet) or the object s runtime environment (for and application). In this context, persistence is the ability of an object to record its state so that it can be reproduced in the future, perhaps in another environment. For example, a persistent object might store its state in a file. The file can be used to restore the object in a different runtime environment. It is not really the object itself that persists, but rather the information necessary to construct a replica of the object. Whan an object is serialized all of the object s data, but not its methods or class definition, is writtern to a stream. Serialization An object records itsrlf by writing out the values that describe its state. This process is known as serialization because the object is represented by an ordered series of bytes. Java provides classes that write objects to streams and restore objects from streams. The main task of serialization is to write out the values of an object instance variables. If a variable is a reference to another object, the referenced object must also be serialized. Seriaizatin may involve serializing a vomplex tree structure that consists of the doriginal objct, the object s objects, the objects s objects s objects, and so on. An object s ownership hierarchy is known as its graph. Not all clases are capable of being serialized. Only objects that implement the serializable or Externalizable interfaces may successfully be serilized. Both interfaces are in the java. Io package A serializable object can be serialized by another object, which in practice is a type of output stream. An externalizable object must be capable of writing its own state, rather than letting the work be done by another object.

The Serializable Interface The Serializable interface does not have any methods. When a class declares that it implements Serializable, it is declaring that it participates in the serialization protocol. When an object is serializable, and the object s state is witten to a stream, the stream must contain enough information to restore the object. This must hold true even if the class being restored has been updates to a more recent (but compatibl) version. You can serialize any class as long as the class meets the following criteria: y The class, or one of its superclasses, must implement the java. Io. Serializable interface. y The class can implement the writtObject( ) method to control data that is being saved and apped new data to existing saved data. y The class can implement the readObject( ) method to read the data that was written by the corresponding writtenObject( ) method.

If a serializable class has variables that should not be serialized, those variables must be market with the transient keyword. The serialization process will ignore any variables marked as transient. In general, references to AWT classes that rely on system peers should be marked as transient. Many things like static data, oen file handles, socket connections, and threads will not be serializable, because they represent items that are very JVM-specific. The Externalizable Interface The Externalizable interface identifies objects that can be saved to a stream but are responsible for their own states. When an externalizable object is written to a stream, the stream is responsibl for storing the name of the object s class; the object must write its own data. The Externalizable interface is defined as: Publdic interface Externalizable extends Serializable {

Public void writeExternal (objectOutput out) Throws IOException; Public void readExternal (ObjectInput in) Throws IOException, ClassNotFoundException; } An externalizable class must adhere to this interface by providing a writeExternal ( ) method for storeing its state during serialization and a readExternal ( ) method for restoring its state during deserialization.

Object Output Streams Objects that can serialize other objects implement the ObjectOutput interface from the java. Io package. This interface is intended to be implemented by output stream classes. The interace s definition is: Public interface ObjectOutput extends DataOutput { Public void writeObject (Objectobj) Throws IOException; Public void write (int b) throws IOException; Public void write(byte b[ ] ) throws IOException; Public void write (byte b [ ] , int off, int len) Throws IOException; Public void flush ( ) throws IOException; Public void close ( ) throws IOException; }

The essential method of the interface is writeObject(Object obj), whdich writes obj to a stream. Stream. Static and transient data of obj are ignored; all other variables, including private ones, are written. Exceptions can occur while accessing the object or its fields, or when attempting to write to the storage stram. I an exception occurs, the stream that the interface is built on will be left in an known and unusable state, and the external representation of the object wil be correupted. The ObjectOutput interface extends the DataOutput interace. DataOutput methods support writing of primitive data types. For example, the writeDoubled( ) methdod writes data of type double, and write Boolean ( ) writes data of type Boolean. These primitive-type writing methods are used for writing out an object s primitive instance vatiables. The primary class that implements the ObjectOutput interface is ObjectOutput Stream. This class is similar to other output stream classes, which are discusses in Chapter 9. To test the application, invoke it with a filename as a commandline argument: Java Persis Test filename Then use the mouse to draw some rectangles. Next, click on the Save button to write the display list to the file. Clear the screen or draw more rectangles. Finally, click the Restore button. The Display will change back to state it was in when the Save button clicked. You can even terminate he application and restart it; it will still restore correctly from the external file. This example could achieve the same result by opening a data output stream instead of an object ouput stream and writing four ints for each rectangle. The benefit of using serialization lies in the dramatic improvement in program maintainability. If you were to store and

restore the display list by using data input and output streams, any change in the format of the display list would force a change in both the writing and the reading code. With serialization, the display list data format is irrelevant (although the data graph is still important changing the data in the object would make restoring old data impossible). The source code for the example follows, and it I also included on the CD-ROM in the file javadevhkbk\ch12\serial\persisTest.java. LIST 12.1 PersisTest.java

Import java. awt.*; Import java.awt.event.*; Import java.io.*; Import java.util.Vector; Public class persisTest extends Fram Implements MouseListener, ActionaListener { Vector String Button displayList; pathname; clearBtn, saveBtn, restoreBtn, quitBtn;

Public static void main(String args[ }) { If (args.length ==o) {

System.out.println( Usage: java PersisTest filename ); System.exit(0); Try { s.writeObject (p); s.flush ( ); } catch (IOException e) { }

Restoring the object involves opening a file input stream on the file and chaining an object input stream to the file input stream. The point object is read by calling readObject ( ) from the object input stream; the return value is of type object and must be cast by the caller. The following code fragement show how this is doen: Point p = null; FileInputStream f = new FilekInputStream ( point.ser ); ObjectInputStream s = new ObjectInputStream (f); Try { P = (point)s. readObject ( ); } Catch (IDException e) { } In the next section, we will develop a simple example that saves and restores an object. A Serialization Example

As an example of serialization, we will develop a simple painting rogram, call PersisTest, that can store its display list to a file. (A display ist is data structure that contains an abstract desdcription of what should appear on the screen.) The program allows the user to draw rectangles with the mouse; pressing the mouse buttondefins one corner of a rectangle, and releasing the button defines the opposite corner. The display list is a vector that contains two instances of the point class for each rectangle. Each point represents a corner o the rectangle. The PersisTest application is a subclass of Frame. A panel across the top of the frame contains four control buttons. The frame s paint ( ) method clears the screen to while and then traverss the display list vector, drawing one black rectangle for each pair of points in the vector. The four control buttons support clearing, saving, restoring, and quitting. The handler for the Save button uses the writing technique discussed in the previous section to store the display list vector in a file. The filename must be specified in the command-line argument. The handler for the Restore button deserializes a vector, replacidng the old display list with the dnew vector. To test the application, invoke it with a filename as a commandline argument:

Java Persis Test filename Then use the mouse to draw some rectangles. Next, click on the Save button to wite the display list to file. Clear the screen or draw more rectangles. Finally, click the Restore button. The display will change back to state it was in when the Save button. The display will change back to the state it was in when the Save button was clicked. You can even terminate the application and restart it; it will still restore correctly from the external file.

This example could achieve the same result by opening a data output stream instead of an object output stream and writing four ints for each rectangle. The benefit of using serialization lies in the dramatic improvement in program maintainability. If you were to store and restore the display list by using data input and output streams, any change in the format of the display list would force a change in both the writing and the reading code. With serialization, the display list data format is irrelevant (although the data graph is still important changing the data in the object would make restoring old data impossible). The source code for the example follow, and it is also included on the CD-ROM in the file in javadevhkbk\ch12\serial\PersisTest.java. List 12.1 Import java.awt.*; Import java.awt.event.*; Import java.io.*; Import java.util.vector; PersisTest.java

Public class PersisTest extends Frame Implements MouseListener. ActionaListener { Vector String Button displayList; pathname; ClearBth, saveBtn, restorBtn, quitBtn;

Public static void main(String args [ ])

{ If (args.length ==o) { System.out.printIn( Usage: java PersisTest filename ); System.exit(0); } PersisTest that ==new PersisTest(args[0]); That.show( ); } Public PersisTest(String pathname) { This.pathname ==pathname; displayList = new Vector ( ); // Handle our own mouse clicks. addMouseListener(this); //Build the GUI. Make this object a listener for all actions. setLayout (new BorderLayout()); Panel pan= new Panel ( ); ClearBtn = new Button ( Clear ); Clear Btn. addActionListener(this); Pan.add(clearBtn); saveBtn = new Button( Save );

saveBtn.addActionListener (this); pan.add(saveBtn); restoreBtn = bew Bytton( Restore ); restoreBtn.addActionListener(this); pan.add(restoreBtn); quitBtn = new Button ( Quit ); quitBtn.addActionListener(this); pan.add(quitBtn); add( North , pan); setSize (350, 200); } Public void paint (Graphics g) { // Clear to white. g.setColor (Color.white); g.fillRect(O, O, getSize( ). Width, getSize( ). Height); // Traverse display list, drawing 1 rect for each 2 points // in the vector. g.setColor(Color. Black); int I = 0; while (I < displayList.size( )) {

Point po = (Point)(displayList.elementAt(i++)); Point p1 = (Point) (displayList.elementAt(i++)); Int x = Match.min(pO.x, p1.x); Int y = Match.min(pO.y, p1.y); Int w = Match.abs(pO.x p1.x); Int h = Math.abs(pO.y p1.y); g. drawRect(x, y, w, h); } } Public void mousePresses(MouseEvent e) { // Store x and y in display list vector Point p = new Point(e.getX( ), e. getY( ) ); displayList.addElement(p); } Public void mouseReleased(MouseEvent e) { // Store x and y in display list vector , and request repaint. Point p = new Point(e.getX( ), e.getY()); displayList.addElecment(p); repaint ( ); }

// Unused methods of MouseListener interface. Public void mouseClicked(MouseEvent e) { } Public void mouseEntered(MouseEvent e) { } Pubic void mouseExited(Mouse Event e) { }

Public void action Performed(ActionEvent e) { If (e.getSource( )== clearBtn) { // Repaint with an empty display list. displayList = new Vector( ); repaint ( ); } Else if (e.getSource( ) == saveBtn) { // Write display list vector to an object ouput stream. Try { // Write display List vector to an object output stream. Try { FileOutputStream fos = new FileOutputStream(pathname);

ObjectOutputStream oos = new ObjecOutputStream(fos); Oos.writeObject(displayList); 00s.flush( ); Oos.close(); Fos.close(); } Catch (Exceptionex_ { System.our.println( Trouble writing display list vector ); } } Else if (e.getSource( ) == restoreBtn) { // Read a new display list vector from an object input stream. Try { FileInputStream fis = new FileInputStream(pathname); ObjectInputStream ois = new ObjectInputStream(fis); Ois.close( ); Fis.close ( ); Renaint( ); }

Catch (Exception ex) { System.out.println( Trouble reading display list vector ); } } Else if (e. getSource( ) == quitBtn) { setVisible(false); dispose( ); system.exit(O); } } }

An Introduction to Remote Method Invocation Java s Remote Method Invocation (RMI) feature enables a program in one JVM to make method calls on an object located in a different JVM, which could be running on a remote machine. The RMI feature gives Java programmers the ability to distribute computing across a networked environment. Object- oriented design requires that every task be executed by the object most appropriate to that task. RMI takes this concept one step further by allowing a task to be performed on the machine most appropriate to the task. RMI defines a remote interface that can be used to create remote objects. A client can invoke the methods of a remote object with the same

syntax that it uses to invoke methods on a local object . The RMI API provides classes and methods that handle all of the underlying communication and parameter referencing requirements of accessing remote methods. RMI also handles the serialization of objects that are passes as arguments to menthods of remote objects. The java.rmi and the java.rmi.server packages contain the interfaces and classes that define building blocks for creating server-side objects and clientside object stubs. A stub is a local represesntation of a remote object. The client makes calls to the stub whdich automatically communicates with the server. Object Persistence and RMI When a Java program uses RMI, method parameters must be transmitted to the server and a return value must be sent back to the client. Primitive values can be simply sent byte by byte. However, passing objects, either as parameters or teturn values, requires a more sophisticated solution. The remote object instance needs access to the entire graph of objects referenced by a parameter passes to its method. The remote method might constructed and return a complicated object that holds references to other objects. If this is the case, the entire graph must be returned, so any object passes to or returned from a remote method must implement either the serializable or the dExternalizable interface. RMI is similar to the Remote Procedure Call (RPC) feature that Sun introduced in 1985. RPC also required a way to serialize parameter and return value data, although the situation was simpler because of the absence of objects. Sun developed a system called External Data Representation (XDR) to support data serialization. One significant difference between RPC and RMI is that RPC uses the fast but not very reliable UDP protocol: by default, RMI uses the slower but more reliable not very reliable TCP/IP protocol. However, by implementing your own subclass of java. rmi server.RMISocketFactory, you can choose to run RMI over other socket protocols.

The RMI Architecture The RMI architecture consist of three layers: the stubs/sketleton layer, the remote reference layer, and the trnspot layer. The relationships among these layers are. Shown in Figure 12.`1.

For our example, the following command creates the stubs and skeletons for the CreditCard and CreditManager remote classes: Rmic d. credit. CreditCardImpl credit. CreditManager Impl Note that the command requies specification of the package in which the class files reside. This is why all the source modules for the implementation classes declare that they belong to the credit package. The rmic command creaters four class files in the credit package directory: y y y y CreditCardImpl_Skel.class CretitCardImpl_Stub.class CreditManagerImpl_skel.class CreditManagerImpl_Stub.class

Creating and Compiling the Server Application Now that the stubs and skeletons have been created, the next step is to create a server- side application that makes these classes available to clients for remote invocation. The server-side application will be an application class called CardBank, whose main job is to construct an instance of CreditManager. Except for the line that calls the Credit Manager constructor, all of the Card Bank code involves making the CreditManager object available to remote clients. The details of this process are explained after the following code listing.

List 12.6

CardBank.java

Import java. utill.*; Import java.rmi.*; Import java.rmi.RMISecurityManager; Import credit.*; Public class CardBank { Public static void main (String args[ ] ) { // Create and install a Security manager. System.setSecurityManager(new RMISecurityManager()); Try { // Create an instance of our Credit Manager. System.out.println ( CreditManagerImpl: create a CreditManager ); CreditManagerImpl cmi = new CreditManagerImpl(); //Bind the object instance to the remote registry. Use the // Static rebind ( ) method to avoid conflicts. System.out.println( CreditManagerImpl: bind it to a name ); Naming rebind ( CardManager , cmi);

System.out.println( CreditManager is now ready ); } catch (Exception e ) { System.out.println( An error occurred );

e.printStackTrace(); System.out. println(e.getMessage( )); } } }

Applications, by default, run without security managers. In the main method of CardBank, the set5ecurityManage( ) call installs an RMI security manager. The server publishes an object instance by binding a spedified name to the instance and registering that name with the RMI registry. There are two methods that allow an instanc to be bound and registered: Public static void bind (String name, Remote obj) throws AlreadyBoundException, MalformedUrlException, UnknownHostException, RemoteException Public static void rebind (String name, Remote obj) throws MalformedUrlException, UnknowHostException, RemoteException

Notice that both methods are static and ask for a name to reference the object, as well as the remote object instance that is bound to the name. In our example, the object name is cardManager. Any machine on the network can refer to this object by specifying the host machine and the object name. The name argument required by both bind ( ) and rebind ( ) is a URL-Like string. This string can be in this format:

Protocol://host:port/bindingNames Here protocol is rmi, host is the name of the RMI , port is the port number on which the server should listen for requests, and bindignName is the exact name that should be used by a client when requesting access to the object If just a name is given in the string, then default values are used. The dafaults are rmi for the protocol, localhost for the server name, and 1099 for the port number. WARNING An attempt to bind to any host other than the localhost will result in a securityException. Both bind ( ) and rebind ( ) associate a name with an object. They differ in their behavior when the name being bound has already been bound to an object. In this case, bind ( ) will throw AlreadyBoundException, and rebind( ) will discard the discard the old binding and use the new one. Starting the Registry and Server Application The rmiregistry is an application that provides a simple naming lookup service. When the CardBank calls rebind ( ). It is the registry that maintains the binding. The registry can be run as an independent program or it can created by calling the java.rmi. registry. LocateRegistry.CreateRegistry method, and it must be running before the server side application is invoked. The program resides in the jdk/bin directory. The following two command lines invoke the registry and start up the card bank server: Start rmiregistry Java CardBank

The card bank application prints several status lines as it starts up the service. If there are no errors, you should see the following output: creditManagerImpl: create a CreditManager CreditManagerImpl: bind it to a name CreditManager is now ready Once an object has been passed to the registry, a client may request that the registry provide a reference to the remote object. The next section shows how this is done. Creating and Compiling the Client program The Shopper application needs to find a CreditManager object on the remote server. Th program assumes that the server name has been passed in as the first command-line argument.This name is used to create a URLlike string of this format: Rmi://<hostname>/cardManager The string is pases to the static lookup( ) method of the Naming class. The lookup ( ) call communicates with the rmi registry and returns a handle to the remote object that was constructed and registered. More accurately, what is returned is a handle to a stub that communicates with the remote object. The return type from lookup( ) is Remote, which is the parent of all stub interfaces. When the return value is cast to type CreditManager, the methods of CreditManager can be invoked on it. The following sample code, titled Shopper. Java, shows how this is done. List 12.7 Shopper. Java Import java.rmi.*; Import java.rmi.RMISecurityManager; Import credit.*;

Public class Shopper { Public static void main (String args [ ]) { CreditManager cm = null; CreditCard account = null; // Check the command line If (args.length < 2) { System.err.println ( Usage: ); System.err.println( java shopper <servr> <account name> ); System.exit (1); } // Create and install a security manager. System.setSecurityManager(new RMISecurityManagr( ) ); // Obtain reference to card manager. Try { String url = new String ( // + args [0] + /cardManager ); System.out.println ( Shopper: lookup cardManager, url + +url); Cm = (CreditManager) Naming.lookup(url); } catch (Exception e ) {

System.out.println( Error in getting card manager +e); System.exit (1); } // Get user s account.

Try { Account = cm. findCreditAccount (args[1]): System.out.println ( Found account for + args[1]); } catch (Exception e) { System.out.println( Error in getting account for + Args[1]); System.exit (1); } // Do some transcations. Try { System.out.println( Available credit is: + account.getCreditline()); System.out.println( Changing pin number for account ); Account.setSignature(1234); System.out.println( Buying a new watch for $100 ); Account.makePurchase(100.oof, 1234); System.out.println( Available credit is now: + Account.getCreditLine( )); System.out.println( Buying a new pair of shoes for $160 ); Account.makePurchase(160).oof, 1234); System.out.println( CardHolder: paying off $136 of Balance );

Account.payTowardsBalance(136.oof); System.out.println( Available credit is now: + Account.getCreditLine()); } catch (Exception e) {

System.out.println( Transaction error for + args[1] ); } System.exit (0); } } The client expects two command-line arguments. The first argument specifies the serve. (Ffor testing on a single machine, specify localhost for the server name.) The second argument is a string tha provides an account name. The client program asks the server-side credit manager object for a handle to the credit card object that represents this customer s account. (If the customer has no account yet, one will be created.) The initial random PIN number is modified to something a user will find easier to remermber. The client program then makes several purchases and one payment, reporting the available credit after each transaction. Testing the Client The final step is to execute the client code. It can be run from any computer that has access to the server and to the supporting classes. Here is a sample session output on a Unix machine, with the remote service running on a host named sunbert (the first line is the invocation; the rest is output): % java Shopper sunbert pogo Shopper: lookup cardManager, url =//sunbert/cardManager Found account for pogo

Available credit is: 5000.0 Changing pin number for account Buying a new watch for $100 Available credit is now: 4900.0 Buying a new pair of shoes for $160 CardHolder: Paying of $136 of balance Available credit is now: 4740.0 After the client program has finished running, the remote objects are still alive The execution shown above created a new account for the customer. A second invocation of the client will work with thet account; the available credit numbers in the listing below reflect the current state of the account: % java Shopper sunbert pogo Shopper: lookup cardManager, url = // sunbert/cardManager Found account for pogo Available credit is: 4740.0 Changing pin number for account Buying a new watch for $100 Available credit is now: 4640.o Buying a new pair of shoes fo $160 CardHolder: Paying off $136 of balance Available credit is now: 4480.0 Adanced RMI So far, the example shown in this chapter have just scratched the surface o what RMI has to offer. To RMI system releases with JDK 1.1

demonstrated that it was poised to be a strong caddidate for distributed Java systems; RMI in Java 2proves that Java Soft is not willing to let RMI be a flash in the pan. Here are some of the new features in RMI, which we will explore in the following sections: y The ability to perform callbacks y Dynamic class loading y Object activation, which allows a client to request a reference to a remot object that is not currently active in a a JVM. TIP The RMI is Java 2 also allows you to define and use a custom socket protocol. By subclassing the RMISocketFactory class, you can create your own network protocols, change the network protocol on a per-object basis, or make of secure network protocol like SSL (Secure Socket Layer).

Callback Operations The simple credit card system we developed in the previous section demonstrates a typical client/server application. The CardBank servr creates an instance of a CardManager object and serves the instance of object to the Shopper client using RMI. That example illustrate some of the underlying that RMI handles on the developer s behalf, like the creation and use of network sockets. However, what that example does not show is that RMI is capable of providing two-pay communications between objects. For an object s reference to be sent from one place to another, the object s class only needs to implement a Remote interface and be exported in order to receive remote method calls(by extending UnicastRemoteObjects, an Object is automatically exported).

Once these two requirements have been met. It is possible to send a remote object from a client to a server in such a way that the server is a actually calling the remote methds of the client object. This is the nature of truly distributed application. There is no distinction between client and server -each application provides or uses the services of another. To demonstrate this concept with a practical example, we will extend the Credit application. In that example, the customer receives a credit line by simply passing his or her name to the CreditManager. In this example, ths customer will fill out Credit Application and send that application to the CreditManager. The CreditManager instance will use method provided by a CreditApplication to fill in data that the customer can then validate for the final creditApplication to fill in data that the customer can then validate for the final credit application. In this example, the client creates a local instance of a CreditApplication object and passes a reference to that instance to the server through the CreditManager, obtained through the registry. The server executes methods on the CreditApplication reference using the same mechanism the client usesthe server holds a reference to a stub instance that forwards requests to the client s local object. This example uses the code listed in the following sections, which is also included on the CD-ROM in the directory javadevhdbk\ch12\callback. Creating the CreditApplication Object The CreditApplication object is created in the same way as any other RMI remote object. The object s remote methods are defined in an interface class that extend java.rmi.Remote. List 12.8 CreditApplication.java Package credit; Import java. rmi.*; Public interface CreditApplication extends Remote {

Public String getCustName ( ) Throws RemoteException; Public void setCreditLine (float amount) Throws RemoteException; Public void setCreditCardNumber (String cardNumber) Throws RemdoteException; } Implementing CreditApplication The CreditApplicationImpl object is an implemention of CreditApplication and provides bodies for each of the methods defined in the interface. In addition, CreditApplicationImol defines tha data that a credit application is expected to store. This class extends UnicastRemoteObject so that it is automatically exported upon creation, and it implements a remot interface, CreditApplication, so that it may be passes by reference to the server. For cases where a class cannot extend UnicastRemoteObject, the developed can explicitly export an object through the static method, UnicastRemoteObject. exportObject. List 12.9 CreditApplicationmpl.java Pckage credit; Import java. rmit.*; Import java. rmi.server.*; Public clas CreditApplication Impl extends UnicastRemoteObject implements CreditApplication { Private float creditlinel; Private float creditRate;

Private String CrexditCarNumber; Privat String custName; Private String ssn; Public CreditAppliationImpl (String name, String soc) Throws RemoteException { custName =name; ssn = soc; } Public String gt CustName ( ) { Return custName; } Public void setCreditLine (float amount) { creditLine = amount; } Public void setCreditLine (float amount) { creditLine = amount; } Public float getCreditLine ( ) { Return creditLine; } Public void setCreditCarNumber (String cardNumber) { creditCArNumber = new String (cardNumber);

} Public String getCreditCarNumber ( ) { Return creditCardNumber; } } Modifying CreditManager The CreditManager interface is modified so that the CreditApplication object can be sent to the credit manager. If the customer s application is accepted, the customer will then be issued a valid CreditCard. LIST 12.10 CreditManager.java Package credit; Import java.rmi.*; Public interface Creditmanager extends java. rmi. Remote { /** This method finds an existing credit card for a Given customer credit number. If the customer Does not have an account, an InvalidAccountException Is thrown.*/ Public CreditCard findCreditAccount(String customer) Throws InvalidAccountException, RemoteException;

//** This method received an CreditApplication object from the customer. On the custome s behalf the serve will fill in the missing account number, initial credit line and rate.*/ Public void applyForCard (CreditApplication app)

Throws DuplicateAccountException, AccountRejectedException, RemoteException; } Implementing CreditManager The implementation of CreditManager object is changed to reflect the new design. The CreditManagerImpl now uses a private method to create a credit account. Which is called only if the customer s credit application is approved.

List 12.11

CreditManagerlmpl.java Package credit; Import java. rmi.*; Import java. rmi.server. *; Import java. util. Hashtable; Public class CreditManagerImpl extends UnicastRemoteObject Implements CreditManager { Private static transient Hashtable accounts = New Hashtable ( );

/** This is the default class constructor that does nothing But implicitly call super( ). */ Public CreditManage call super ( ).*/ Public CreditManager Impl( ) throws RemoteExcption { }

/** Creates a new account. Puts the customer name and the Custome s credit card in the hashtable. */ Public CreditManagerimpl( ) throws RemoteException { } /** Creates a new account. Puts the customer name and the customer s credit card in the hashtable. */ Private void newCreditAccount(String anme. String cardNumber, Floate creditLine) throws Dupl;icate Account Excepdtion, RemoteException { CreditCardImpl new Card = New CreditCardImp (name, cardNumbr, creditLine); Accounts. Put(cardNumber, new card): } /** Searches the hashtable for an existing account. If no account for customer name. an InvalidAccountException is thrown. */ Publdic CreditCard findCreditAccount(String cardNumber) Thtows InvalidAccountException, RemoteException { CreditCardImpl account = (CreditCardImpl) accounts. Get(cardNumber); If (account ! = null) { Return account; } else { Throw new InvalidAccountException ( ); }

} /** The Account Manager will determine (based on the Customer name and social security number) the credit line and credit rate.*/ Public void applyForCard (CreditApplication app) Throws DuplicateAccountException, AccountRegjectedExcepiton, RemoteException { // Here, some other process would determne the // customer s credit rating // For now, we ll hardcode that number to 5000. App.setCreditLine (5000.0f); // Generate a credit card number the user can use. String cardNumber = app. getCustNmae( ) + (int)(Math.random( ) * 10000); App.setCreditCarNumber (cardNumber); // Generate the customer credit card. NewCreditAccount (app.getCustName ( ), CardNumber); // Generate the customer credit card. NewCreditAccount (Account (app.getCustName( ), cardNumber, 5000.0f); }

Modifying the Client The client application is modified only slightly to include the step of applying for credit through a CreditApplication object. LIST 12.12 Customer.java Import credit.*; Import java. rmi.*; Public class Customer { Public static void main(String args[ ] ) { CreditManager cm = null; CreditApplicationImpl cardApp = null; CreditCard account = null; // Chck the command line. If (args. Length < 3) { System.err.println ( Usage: ); Sysgem.err.println( java Custome <server> <account Name> <social security number> ); System.exit (1) } // Create and install a security manager. System. setScurityManager(new RMISecurityManager( ));

// Obtain reference to card manager. Try {

String url = new String ( // + args[ 0 ] + /cardManager ); System.out.println ( Shopper: lookup cardManager, url = +url); Cm = (CreditManager) Naming . lookup (url); } catch (Exception e) { System.out.println ( Error in getting card manager + e); System.exit(1); } // Apply for a credit card. // Create an instance of a credit card application. // Send the credit application to the Credit Manager. Try { cardApp = new Credit application to the Credit Manager. Try { cardApp = new CreditApplicationImpl(args[1], args[2]; cm.applyForCard (cardApp); } catch (DuplicateAccountException e) {

System.out.println ( Duplicate Exception applying for Credit ); System.exit (1); } catch (AccountRejectedException e) { System.out.println ( Reject Exception applying for credit );

System. Exit (1); } catch (RemoteException e) {

System.out.println ( Remote Exception applying for credit +e); System.exit (1); } // The application was accepted, let s use the new card! Try { System.out.println ( new credit card number is: + CardApp.getCreditCardNumber( ) + with a credit line of : + CardApp.getCreditLine( ) ); Account = cm.findCreditAccount(cardApp.getCreditCardNumber( ) ); System.out.println ( Found account: + cardApp.getCreditCardNumber( ) ); } catch (Exception e) { System.out.println ( Error in getting account for + Args [1]); System.exit ( 1); } // Do some transcations. Try { System.out.println( Available credit is:

+ account.etCreditLine( ) ); System.out.println( Changing pin number for account ); Account.setSignature (1234); System.out.println( Buying a new watch for $100 ); Account.makePurchase(100.00f, 1234); System.out.println( Available credit is now: + Account.getCreditLine()); System.out.println( Buying a new pair of shoes for $160 ); Account.makPurchase(160.00f, 1234); System.out.println( CardHolde: Paying off $136 of balance ); Account.payTowardsBalance (136.00f); System.out.println( Available credit is now: + Account.getCreditLine( ) ); } catch (Exception e) {

System.out.println ( Transaction error for + Args[1]); } System.exit(0); } }

All that remains is to run rmic on the client-side CreditApplicationImpl class. The rmic utiily creates a set of stub classes that the server will use as proxies to the implementation class.

Dynamic Class Loading One of the primay tratures of RMI is that it has been designed from the ground up as a Java-to-Java distributed object system. RMI is distinct from other systems such as CORBA (discussed in the next chapter) in that it is possible to send a complete object from one remote address space to another. This feature makes it possible to not only pass data over the network, but also to pass behavior-complete class definitions can be passes using the magic of the RMIClasLoader and serialization. RMI makes it easy to send a full object graph by passing an object as the argument to a method call. The only requirement for passing an object is that the object be serializable. How is this useful? Passing an object to another address space makes it possible to use the resources of that addres space-CPU cvcles, files, database access, and so on. If the type of computation required by the object is complex, sending it from a slower machine to a faster machine is worth the overhead of transferring the object over the network. NOTE By default, the RMI system communicates between remote address spaces using a custom protocol (the Java Remote Method Protocol) over a standard TCP/IP protocol in March 1998, at JavaOne, JavaSoft demonstrated an implementation of the internet inter ORB Protocol (IIOP) for RMI. This feature should be available soon. As an example of dynamic class loading, we will continue the bank paradigm of the previous examples and apply RMI to the process of obtaining a loan. Although this example is by no means computation instersive and could be easily executed locally the example demonstrates the mechanics of sending an object from one address space to another.

In the example, the client and server both share the definition of an abstract class called loanType. The Loan Type class defines the calculatePayment ( )method, whdich returns a Loan object. On th client side, a subclass of Loan type defines what the culatePayment method should do. The client application requests a reference to a Loan0fficer class, then sends an instance of a Loan Type object to the Loanofficer. Processloan method. This method executes the calculatePayment method of the object passs and returns an instance of a LoanType object. NOTE The LoanOfficer doesn t know in advance what code it is going to run. It depends on which subtype of LoanType it receives.

Although this looks a little like the callback presented in the previous section, in this example, the server application must recreate (through class loading and serialization) an instance of the object passes as a LoanType object before executing the method. The server is working on a copy of the client s Loan Type. NOTE Both the callback mechanism and the dynamic class loading mechanism are triggered by passing objects as arguments to remote methods. The key difference between passing a remote reference (which contains a stub instance)used in a callback versus the serialized instance of an object, is whether or not the object being passes implements the java.rmi.Remote interface, its stub is serialized; otherwise, the object instance is serialized. The Loan-processing example uses the code presented in the following sections, which is also included on the CD-ROM in the directory javadevhdbk\ch12\dynamdic.

Defining the LoanTye Class The Loan Type class is abstract (as opposed to the interfaces used so far) because many different types of loand could have similar data and methods, differing only in how the interest and monthly payment arer calculated for (for example, an adjustable rate mortgage or a ballon payment. List 12.13 Loan Type.java Package bank.loan; Import java. io. Serializable; Public abstract class LoanType implements Serializable Private float monthlyPayment, interestRate; Private int loanAmount, loanDuration; // This method is executed by the server on behalf of // the client. Public abstract void calculatePyament( ); Public LoanType (int amount, float rate, int term) { loanAmount = amount; interestRate = rate; loanDuration = term; } Public void setMonthlyPayment (Float payment) { monthlyPayment = payment; {

} Public float getMonthlypayment( ) { Public float getMonthlyPayment( ) { Return monthlyPyament; } Public int getLoanAmount( ) { Return LoanAmount; } Public float getInterestRate( ) { Return interestRate; } Public int getLoanDuration( ) { Return loanDuration; } }

Defining the ConventionalLoan Class The client defines an instance of a LoanType object by extending the abstract class and providing a method body for calculatePayment. This class, ConventionalLoan, calculates the monthly payment for conventional mortgages. LIST 12.14 ConventionalLoan.java Package bank.loan; Public class ConventionalLoan extends LoanType {

Public ConventionalLoan(int amount,float rate, int term) { Super (amount, rate, term); } Public void calculatePayment ( ) { // Convert the interest rate to decimal percentage Float interesrRate = getInterestRate ( )/100; // calculate the monthly interest rate Float monthlyInterestRae = interestRate/12; // convert the duration of the loan from years in to // months Int number0fMonths = getLoanDuration ( ) * 12; Float pmt = (float) (getLoanAmount()*(monthlyInterestRate/ (1-Math.pow((1 + monthlyInterestRate), -number0fMonths))));

setMonthlyPayment(pmt); } } Creating the LoanOfficer Interface The client requests a reference to a loan0fficer instance from the server application. The LoanOfficer interface defines the processLoan method, which takes a single LoanType argument and returns a LoanType object, from which the client may extract the monthly payment amount. LIST 12.15 LoanOffiece.java Package bank. Loan; Import java. rmi. Remote; Import java. rmi. RemoteException; Public interface loanofficer extends Remote { Public LoanType processLoan(LoanType loan) throws RemoteException; } Implementing LoanOffice Package bank.loan; Import java. rmi. Remote; Import java. rmi. RemoteExcmption; Import java. rmi. Server. UnicastRemoteObject; Public class LoanOfficerImpl extends UnicastRemoteObject Implements LoanOfficer {

Public LoanOfficerImpl( ) throws RemoteException { } Public LoanType processLoan (LoanType loan) throws RemoteException { Loan.calculatePayment( ); Return loan; } }

Setting Up the Server Finally, the server application creates an instance of a LoanOfficerImpl object and registers the implementation with the rmiregistry. LIST 12.17 Lender.java Import java.rmi.Naming; Import java.rmi. RemoteException; Import java.rmi. RMISecurityManager; Import bank.loan.*;

Public class Lender

Public static void main (String args[ ]) { // Create and install a security manager. System.setSecurityManager(new RMISecurityManager());

Try

// Create an instance of our loan officer. System.out.println( Lender; create a LoanOfficr ); LoanOfficerImpl loi = new LoanOfficerImpl( ); // Bind the object instance to the remote registry. // Use the static rebind ( ) method to avoid conflicts. System.out.println( Lender: bidnd the LoanOfficer to a name ); Naming.rebind( loanOfficer , loi); System.out.println( The LoanOfficer is ready to process rquests ); } catch (Exception e) e. printStackTrace( ); System.out.println(e.getMessage( )); } } } {

Setting Up the Client The client application creates an instance of ConventionalLoan, then obtains a remote reference to a LoanOfficer object and passes the instance of the ConventionalLoan to Loanofficer through the processloan method. First, the LoanOfficerImpl will look in its CLASSPATH for the class file. When the cl;ass is not found, it will use the URL supplied in the object s serialized form. This URL would have been set from the client s command line, via the java.rmi.server. codease

property. If the server cannot load the ConventionalLoan class from the cldient-supplied URL, it will fail with a ClassNotFoundException. The client application takes four arguments: the hostname of the server, the amount of the loan, the annual percentage rate (as a float), and the number of year for the life o the loan. LIST 12.18 ConventionalLoanClient.java Import java. rmi.Namint; Import java.rmi.RemoteException; Import java.rmi.RMISecurityManager; Import bank. Loan.*; Public class ConventionalLoanCdlient { {

Public static void main(String[ ] args) throws Exception LoanOfficer officer; ConventioalLoan conv; // Check the command line. If (args. Length < 4) {

System.err.println( Usage: ); System.err.println( java ConventionalLoanClient<server> +

<mortagage amount> <interest rate> + <number of years> ); System.exit (1); }

Int amount = Integer.parseInt (args[1]); Floate rate = (new Float (args[2])). Floagtvalue(); Int length = Integer.parselInt (args[3]); // Create a new loan instance. Conv = new ConventionalLoan (amount, rate, length); // Create and install a security manager. System.setSecurityManager(new RMISecurityManager()); // Obtain reference to laon officer. Try { String url = new String ( // + args[0] + /loanOfficer ); System.out.println ( Conventional Client;lookup loanOfficer, + url = +url): Officer = (LoanOfficer)Naming.lookup(url); } catch (Exceptyion e) {

System.err.println( Error in getting loan officer +e); Throw e; System.exit(1); } // Get the monthly payment. Try { // Use the existing reference to get back

// the changed instance information. Conv = (ConventionalLoan) officer. processLoan(conv); Sysgem.out.printLn( Your monthly payment will be + Codnv. GetMonthlyPayment()); } catch (Exception e1) { System.err.println( Error in processing loan +e1); Throw e1; } } }

Running the Loan-Processing Application So far, the example illustrated in this chapte have made use of two (or three, if you count the rmiregistry) JVMs running on the same host with the same CLASSPATH variable set. For ths example, in order to illustrate that the classes are actually loaded over the network, the rmiregistry, server, and client will be isolated from each other through three steps: y The Server classes (including the stub classes created by rmic ) will not be physically located in the sme directory as the client application. y The client class to be uploaded to the server (ConventionalLoan) will not be in the same directory as the server. y The registry will be complently isolated from both the client and the server. In order to load classes dynamically, the client and server applications must create and install an instance of an RMISecurityManager, because the RMIClassLoader required that a security manager be installed.

Furthermore, the client and serve must declare the URL path to the classes the they are serving in order for application running in other JVMs to find these classes. The server will be serving the stub class for the LoanOfficer IMPl, and the client will be serving the ConverntionalLoan class definition. To prove that the client s ConventionalLoan class and the server s stub classes are actually transferred between JVMs, do not set the CLASSPATH variable and start the rmiregistry in a directory isolated from the client and server. WARNING If The rmi registry can find the class definitions locally, it will ignore the java.rm.server.codebase property set from the command line. This is a problem because other JVMs will not be able tyo download th class definitions. From the command line, enter: C:\> start rmiregistry Start the server application from the server directory-again, without setting the CLASSPATH variable. The sever must let the registry and the client know where to load classes that are being made available by the server, so set the java, rmi.server.codebase property. From the command line, type: C:\RMI\agent\server>java -Djava.rmi.server.codebase=file:/RMI/agent/bank.loan.lender NOTE The java.rmi.server.codebase property requires forward slashes to separate the directory names (of the path), and there must be a trailing slash on the last directory.

The OutPut from the srver looks like this: Lender: create a LoanOfficer Lender: bind the Loanofficer to a name The LoanOfficer is ready to process requests Start the client application from the client directrory again,do not set the CLASSPATH variable. The client must let the servr know where the Conventional Loan class is located, so the client application also sets its codebase property: C:\RMI\agent\client> java -Djava.rmi.server.codebase=file:/RMI/agent/client/bank.loan .ConventionalLoanClientgus 250000 7.25.30 This example shows a $250,000 mortgage at an annual percentage rate of 7 for 30 years, on a server named gus .

Object Activation In previous versions of RMI, in order to obtain a reference to a remote object, the server that generated the instance of the object had to be running (live) in a JVM. This simple mechanism is sufficient for most applications. However, for large systems that create a number of objects that are not used at the same time (or some objects that are not used at all), it is useful to have a mechanism to suspend those objects until they are needed. The activation mechanism in Java 2 provides this facility. Activation allows a java object to be bound (named by the registry)na dthen activated at some later date simply by referencding the object through the registry. One of the primary benefits to this approach is that the application that create the instance of the remote object can terminate or exit normally

before the object is ever used. They ability to activate remote objects on request allows RMI system designers much greater flexibility in designing smaller servers. In order to make activation work, the RMI team created another daemon process, the Java RMI Activation System Dadmon (rmid). The process of finding an object reference is illustrated in Figure 12.2

The rmid process must be run first, through the command line: C:\> start rmid By default, rmid will start on port number 1098 (rmirgistry is on port 1099), but you can spedify and alternate port: C:\>start rmid port 2001 To demonstrate the object activation feature, we will extend the loanprocesing example presented in the previos section by activation LoanOfficer to approve the mortgage loan application. The client side of this example is just like any other RMI client class, since the client requests a remote reference and has no idea that the object is activatable dor running as a standard UnicastRemoteObject. The server side however is very different, since the server must register the activatable object with the activation system before it terminates. The extended loan-procesing example uses the code presented in the following sections, whdich is also included on the CD-ROM in the directory javadevhdbk\ch12\activation. NOTE Since the server is not run again when the object is activated, the term server does not really apply, and thus the RMI team came up wth the term setup, which better defines what the activation application does before it exits.

Modifying LoanOfficer To simplify the example and focus on the elements that make an object activatable, the LoanOfficer interface now defines a single method isApproved which takes a single argument-aLoanApplication object-and returns a Boolean result. LIST 12.19 LoanOfficer.java

Package bank.laon; Import java. rmi. Remote; Import java. rmi. RemoteException; Public interface Loanoffice extnds Remote { Public Boolean is Approved (LoanApplication app) Throws RemoteException; }

Implementing LoanOfficer and Extending Activatable The LoanOfficerImpl class implements the LoanOfficer interface and extends the Activatable class instead of UnicastRemoteObject. Note that there is an additiona constructor that could be defined for an Activatabele class, but this one constructor is all that is necessary for thi example. Like the UnicastRemoteObject examples seen earlier, an Activatable class needs only to implement a remote interface and to be exported to accept incoming method requests. By extending java.rmi.activation. ACtivatable, the LoanOfficerImpl class is exported automatically upon construction, but any class (except those that extend UnicastRemoteObject or Actibatable ) may be exported by using the static method, Activatable.

exportObject, as java.rmi.Remote. LIST 12.20

long

as

it

directly

or

indirectly

implements

LoanOfficerlmpl.java

Package bank. Loan; Import java .rmi. activation. ActivationID: Import java. rmi. MarshalledObject; Import java.rmi.RemoteException;

Public class LoanofficerImpl extends Activatable Implement LoanOfficer {

Public Loanofficerimpl(ActivationID id, MarshalledObject data) Throws RemotException {

// Register the LoanOfficrImpl with the activation // daemon and export it on an anonymous port. Super(id, 0); } Public Boolean isApproved(LoanApplication app) Throws RemoteException { // Here , some other process would determine wheter the // customer was approved for the loan. // For now, we ll let everyone be approved! Return true:

} } Creating the Activation Setup Class The setup class, a rewritten Lender class, is a bit more complex than the serve class for a UnicastRemoteObject; however, it is liketly that this mechanism will be simplifies in future releases. The Lender creates an instance of a URL object that represents the location of the activatable class, LoanOfficerImpl. An ActivationGroupID is passed to the ActivationDese object, which is registered with rmdid. Each ndew JVM that is started by rmid will activate objects for only a single ActivationGroupID. If a JVM is already running that is associated with this class s ActivationGroupID, then this oject will be created in that JVM rather than starting a new JVM. The activationGroup ID gives greater control over which JVM the activated object runs in. Next, the static method Activatable. Register passes the ActivationDese up to rmid. The activation group descriptor is all the information that rmid will need to create an instance of the Activatable class. The Activatable. Register method returns a remote reference that is then used to register the Activatable class with the rmiregistry. The setup class, Lender, then explicitly exits with System. Exit. LIST 12.21 Lender.java

Import java. net . URL; Import java. rmi. Activation. Activatable; Import java. rmi. Activation. ActivationDese; Import java. rmi. Activation. ActivationGroup; Import java. rmi. Activation. ActivationGroupDesc; Import java. rmi. Activation. ActivationGroupID;

Import java. rmi.MarshalledObject; Import java. rmi.Naming; Import java. rmi.RemoteException; Import java. rmi.RMISecurityManager; Import java. security.CodeSource; Import java. security.jPublickey; Import java. util.Proprties; Import bank.loan.*;

Public class Lender

{ {

Public static void main (String args [ ]) If (args.length < 1) {

System.out.println ( Usage; java bank.loan.Lender <absolute path to class fils> ); System.exit ( 0); } // Create and install a security manager. System.setSecurityManager(new RMISecurityManager()); Try { // Create an instance of our loan officer. System.out.println( Lender:create a LoanOfficer ); URL whereTheClassFilesIs = new

URL ( fie: +args[0] / ); // These are required for Java 2 Beta 3 Publickey [ ] mySecurity = null; CodeSource direction = New CodeSource(whereTheClassFilesIs, mySecurity); Properties env = (Properties) System.getproperties ( ).clone( ); ActivationGroupID groupID = ActivationGroup.getSystem( ).registerGrop( New ActivationGroupDesc(env)); // Marshaled object is typically used to tell the activated // object where to find its persistent data. // Right here it is unused, but required for the // ActivationDese MarshalledObject commandlineInfo = null; ActivationDesc ad = New ActivationDesc (groupID, bank.loan. LoanOfficerImpl , Directions, commandLineInfo); // Register the activatable class with rmid. LoanOfficer lo = (LoanOfficer) Activatable.register(ad); System.out.println( Registered with rmid );

// Bind the object instance to the remote registry. Use the // static rebind( ) method to avoid conflicts. System.out.printl;n( lender: bind the LoanOfficer to a name ); Naming.rebind( loanOfficer , lo); System.out.println( The LoanOfficer is ready to process requests ); } catch (Exception e) { e.printStackTrace( ); System.out.println(e.getMessage()); } // The work is done, now exit the program. System.exit(0); } } On the client, the LoanApplication object is passes to the LoanOfficer object. The LoanApplication is a simple class that is constructed with the customer s social security number and the loan amount.

LIST 12.22

LoanApplication.java Package bank.loan; Public class LoanApplication implements java.io.Serializable { Private String ssn; Private int loanAmount; Public LoanApplication(String loanInfo, int amount) {

Ssn =loanInfo; loanAmount = amount; } Public String getApplicatnt( ) { Return ssn; } Public int getRequestAmount( ) { Return loanAmount; } } The client crates an instance of a LoanApplication and requests a Loanofficer reference from the registry.

LIST 12.23

LoanClient.java Import java. rmi.Naming; Import java. rmi.RemoteException; Import java. rmi.RMISecurityManager; Import bank.loan,*; Public class LoanClient { Public static void main(String[ ] args) throws Exception { LoanOfficer officer; LoanApplication app; // Check the command line.

If (args. Length < 3) {a System.err.println( Usage: ); System.err.println( java LoanClient <server> + <social security number> <mortgage amount. ); System.exit (1); } String applicant = args[1]; Int loanAmount = Integer.parseInt(args[2]); // Create the LoanApplication instance. App = new LoanApplication(applicant.loanAmount); // Create and install a security manager. System.setSecurityManager(new RMISecurityManager( )); // Obtain reference to loan officer. Try { String url = new String ( rmi:// + args[0] + /loanOfficer ); System.out.println ( LoanClient: lookup loanOffice, + url = url); Officer = (Loanoffiecer)Naming.ollkup(ur); } catch (Exception e) { System.err.println( Error in getting loan offier + e); Throw e; }

// Get the loan approval. Try { Boolean approved = offiecer. isApproved (app); System.out.print( Your request for + loanAmount+ was ); If (!approved ) { System.out.print( not ); System.out.print( not ); } System.out.println( approved! ); } catch (Exception e1) { System.err.println( Eror in processing loan = e1); Throw e1; } System.exit(0); } } The registry looks up the LoanOfficer object that was registered by the setup application and returns to the clint a remote reference that contacts rmid to create an instance of the class.

Summary Java s persistent object support provides a very useful facility for storing and reconstitution objects. This feature is valueable in its own right; moreover, it plays an essential role in remote object invocation by providing a

Java-standard protocol for reading and writing objct data to and from I/O streams. While successful RMI programming involves a number of steps, the infividual steps ae not difficult. The examples presented in this chapter provide a template for your ow development efforts. While RMI is constantly compares to CORBA as a distributed object technology, it is important to bear in mind that RMI is capable of sending a full object data graph from one remote JVM to another. This is a feature that is not available in standard CORBA implementations. Furthermore, RMI systems are becoming more widely integrated as customers find that RMI is easier to develop and understand than CORBA. With the addition of activation and the future integration of the IIOP protocol, RMI is well positioned to continue as an inexpensive and powerful tool for creating object frameworks. The next chapter discusses CORBA, IIOP, and Java IDL in detail.

CHAPTER THIRTEEN Java IDL and CORBA Connectivity

y y y y y y

Heterogeneous environment problems An introduction to CORBA An introduction to IDL CORBA service development Mapping language from IDL to Java Legacy code wrapping

Java IDL, which was introduced with release 1.2 of the JDK, provides an implenment of the CORBA 2.0 (Common Object Request Broket Architecture) specification. CORBA is a distributed framework designes to support heterogeneous architecture. With CORBA, it is possible to connect two systems that differnot only in their hardware (CPU and memory ), but also in their operating systems and programming languages. This chapter begins with a discussion of the dproblemf that CORBA was designed to solve .Then it covers the CORBA components and IDL, and examines how to develop CORBA services. After the examples, we ll go into some of the details of IDL-to Java language mapping. Finally, we ll describe how legacy code wrapping works.

The Compatibility Problem CORBA was created to solve a common problem for most large companies. This problem is that there are different computer systems at work within the company. For example, the graphics department may have

Macintoshes running MacOs, the engineering department may have Sun workstations running Solaris, and management may have PCs running either Windows 95 or NT. In addition to the operation of the company. Traditionally, computer manufactures have attempted to solve the compatibility problem of a heterogeneous environment by creating a line of products that reaches into all areas of a company s business. For example, a single vendor may offer a low-end sysgem, a graphics system, and a high-end server system. This can sometimes solve the problem of compatibility, but it also is costly and leads to vendor dependence; the company must commit to spending more money on a single vendor s solution. A Heterogeneos Environment Case Study In order to understand why companies frequently have heterogeneous environments. Let s consider the case of a fictional book publishing company, Sullivan Publishing. Since the early 1900s, Sullivan Publishing has printed and bound books, all by hand, The initial plant was little more than a small warehouse with several bulky manual printing presses and a leather cutting table for tha book covers. Over the next 70 years, the business grew, so Sullivan Publishing moved into larger quarters and bought automatic printing presses and binding machines. As the Company grew, so did the quantity of data associated with book inventores and production and marketing costs. In order to remain competitive, the company needed an information system that would support its manufacturing and inventory goals. The Mainframe s Roe During the 1970s and 1980s, the company purchases a large mainframe computer and hired a group of programmers to write and maintain programs to translate the publisher s business process into computer applicatons:

y Management used programs to produce reports that could be used to evaluate the information compiled by the computer and to make decisions based on that information. y The Production group used programs to track the costs of raw goods and to decide when to buy quality products from paper and ink dealers, so inventory did not sit idle on shelves for too long. y The marketing group used programs to analyze readership trends and to ensure that specific target markets were not missed. y The graphics department created programs that helped the designers standardize logos and product branding, and used other programs to produce the books cover artwork. It is important to note that the purpose of the mainframe computer was to provide the decision-makes in the company with tools to maintain and expand the business. The computer, the operating system, and the programming language(s) used to develop the programs were irrelevant to the real purpose of the system, which was to make more money for Sullivan Publishing. The Evolution of The PC and the Network As tidme went on, two events in the devolution of computer technology brough changers to Sullivan publishing s computer system. The first event was the evolution of the PC as an inexpensive business computer. The PC made it possible for a single department within the company to make relatively small purchases (compared to the mainframe) of computer equipment that would have no impact on the mainframe environment. The local PC resources provided an attractive alternative to the terminals attached to the mainframe-more programs, better performance, local storage, and better games! The second evolution was the network, which allowed companies to tie their different computer resource together and to share files and data. The network was technically capable of connecting disparate systems bcause the protocols for the network were designed as standards, independent of a

computer s hardware or operating system. This is important because without the network there is no concept of a distributed software architecture. Figure 13.1 illustrates Sullivan publishing s network. Unfortunately, the dream of sharing information between different systems proved difficult and expensive to implement. Programs could share data only if the data was properly formatted to the computing environment that used it. Computer companies were not interested in the data needs of a printing company, and they developed standards for data formats suited for their own hardware and operating systems. Thus, data and files from the mainframe word processor were dincompatible with the word processing programs on the PCs. Modern Challenges So now we come to the challenges of the late 1990s. First, the company s managers would like all of their computers to seamlessly be able to share information. Second, they would like to offer an online buying service. Sullivan Publishing has evaluated several alternative proposals from a variety of computr vendors. Each vendor promises to integrate the compnay s business onto a single platform that would make the computers work together as a system again. However, each vendor s proposal involves significant rewriting of the existing code base in addition tod the purchase of new hardware. Migration to the Network-Centric Model The dilemma of the hypothetical publishing company is very common in many real companies, although perhaps not as severs. The short-term costs of a migration to a desktop-centreic omputing model are lower than the initial mainframe costs, but such a solution leads to incompatibilities between systems because they are heterogeneous in nature. What companies with heterogenros systems would really like to do is invest in a new software framework that allows them to leave the existing hareware intact and migrate exisitning software toward a network-centric model, where

each computer system is part o the overall business. System, Companies want to move applicationsand ystems toward a central model that emphasizes a common look at the business application, regardless of the operating system and programming language the application requires. Furthermore, companies would like to be able to use the current legacy code in its current state, until all of the code can be understood, documented, and rewritten for more modern hareware.

An Oerview of CORBA Several year ago, a group of engineers decided to form a consortium of their respective companies and design a reusable sysem that would enable multiple programming and operating system environments to work together. These engineers formed the Object Management Group (OMG). Working together, the OMG members have developed several hundred pages of specifications that define a framework of reusable components. The specification covers the arvhitectural elements that are required to allow one hareware and software system to communicate with another. The OMG is now a consortium of more than 800 companies, and CORBA is the framework that is the estlf of their work. A framework is a reusable collection of code that is almost ready-to use, which means that with some customization, it can be applied to specific implementations. The CORBA framework is designed to make communication between remote address spaces easier to implement. The primary goal of CORBA is to provide software developers with a means for developing systems that do not rely on a single operating system, programming language, or even hardware acchitecture. CORBA by itself is not a product that you can buy from a store. The CORBA standard defines how companies can create implementations of the standard. You can purchase implementations from companies like Ione Technologies and Visigenci (now part of Borland).

A CORBA implementation is composed of several pieces, depending on the vendor s individual application of each standard. A typical CORBA vendor will supply the following components: y An Object Request Broket (ORB) implementation y An Interface Definition Language (IDL) compiler y One or more implementations of Common Object Services (COS), also known as CORBAServices y Common Frameworks, also known as CORBA y Facilities The Object Request Broket (ORB) The primary mechanism for connecting objects in different address spaces is a function of the ORB. You can consider the ORB to b an object bus or object pathway. When two CORBA systems with t communicate between different address spaces, the ORB takes care of making sure theat regardless of the hardware, operating system, and software development language used, the remote object invocations will success. Figure 13.2 illustrates how an ORB connects objects between a client and a server. Typically, an ORB is implemented in one of two ways: y As a library of objects that form an extension of the CORBA runtime y As a daemon process In either case, the ORB is responsible for establishing communications with the remote system, marshaling parametyers to make remote calls, and managing concurrency of simulataneous requests from multiple clients.

Common Object Services (COS) and Common Frameworks The ORB does not make up the entire CORBA implementation. Common Object Services such as the following are developed to assist th ORB:

y The Naming Service provides a way for CORBA clients to fifnd objects on the network. An implementation server registers an object with a Naming Service using a hierarchical representation similar to a path used by a filename. Clients can request a reference to the object by name, using the Naming Service. y The Event Service allows a client or server to send a message in the form of an event object to one or more receivers. Objects can request to listen to a specific event channel, and th Event Service will notify them fo an event on that channel. The Event Service will store events before delivering them, so that clients and servers do not need to be connected. y The Security Servic provides a means to authenticate messages, authorize access to objects, and provide secure communications. y The Transaction Services defines a means to control an action against a database or other subsystem. The Transaction Service allows clients and servers to commit or roll back a transaction, even when the transaction affets multiple databases. Currently, there are a total of 15 services. Along with those listed above, the services are Persistent Object Service, Concurrency Control Service, Life Cycle Service, Relationship Service, Externalization Service, Query Service, Licensing Service, Property Service, Time Serice, Object Trader Service, and Object Collection Service. In addition to the Common Object Services, there are Common Frameworks. The Common Frameworks define application-level services, typically for vertical markets, such as Oil and Gas, Transportation, and Doucment Preparation, Currently, the majority of the specifications for these frameworks are in review, but few vendors have developed services that support portions of these specifications. An Overview of IDL and IIOP The ORB, Common Object Services, and Common Frameworks would be difficult for any one vendor to implement if where were not some standard way to define the interfaces that each of these elements requires. The

definitions of the interfaces in CORBA are created through a set of language constructs that are specified by the Interface Definition Language (IDL). Additionally, the CORBA 2.0 specification introduced the Internet InterORB Protocol (IIOP) standard that specifies how ORBs communicate over networks. IDL Definitions IDL provides a programming-language neutral way to define how a service is implemented. Th constructs that make up IDL are syntactically similar to C and C++ (and even Java), but they cannot be compiled into a binary program directly. Instead, IDL is intended to be an intermediary language that defines the interfaces that a client will use and a server will implement. IDL is best thought of as a contract between the system that makes use of an object and a system that implements an object. A developer creating a CORBA system, models a system using IDL to define the interface that the system will support. This model is an abstract representation of the actual system. For example, the following is a simple IDL file: Module Calculator { {

Interface Functions

Float square_root ( in float number ); Float power (in float base, in float exponent); }; }; This IDL file describes two function keys on a calculator. A square root function and a power function (a number raised to a power). The definition of these function is abstract- there is no code describing the implementation of these function, nor is there any definition of the language to be used to implement the functions.

This IDL specification is compiled using a tool that creates code for the specific operating system and programming language that the developer needs. Currently, CORBA vendors support C,C++, Java, SmalTalk, and Ada. Some Companies have their own implementations of other languages such as COBOL. We ll cover the Java mapping of the most useful IDL construct later in this chapter. NOTE IDL files are compiled, but this is really a misnomer and illustrates the limited nature of computer terms. An IDL file is actually translated from the general constructs that make up IDL to specific programming language constructs (like C, C++ or java). However, the files generated by the translation process are not complete; they require the implementation details, which the developer must full in. IIOP Communications The IIOP is a TCP/IP implementation of the General Inter-ORB protocol (GIOP). The GIOP specification defines how ORBs communicate, includidng how messages are sent, how byte ordering is done dor integer and floatingpoint numbers, and how parameters are marshaled for remote object einvocations. NOTE While not a CORBA component per se, IIOP compatibility is required of CORBA vendors who wish to advertise that they are 2.0 compliant . The IIOP specification has proably done more to further the cause of CORBA than any other specification. Without IIOP, CORBA vendors are free to implement their own ORB communication protocols, effectively creating a vendor lock-any additional service would need to be purchases from the single vendor. With CORBA, it is possible to build a client application using one vendor s ORB and IDL compiler, build a sever or object implementation with a second vendor s ORB and IDL compiler,and create a set of common services for both client and server with yet a third vendor s ORB and IDL compiler. The

IIOp allows each of the three different vendrs products to communicate with each other using a standard set of protocol emantics. (And when you consider that all three of these ORBs could be using a different programming language ad running on a different hardare and operating system platform, you get he idea that CORBA is pretty cool!)

A Working CORBA System Now that we ve introduced the CORBA components and specifications, let s see how each of these is used to develop a working CORBA system. Java IDL is now part of the Java 2. The current release includes a 100% Pure Java ORB, a set of API, and a Naming Service (tnameserv) that follows the COS Naming Service specification. An IDL compiler (idl tojava) is available separately. Java IDL is CORBA 2.0 compliant, so it also communicates with any other HOP(version 1.0) ORB. The description here applies in particular to Java IDL, but theprocss will be similar in most other CORBA implementations. The process of creating a CORBA sysem starts with the development of a design, or the outline of what functionality the system is to provide. From there, the design is translated into objects that provided the functionality required by the design. Thes objects are expresses in terms of IDL interfaces and collected into related modules. The IDL file(s) is then compiled to generate stub and skeletons provide interfaces to object implementations that servers will provide. Once the IDL file is compiled, object implementations are created from the fifles that are generated, and a server application is created to provide a means for publishing the object references by name through the Naming Service or through their Interoperable Object Reference (IOR). The client application requests a reerence to an object through the Naming Service by anme and is returned a reference to a generic CORBA object. This object reference is narrowed (like Java casting) to a reference that is actually the stub representation of the remote CORBA object.

The IDL File CORBA objects are first describes by their interface in an IDL file. A CORBA object is also known as a service. CORBA services provide operations that may or may not return result(s). NOTE Actually, you could develop a CORBA application with out using IDL. In fact, there are CORBA products that allow the developer to creae java and C++ code fro a visual development tool skipping over the creation of IDL files. However, an IDL file provides a road map for the development of a sound CORBA system, forcing the developer to think through the problem before generating any execuatable code. The IDL file also provide written documentation of the c reation process and preserves the software design investment. An IDL file from 1998 will continue to provid insight into the design of a system long after CORBA is transformed into a new software paradigm. There is no concept of data in an IDL definition, because IDL interface definitions of services are true object-oriented descriptions. The data is not shown because it is always private and accessed only by an operation, which is public. For example, consider our sample IDL file: Module Calculator { Interface Function { Float square _ root (in float number); Float power ( in float base, in float exponent); }; }; Functions is a CORBA service (encapsulatd in a package or library called calculator) that describes two operations, square _ root and power. An IDL

compiler will generate languge-spcific files, depedndidng on the purpose of the compiler. For example, The IDL compiler for Java IDL will generate Java files. Stubs and Sketetons The names of the files generated by the IDL compiler depend on the contents of the IDL file and the IDL compiler used. In our sample IDL file (shown in the previous section), a package directory Calculator is generated and a Java interface file named Functions. Java is generated in the Calculator directory. Functions. Java contains an interface declaration for the two operations. Other generated files include stub and skeleton files. Stub files are used by client code to communicate with remote CORBA objects. Skeleton files are used by the ORB to make up-calls to server object implementations. Both stub and skeleton classes extend a common ORB class that allows these two objects to communicate. Both client and server applications utilize the Naming Service (tnameserv) to provide information about the remote object that is requested and served, respectively. Figure 13.3 illustrates how stubs and skeletons are used in a CORBA application. When the server is started, it creates or is passes on object that is to be referenced. This object implements the operatiosn deines in the IDL file; in our example, it provides method bodies for the square _ root and power methods. The Java class that provides the implemenatation of the operations defined in the IDL interface Functions also extends to this object with the Naming Service . The client requests a reference to a remote object through the Naming Service. The reference that returned is passes to a stub object. The client then invokes methods through the stub references as if the object were local to the client. The stub, in turn, passes requests to the skeleton reference obtained through the Naming Service.

CORBA Servers The Naming Service provides a reference to a CORBA object provided by a server. There are two type of CORBA objects: transient and persistent. Transient objects have the same lifetime as the server that created them as long as the server is running, the object is availabl . Pesisgent objects do not require a running server. If a request is made of an object that is not available because the server that created the object is not running, an ORB daemon will start the appropriate server to activate an object and return its reference. As of this writing, Java IDL provides only transient servers, but Java IDL clients can access persistent servers provided by other CORBA vendors. Static Versus Dynamic Skeletons CORBA servers can refer to object implementations either statically or dynamically. In both cases. Client requests are not sent directly to the object implementation, but instead pass through a skeleton. The skeleton provides methods for handling the order of arguments passes to the method invocation on the object it represents and provides methods for marshaling results to be passes back to the stub. Static skeletons are generated directly from the IDL interface declarations. These are the easiest to create because the order of the arguments and their type is known in advance (at compile time). Dynamic skeletons are more flexible, allowing method invocations on an object to be handles dynamically at runtime. By default, the java idl compiler generates skeletons that use java IDL s dynamic skeleton interface (DSI). The use of the DSI skeletons is transparent; the client still makes calls to the operations declarations declared in the IDL interface declarations. Subclasses Skeleton Classes versus Ties With Java IDL, you can connect the skeleton interfaces with the actual object implementation in two wazys. One way is to inherit skeleton methods directly, by subclassing the skeleton class generated by the IDL compiler. This approach is straightforward-each IDL interface method has a direct correlation to a sekeleton method.

However, for some applications, you may want to reserve the superclass slot for another class, particularly in instances when the classes that are being wrapped by the CORBA skeleton classes already exist. In this case, another class may be used in between the skeleton and the implementation that delegates the method calls to the appropriate implementation class. These delegation-bases skeletons are referred to as Ties. Java IDL provides a mechanism for creating a Tie implementation by simply specifying the ftie flag to the idltojava application on the command line. CORBA Clients A client application invokes methods on CORBA objects. In order to invoke a method on a CORBA object, the client must know what methods are available and what arguments each method takes. A client can be written with static or dynamic method invocations. Static method invocations are the easiest to write because they are generated and type- checked at compile time. A static invocation uses the methods declared by the Java intraces generated from IDL interface definitions. Dynamic method invocations are more flexible. They allow the client to discover the object definitions at runtime. However, dynamic method invocations do not type-check arguments, so it is the responsibility of the client to make sure that arguments are valie. Dynamic invocation also requires that the server supports an interface Repository. The Interace Repository is used to provide the client wit method names, types, and argument lists. As of this writing, Java IDL does not provide an Inteface Repository, although Java IDL clients can access the Interface Repository provided by another ORB. The methods org.omg.CORBA.Object.get _interface will throw an exception if the server side is implemented in Java IDL, but it will return a valid reference if the server is another ORB.

The Object Adapter Some CORBA implementations support the concept of an Object Adapter. The Object Adapter is responsible for creating server objects and returning the object reference (object ID). The Object Adapter is only used on the server side. CORBA specifies that at least one Basic Object adapter is only used on the server side. CORBA specifies that at least one Basic object adapter (BOA) is supported. However, the current specification for the BOA is quite vague, so there are different semantic for the implementation of the BOA from vendor. These differences have made it difficult to port server-side code from one vendor s implementation to another. The OMG recently releases a new specification, deprecating the BOA and replacing it with the Portable Object Adapter (POA). This new specification carefully carefully defines the requirements for a POA, making it possible to move server-side code from one vendor s implementation to another. The POA is described in the IDL and will be instantiated as a CORBA object. As of this writing, the POA is still in the specification phase and has not yet been implemented. Java IDL currently supports only transient object servers, and therefore does not implement a BOA; instead, a simplifies object adapter for transient objects is built into the Java ORB class. A Simple CORBA Service As described earlier, CORBA services ae expresses in terms o IDL interfaces. The Naming Service is actually an IDL file that describes the interfaces requird to provide this service . To introduce how java IDL is used, we ll develop a simple CORBA service. There are ten basic steps to developing the CORBA service: 1234Create an IDL file that represents the interfaces service: Compile the IDL file using idtojava. Compile the generated classes using javac. Create a implementation class.

5- Create the implementation server. 6- Create the client application (or applet). 7- Compile the implementation, server, and client code. 8- Start the Naming Service application, tnameserv. 9- Start the server (which registers with the Naming service). 10Start the client.

WARNING The most important of these steps is the first, but many developers spend too little time in design. One of the drawbacks to a flexible framework is that the design of the framework is what drives the implementation. Changes that are made to the implementation are not reflected in the IDL file automatically. Furthermore, tools for converting an implementation back to IDL are not provided by most CORBA vendors The steps abd the code for the CORBA service example are described in the following sections. The full code is also on the CD-ROM in javadevhdbk\ch13. Creating the IDL File For our example, we ll use the same sample IDL fifle presented in earlier sections: Module Calculator { Interface Functions {

Float squar _ root ( in float number); Float power (in float base, in float exponent); }; };

In this IDL file, an IDL interface named functions is enclosed in the naming ecope of a module named Calculator.The IDL interface Functions describes a single service tha contains wo operations: squre _ root and power. The square _ root operation takes a single float result. The operation power takes two floate arguments passes by value, and returns a single float resut. The service Function is enclosed in the Calculator naming scope. (We ll discuss the semantics o Java IDL in the IDL to Java Language Mapping section late in the chapter.) Compiling the IDL File For this example, assume that our sample IDL fie is in a file named calc. idl. To compile the IDL file, us the idltojava compiler. Idltojava fno cpp cale. Idl The fno cpp option is used to turn off C/C++ preprocessing. This option is useful only if you plan to add preprocessing commands to your files. Other options are decribes in the document jidlcompiler.html,which is shipped with the idltojava compiler. The IDL compiler uses the constructs specified in the IDL file to generate specific Java files and directories. The module construct is used as a package specification, and the interface contruct is used as a Java interface definition. In our sample IDL file, the package name is Calculator, and the Java interface file generated is named Functions.java. The Java IDL compiler generates the following files for this example: Calculator Functions The directory/package creaded by the moudule declaration. A Java interface that declares the oprations and methods. A class that implements the Functions interface and Provides a single class that the implementation class Can extend. _FunctionsStub Another class that implements the Function interface.

_FunctionsImplBase

This class is extended by the client class to access the Methods declared in Functions. FunctionsHolderd A utility class provided to allow client applications to Pass a Functions object as a value to the server. It is not needed in this example. FunctionsHelper Another utility class that the client uses to classify Object references received from the servr as Functions objects.

Compiling the Generated Classes The idltojava IDL compiler generates only Java source code, so the generated classes must be compiled. The nice thing about this step is that none of the generated classes will throw compilation exceptional! To compile the generated classes, use the following compiler command: Java calculator\ *.java

Creating the Implementation Class The next step is to provide a Java class that implements the Java interface generated by the IDL computer. It is recommended that the physical location of the classes that you create remain separate from the generated classes. The generated classs are in the Calculator directory already, so the crated clases can be created on directory leve above them. Java IDL provides a file that makes this step easy. The _FunctionsImplBase.java file is an abstract class file that extends org. omg.CORBA.DynamicImplemention and implementation methods.

The implementation class must provide method bodies for the interface methods described by he Functions interface (generated from the IDL file calc.ifl). LIST 13.1 /* * file: /calculator/Functions.java *from: calc.idl *Date: Wed Dec 31 13: 44: 56 1997 *By:C:\JDK1~1.2BE\BIN\IDLTOJ~1.EXE Jaa IDL 1.2 Nov 10 1997 *13: 52:11 */ Package Calculator; Public interface Functions Extends org.omg. CORBA.Object { Float square _ root (float number ); Float power (float base, float exponent); } NOTE As of JDK 1.1 all methods defined in an interface are implicitly public. Therefore, the implementation class must provide methods for the square _ root and power methods. By convention, the implementation class adds an Impl suffix to the interface name. The implementation class created is shown below. Functions.java

LIST 13.2

Functionslmpl.java

// Implementation file for the Functions interface Package Calculator; // First, extend the Implmentation Base class Public class Function Impl extends _ FunctionsImplBase // A constructor is not required, but is recommended Public FunctionsImpl ( ) { } // Implement the two special methods Public float square _ root (float number) { Return (float) Math.sqrt ( (double) number); } Public float power (float base, float exponent) { Return (float)Math.pow ((double)base, (double) exponent); } } This simple implementation returns a square root using the sqrt ( ) method and the pow( ) method of the java.lang.Math class. Note that these methods take double type arguments and return a double as a result, so the arguments and the results of the methods should be cast to a float. {

Creating the Implementation Server The next step is to create a server class that will register the implementation object with the ORB and Naming Sevice and provide the Connection to the implementation class implementation class. Like the implementation clas, this Java class is not generated by the idltojava compiler. LIST 13.3 CalculaorServer.java // The Calculator Server class Import Calculator.*; Import org.omg.CosNaming.*; Import org.omg.CosNaming.NamingContextPackege*; Import org.omg.CORBA.*; Public class CalculatorServer { Public static void main(String args[ ] ) { Try{ // Create and initialize an instance of an ORB ORB orb = ORB. Init(args, null); // Create implementation object and register with ORB FunctionsImpl fRef = new FunctionsImpl ( ); Orb.connect (fRef); // Get a handle to the name server Org.omg.CORBA.Object objRef = Orb.resolve _ initial_ references ( NameService );

NamingContext ncRef = NamingContextHelper.narrow(objRef);

//Bind the object reference in Naming NameComponent nc = new NameComponent ( calc , ); NameComponent path [ ] = {nc}; ncRef.rebind(path, fRef); // Wait for invocations from clients Java.lang.Object sync = new java.lang.object ( ); Synchronized (sync){ Sync.wait ( ); } } catch (exception e) { System.err.println( ERROR: +e); e.printStackTrace(system.out); } } }

The server code creates and initializes an ORB object, then creates a reference to the object implementation FunctionImpl. The server must publish the object reference to the naming sevice in order for the object to be located. The name of the object reference is arbitrary and formed by creating a naming scope, similar to a filename and path. In our example, the FunctionsImpl reference is named Calc and is a top-level name. Finally, the

server waits (indefinitely) for an object request (through the newly created ORB reference). This server is an example of a transient object server; the object reference and the ORB require that server application to remain running. Creating the Client Application The client application will locate a reference to the Funtions object using the Naming Service. The object reference returned is a CORBA object reference that must be cast or narrowed to the appropriate reference type. The server published the name of the reference as Calc , so this is the object reference that the client will rquest of the Naming Service. LIST 13.4 CalculatorClient.java // Calculator Client Import Calculator.*; Import org.omg.CosNaming.*; Import org.omg.CORBA.*; Public class CalculatorClient { Public.static void main(String args[ ] ) { Try { // Create and initialize an instance of an ORB ORB orb = ORB. Init (args, null); // Get a handle to the name server Org.omg.CORBA.Object objREf = Orb.resolve_initial_ references ( NameService );

NamingContext ncRef = NamingContextHelper.narrow (objRef); // Look up the object bound to the name Cale NameComponent nc = new NameComponent ( Cale , ); NameComponent path [ ] = {nc}; // Use the Helper class to cast the generic CORBA object // reference to a Functions implementation. The object returned // by the narrow method is actually a _ FunctionsStub object object // that implements the methods in the Functions interface Functions fRef = fufnctionsHelpeer. Narrow (neRef.resolve(path)); //Use the reference to execute the interface methods Float sqrt = fref.square _ root (10f); Float pow = fRef.power (2f, 8f); System.out.println ( The square root of 10 is: +sqrt); System.out.println ( 2 to the 8th power is: +pow); } catch (Exception e) { Sysem.out.println( ERROR : +e); e. prifntStackTrace(Sysem.out); } } } The client program also creates an instance of an ORB, then requests a reference to an object that matches the naming scope created through the NamingContext reference.The object reference that the Naming Service

returen is a general CORBA reference and must be cast before the objecte methods can be called. In addition, the object reference will be represented by a stub, on which the client application will invoke methods. The helper class, generatd by idltojava, makes this easy by providing a method called narrow( ), which returns a reference to a FunctionsStub. With this reference, the square _root and power methods can be called.

Compiling the implementation, client, and server code The newly created implenaetation, server, and client Java class files are compiled next with the following command line: Javac Functionsimp .java calculatorserver. Java calculatorclint. java Starting the Naming Service Application The Naming Service application tnameserv, is provided with Java 2. The Naming Servce Will listen on port-------number 900 default-----for name resolution and binding requests. You can change the default port number by specifying an argument to tnameserv. For example, here the default port number is changed to 1050: tnameserv ---ORVInialPort 1050 The Naming Service application responds with something similar to the following output: Initial Naming Context: IOR: 000000000000002849444c3a6f6d672e6f72672f436f734e616d696e672f4e6 16d696e7436f6e746578743a3000000000010000000000000340001000000 00000864656661756c74000403000000000001cafabcafe0000000234ba207 b0000000000000080000000000000 TransientNameServer: setting port for initial object references to: 1050

The output lists the Naming Service s Interoperable Object Reference (IOR) and the current port number that the Naming Service is listing on. The IOR string is another mechanism for locating a CORBA object reference. The IOR contains information about the location of the object, including the hostname and IP address. And what services the object provides. The IOR is most useful for passing an object reference between two ORB implementations without the need for a Naming Service to locate an object reference. This works as follows: The server publishes a stringified object reference (the string representation of the CORBA object reference) by converting the object reference to a string. For example, the Calculatorserver class definition shown earlier includes: Try{ // Create and initialize the ORB ORB orb=ORB.init(args,null); //Create implementation object and register it with the ORB Function Impl fRef = new FunctionImpl ( ); Orb.connect(fRef); System.out.println (orb.object_to_string (fRef)); } The server wil then report the IOR for the FunctionsImpl object. The calculatorclient is passes the entire stridfng output as an argument on the command line, and it converts the IOR string to an object reference: Try { // Create and initialize the ORB ORB orb = ORB . init(cargs, null); // Get a reference to an object from third argument // on the command line

Org.omg.CORBA.Object objRef = orb.string_to_object (args[2]); // Use the interface Functions to resolve the actua // object reference Functions fRef = ffunctionsHelpe.narrow (objRef); }

Starting the Server Next, the server is started to register the implementation object with the Naming Service. The server must locate the Naming Service by using the same port number or by using the IOR that the Naming Service published on startup. In this example, the port number is use. Java CalculatorServe ORBInitialport 1050 The server will run until it is killed. Starting the Client Now we can run the client application. The client must also be able to locate the Naming Service in order to contact the appropriate server for a reference to the implementation object: Java CalculatorClient ORBInitialPort 1050 The client application produces the following output, indicaton that it was successful in locating the server, rerceiving a reference to the functionimpl object, and executing a square _ root and power operation: The square root of 10 is: 3.1622777 2 to the 8th power is: 256.0

IDL-to-Java Language Mapping Programming conventions for Java and IDL differ slightly IDL conventions do not require capitalization for the names of modules, interfaces, or operations. In addition, IDL conventions are the result of the OMG s adoption of a definition language that crosses several programming languages and the attempt to create a standard that satisfies the capabilities of all of these languages. Here are some general guidelines to follow when developing IDL files: y An IDL file is composed of several elements that together create a naming scope. y IDL does not support the overloading and overriding of operations, although inheritance (single and multiple) is supported. The following sections present an overview of the IDL-to-Java language mapping focusing on the most commonly used constructs. TIP For the complete IDL-to-java language mapping, refer to http://www.omg.org/library/schedult/technology adoption.htm.Also. Chapter 5 through 8 of the Java mapping specification are provided as part of the Java IDL documentation (shipped with Java 2). These chapters are available through the file /JDK1.2 document installation directory/docs/guide/idl/mapping/jidlMapping.html. IDL Constructs As examples of how to use some common IDL constructs, we ll look at sample IDL files that might be used by Sullivan Publishing, the fictional book publishing company described at the beginning of this chapter. IDL Modules The IDL module construct is use to define the enclosing scope of a group of IDL interfaces. A module can contain one or more interfaces, and can nest

other module constructs. Each module construct compiles to a Java package name. Here is an example of a nested module construct: // IDL Module sullivanBooks { Module BookStore { Interface Account {

}; }; }; The Java code generated by idatojava would include the following package declaration: // Java code Package SullivanBooks.BookStore;

IDL Interfaces The IDL interface construct maps to a Java interface class. The idltoava compiler generates several Java files from a single IDL interface construct: y A Java interface class with the same as the interface identifier. y A generated implementation base class that contains the skeleton cod required for the server-side application y A stub class y A helper class that is used to narrow the object reference returned from a Naming Service to the stub object required by the client y A holder class that is used to contain a reference to the IDL type if the interface is passes as an argument in an operation

Given the IDL module definition shown in the previous section, the following files are generated (under the SullivanBooks.BooksStore package directory) using idltojava: Account. Java AccountHoldr.java _AccountStub.java AccountHelper.java _AccountImplBase.java IDL interfaces can contain attributes, exceptions, and operations. IDL Attributes An attribute defines a CORBA variable type that may be accesses by predefined methods. CORBA types can either be standard IDL. Types (listed in Table 13.1) or another IDL interface. T A B L E 13.1: IDL-to-Java Mappings

An attribute will generate an accessor and mutator method for the type declared. For example: // IDL Attribute float price; Will generate the following Java methods: // Generated Java methods Float price ( ); Void prince (float arg);

The attribute may also be declared read-only, in which case only an accessor method is declared. Note that the IDL compiler does not generate a price variable, just the methods to acces the variable. IDL Operations IDL operations are compiled to Java methods. Each operation must declae a return type and may have zero or more arguments. Auguments to operations declare the call semantics of the argument. These may be in, out, or inout. An in parameter is call-by-value and is mapped directly to the corresponding Java type (see Table 13.1). An out parameter uses call-byreference semantics. Java does not use call-by-reference, so out parameters are mapped onto a Java Holder class. This class encapsulates a data variable that contains the parameter, and the value of the class reference in passes. Finally, the inout parameter semantics are call-by-value/result. This too is mapped onto a Java Holder class. Operations That Raise Exceptions Operations can declare that they raise an exception using the construct raises (exception).Exceptions in the raises clause must be declared before they can be used. Here is an example: // IDL // . . . code above not shown Interface account { Void orderBooks ( in Books, out string ordered) Raiss (StockException); }; The above operation, orderBooks, declares an in parameter named books of type BookList and an out parameter that is a string and raise an exception StockException

An IDL File to Define Three Services To continue the discussion of IDL constructs, let s look at a more complete example. Here is the IDL file that Sullivan Publishing will use for its online bookstore: // Sample IDL Module BookStore { Exception StockException { String reason; }; Exception AccountException { String reason; Float creditLine; }; Struct Book { String title; String author; String isbn _ number; Float price; }; Typedef sequence <Book> BookList; Interface BookOrder { Readonly attribute BookList the order; Void addBook (in Book the Book ) raises (StockException);

Void removeBook (in Book the Book); Void searchBook ( in Book the Book, out Book result) Raises (StockException); }; Interface BookOrderManager { BookOrder generateOrde ( ); }; Interface Accont { Readonly attribute string accounted; bookOrder getBookorder ( ); void orderBooks (in BookOrder ordr) raises (AccountException); Void checkStatus (in BookOrder order, out strig status); }; Struct paytype { String cardType; String cardNumber; String expirationDate; }; Interface AccountManager { Account getAccount (in string name, in PayType payment ); };

}; This IDL file defines four sevices: y The AccountManager service will generate an Account for the customer and allow the customer to generate a book order. y The Account service is used to generate a book order, order books, and check the status of a book order. y The BookOrder service is used to add or remove books from an order. y The Book OrderManager service generates a new order that the Account object uses to order books. Customers will open an account, then generate a book order with one or more books they add to the order, then place the order. If a book is not in stock, then a StockException is raised to let the customer know that the book is out of stock. An Account Exception is raised if the credit card used to open the account is overdrawn or invalid at the time of ordering. Object Factories The factory concept is very important in the development of CORBA servies . It is sometimes desirable to be able to create new objects on the fly at runtime. This capability is important when the number of objects to be created is known in advance.

The IDL file shown in the previous section use object factories. The number of accounts that Sullivan Publishing will have over the life of the company cannot be predetermind. It might be possible to create a number of objects in advance that can then be doled out, but how many is enough? Should you create 10 or 100? Rather than describe each object as a discreate service that exists on the server, an object factory allows the server to create an instance of an

Account object for each new customer request. The Account Manager service is responsible for reciving a request for a new Account, and then creating a new Account object for that request. Subsequent requests will always return the same object reference given that the account name is the same. Granted, using a single string to create a unique object is probably not enough, but the idea is that some given set o parameters defines what object reference to return. Figure 13.4 illustrates this use of an object factory.

Like wise, each Account may have one more BookOrde objects from the BookOrder Manager objects on request. IDL Exceptions IDL exception are passes as object references, as in Java, but they do not map directly onto the Java Exception API. IDL exceptions extend the org. omg. CORBA.UseException class. Exceptions may contain daa that is accesses as public members of he named class and may be passed in the construction of the exception. For example, this exception construct: // IDL Exception StockException { String reason; }; Is compiled into a java class (AccoutException.java); /* *File: ./BookStore/AccountException.java *From: Bookstore 2.idl *Dat: Tue jan 6 14:13:36 1998

* By: idltojava java IDL 1.2 Nov 12 1997 12:23: 47

*/ Package Bookstore; Public final class AccountException Extends org.omg.CORBA.UserException { // instanc variables Public string reason; Public float reason; Public float creditLine; // constructors Public AccountExceptio ( ) { Super ( ); } Public AccountException(String __reason, float__creditLine) { Super( ); Reason + __reason; creditLine = __creditLine; } } IDL Structures The IDL struct is a container class that may be used to pass a collection of data as a single object. An IDL struct maps to a Java class with public data members. For example, this struct construct: // IDL

Struct Book { String title; String author; String isbn _ number; Float price; }; Maps to a Java final class: /* File: ./BookStore/Book.java * From: bookstore2.idl *Date: Tue Jan 6 14:13:36 1998 *By: idltojava Java IDL 1.2 Nov 12 1997 12:23:47 */ Package BookStore; Public final class Book { // instance variables Public string title; Public string author; Public string isbn_number; Public float price; // constructors Public Book ( ) { } Public Book (String __title, String__author,

Title = __title; Author = __author; Isbn _ number = __isbn_nuber; Price = __price; } } IDL Type Definitions IDL provides a construct for naming new IDL types from existing types. The typedef construct does not direrctly map to Java, so the IDL compiler will substitute and replace any instance of the typedef anem for the actual type in the IDL before compiling it. The typedef construct makes it easier to write IDL files, particularly when sequences are required. Here are some examples of typedef constructs: // IDL Typedef string Customer Name; Typedef long customersalary; Typedef sequence <long> customerOrderID;

IDL Sequences IDL sequences are single-dimension arrays that may be bounded or unbounded. A bounded sequence difines its maximum size in the declaration of the sequence. For example, in this sequence construct: // IDL Typedef sequence <long, 10> openOrdes;

A bounded sequence of ten IDL long numbers is defined as the type open Orders. The bounds of a bounded sequence are checked as the argument is marshaled and sent. If the bounds of a bounded sequence are exceeded, a MARSHAL system exception is raised. Both bounded and unbounded sequences generate a Java helpe and holder class for each sequence. IDL Arrays The IDL array construct is used to create a single_dimension bounded array of any IDL type. The array construct is mapped to Java the same way as the bounded sequence, but uses different semantics. Here is an example: // IDL Const long length = 20; Typedef string custName [ length]; IDL Enumerations The IDL enum construct is used to represent an enumerated list, as in this example: Enum CityList {Boston, Newyork, Philadelphia, Baltimore}; The enum construct maps to a java final class with the same name: /* *File : *From: *Date: *By : */ Package BookStore; ./BookStore/cityList.java test.idl Tue Jan 6 16:32:56 1998 idltojava java IDL 1.2 Nov 12 1997 12:23:47

Public final class CityLit { Public static final int _ Bostom = 0, _NewYork = 1, _Philadelphia = 2, _Baltimore = 3; // code deleted } Legacy Applications and CORBA A business application may include code that is not current or state-ofthe-art, but works perfectly well. That code may have been written by engineers who left the company long ago. This type of code is referred to as legacy code. One of the drawbacks to legacy code is that it is ofte deployed on a legacy hardware system as well. The company needs to access this code on its existing hardware platform and be able to use it across its network. One of CORBA s primary benefits is that it allows developers to wrap legacy code with a CORBA object approach. An IDL description of the legacy interfaces is used to produce a set of CORBA objects. These objects can then make calls into the legacy code and expose the legacy system to a network. Figure 13.5 illustrates this approach. Wrapping legacy code does require some understanding of the way that the code works. The low-level implementation details are not important, but an understanding of the way that the code is called or interfaced with other code modules is necessary. The interfaces and access methods become the foundation of an IDL interface, which is then used to create a CORBA system. As an example, suppose that Sullivan Publishig (Our fictional book publishing company discusses at the beginning of this chapter), in one of its expansions, has purchases a book catalog service. Part of this purchase involved the acquisition of some C code used to search for book records in a

database. The current book catalog service is a phone-only service. Sullivan Publishing would like to use the Internet to allow customers to order books, but still preserve the current code that exists for searching the book database. This is an excellent application for CORBA. The legacy C code can be used as is, but will be wrapped by an implementation that will expose the C code to the network. In this example, Sullivan Publishing purchases inventory-tracking software that was designed to run on a Windows NT computer. The original code was not designed to run on a network, and the original source code is not available, so it is not practical to port the code directly to Java. However, the interface to the code is fairly straightforward the C code is compiled into a library. For example, calls to the search routines are made as follows: Void search (Book *toFind, Book *result); Where the parameters are passes as a pointer to a struct: Struct Book { Char title [100]; Char author [100]; Char isbn [25]; Float price; }; The developer defined the C function call and the C struct in IDL as follows: // IDL Struct Book { String title; String author;

String isbn _ number; Float price; }; Interface BookOrder { Readonly attribute Booklist the Order; Void addBook (in Book the Book) raises (StockException); Void removeBook ( in Book the Book); Void searchBook (in Book the Book, out Book result) Raises (stockException); }; Since Sullivan Publish would like to preserve the legacy C code for the search routine, the BookOrder object must be implemented on the Windows NT computer. There are a couple ways to do this. y Use a CORBA vendor that supports a C language mapping and a Windows Nt ORB. Implement the BookOrder object in C, directly integrating the library call to the search function. y Write the implementation class for BookOrder in Java on the Windows NT machine, and use a native method to call into the seach function. The is a book about Java, so we ll demonstrate the latter approach: // Implementation file for the BookOrdere interface Import BookStore.*; Import java.util.vector; // First, extend the Implementation Base class Public class BookOrderImpl extends _ BookOrderImplBase { // keep a vector of books to be ordered

Private vector booklist; // constructor Public bookorder impl ( ) // initialize the vector Booklist = new vector ( ); } // Implement the method to return the current list of books Public Book [ ] the Order ( ) { Book [ ] bookOrder; // Turn the vector into an array bookOrde = new book [booklist.size()]; boolList.copyInto (bookOrder); } Return bookOrder; } Public void remove (Book the Book){ // Remove an element from the booklist booklist.removeElement (the Book); } Public void searchBook the Book, BookHoldr result) Throws BookStore.StockException { // Call the native search function {

Search (theBook, result); If (result ==null) { Throw new stockException ( No book found with ISBN numer: + the Book.isbn_number); } } // The native method for search Private native void search (Book the Book, BookHolder result); // Load the native method from the specified library static { System. loadLibrary ( ordelib ); } } Note that the serve application for the Account Manager object can rerside on another machine, like a Sun workstation. The client application will request a reference to an Account Manager. Using this object reerence, the client application will request an instance of an Account (by calling the getAccount method). With this object reference , the client can generate a new BookOrderManager on the Windows NT machine and returns a BookOrder object. To the client application, this all happens through local stub invocations!

Summary CORBA makes it possible to develop systems that are independent of a programming language and operating system. The introduction of Java to the programming world and the development of protocol standards have propelled CORBA in to the current mainstream of computing.

CORBA provides an intermediary solution to the problem of rewriting code. CORBA makes it possible to preserve a company s current investment in COBOL C, C++, and Ada applications while making the transition to Java in the lontem. CORBA s standards-based approarch also frees decision-makes from making a single vendor choice. Systems that are developed using the CORBA framewok and standareds are easily adapted to other vendors products with a minimum of code rewriting. The future of distributed object programming will undoubdtedly include CORBA. It is likely that in a few years, systems will be developed with visually driven tools, eliminating the need to develop IDL files altogether. Furthermore, it is becoming increasingly apparent that software vendors have embraced the standards set forth by the OMG, and the future will include more interoperability across both software and hardware domains.

CHAPTR FOURTEEN Content and Protocol Handlers

y y y y y y

Protocol and handler types Protocol and the URL Approaches to content and Protocol handling Protocol handlers Content handlers Server-side handling

The Internet, mainly in the guise of the World Wide Web, allows data to be shifter around in a wide a variety of formats. Despite appearances, the Internet has many more components besides HTTP and the World Wide Web, In fact, a wide variety of different protocols such as FTP, Talnet, and Gopher__exist on the Internet and are quite well known. Java programs may be required to handle any or all of these protocols and data formats. This chapter looks at the issues that are raised by these requirements and the mechanism that is built into the Java core packages for coping with the variety. The first sections descuss the background issues and consider how problems are handled in other related systems. Later sections describe the implementation and installation of Java content and protocol handlers.

Protocol and Content Types The Internet contains information resources in a wide variety of formats. A corporat internet also offers various formals, including all those that are normally found on the Internet. For example, it might be advantageous to publish figures using the native format of a spreadsheet

application, which would also allow the work to be modifies and might even result in smaller files. When compared to, for example, PostScript files. Each of these different formats constitutes a different content type. Two things are required to support multiple content types and to be able to view them in a web browser without user intervention: y The browser must be able to recognize the content type in some way. y The browser must be able to invoke code that handles the content correctly.

It has long been a tradition to use an extension, such as. Txt or.cmd, in afile name to indicate the nature of the contents of a file. In a web environment, especially one with many dissimilar platforms, this mechanism is not sufficiently expressive nor widely standardized . Problems can arise when such mnemonic extensions are reused by different applications for incomepatible files. This situation is handle on the web by making more detailed content type information available as part of the protocol. The nature of a data set is described using a string called the MIME content type. MIME Description of Content Type MIME, the Multipurpose Internet Mail Extensions system, was first invented , as the name suggests, to facilitate sending files representing images and sounds over Internet mail links. Strictly speaking, Interent email is a 7-bit ASCII-only protocol; therefore, sending binary files directly is not possible. MIMF, in the mail context, address two separate issues; how to represent 8-bit binary data using only 7-bit ASCII and how to describe the significance of the files that are being transmitted. A number of general, or top-level, categories are defines by MIME, including text, audio, image, and video. These categories are further subdivided to indicate the particular type of encoding used. So, for example, normal web pages are encoded using HTML, and the MIME type

string representing that is text/html. Notice that the parts that make up the type are separated by a forward slash, in a fashion similar to that used to sparaete elements of a URL. TIP Like all Internet protocols, MIME is defines by Request For Commant documents (RFCs). In this case, the documents are RFC 1521 and 1522. These are on the CD-ROM in the directory javadevhdbk\rfcs.

Protocols and the URL Identifying the protocol to be used for a data transfer is at least as important as identifying the contents of the transfer. In a URL, the protocol to be used is defined by the part of the URL immediately before the first colon. For example, a URL that starts with http:specifies the use of the HTTP protocol; a URL that starts with telnet: indicates that Talnet is the protocol to be used. Each protocol has a default port number associated with it, but this can be overridden in the body of the URL by adding a number, prefixed with a full colon(:) between the end of the target machine name and the start of the path part of the URL. For example, if an HTTP connection is to be made using port 8080 rather than the default port of 80, to a machine www.fred.com, the URL would start like this: http://www.fred.com:8080/ A number of well-known protocols exist, and the URL concept allows the possibility of adding new ones. Such additions might be particularly appropriate in a closed environment like a corporate intrant. Nexted Protocol Handlers An interestiny capability introduced with Java 2 is offered by the idea of a nested protocol handler. A nested protocol handler uses another protocol to do part of its work.

Specifically, Java 2 includes a new protocol called jar: that allows data to be read from a JAR archive. This protocol is nested in the sense that the location of the JAR archive itself is specified using another URL, and hence another protocol. For example, suppose that you want to speciy a URL that describes a file called data. Dat, which is located in a subdirectory called jan in a JAR archive called accounts.jar.and the JAR archive is itself located on a web server at the URL http://accounts.myco.com/records/account.jar.you would use the URL jar:http://accounts.myco.com/records/accounts jari/jan/data.dat. To create a nested protocol handler, you simply parse the overall URL and separate the two parts. One part of the URL is used in handling the connection aspects, and the other part is used in handling the aspects that are specific to the new protocol. This approach has the potential to provide a convenient means for HTTP tunneling. Extensibility in Java Modern browsers must handle the wide variety of content types and protocols that exist on the Internet. Ideally, it should be possible to enhance a browser to cope with new standards that arise without needing to upgrade the whole browser. The same extensibility is required in Java. NOTE The software that handles a particular content type is referred to as a content handier. The software tha handles a particular protocol is called a protocol handler.

One of the earliest techniques for extending a browser was to allow the configuration of an external helper program that could be used when an otherwise unsupported protocol or content type was encountered. This approach does not allow the resulting data to be displayed in the same browser window as the rest allow the resulting data to be displayed in the same browser window as the rest of the data being loaded, but it is easy to

implement in a vaiety of systems. Its limitations are that browser must be configured manually for each new content type protocol and that the handling program must be obtained separately. Another approach involves designing the browser to be extended by means of additional code modules provided after the original browser has been written. This extensibility eliminates the need to load and run external programs to work with additional protocols and content types. This code-module approach is the principle underlying the plug-ins used by the Netscape Navigator browser. The JVM provide a meachnism for loading code into a running program. This dynamic-linking idea is fundamental to the design of Java and is ideally suited to the particular case of content or protocol handlers. The key to creating a program that can be readily extended later lies in a carefully considered object-oriented design. Consider a drawing program that is being created to handle lines, circles, and extensions. If it is coded so that thse items are handled explicitly, then a later extension will require changes to the source, recompilation, and redistribution of the whole program. On the other hand, if the program deals instead with a mor generalized object of a class called Drawable (as an example), then it can quite easily be extended to handle any other subclass of Drawable without needing recompilation. For this to work in practice, two things must be done. First, the Drawabl class must be designed carefully to ensure that it provides an interface flexible enough to allow any future ideas to be expresses, at least as far possible within the broad context of drawing. Second, a mechanism must be provided for the program to determine which implemdentations of Drawable are available for use at runtime. These must be able to express their names and make themselves available via the user interface. In the case of a drawing program, it is reasonable to arrange that all specific Drawable classes be placed in one particular directory. The

program can then scan that directory to determine the names of the Drawable Classes that are available to it. Default Protocol and Content Handler Mechanisms In the case of both codntent and protocol handlers, the mechanism by which the program determine what the names of both the package and the class should be based on the name of he protocol or content type in question. Given this vonvention, it is a simple matter for the browser program to ask for the handler by name. If the attempt to load that driver fails, then the protocol or content type is unsupported. NOTE Java s framework for locating content and protocol handles allows, in principle for these handlers to be loaded from the same the same web server that supplies the data. However, in the current implementations of the Applet viewer and Hotjava, this ease of loading is not possible. Current browsers only support searching or either type of handler on the local machine CLASSPATH, which is a significant limitation. As explained earlier, the protocol name is specified as the first part of the URL text string immediately before the:// separator. It is easy to extract this, and the mechanism for doing so is consistent regardless of the protocol. Furthermore, the URL class in the java. net package provides a built-in method for this purpose. Because the protocol name is part of the URL, the primary responsibility for locating handler code for nay particular protocol rests with the URL class. When the method openconnection( ) is called on a URL object, a protocol handler is located, if possible, and invoked. The protocol handler returns a URL Connection object over which the data can be transferred. The URL class provides three routes for obtaining a protocol handler: y Locate a class called Handler using the local CLASSPATH and a package name built using the protocol name and a predefined prefix.

y Locate a class called Handler using the local CLASSPATH and a package name built using the protocol name and a use- specified presix. y Invoke a factory. A factory takes a protocol name and attempts to return an instance o a Protocol Handler. It can use any algorithm to achive this, limited only by the programmer s imagination. (You will see later the factory concept is also employed in content handling.) Whatever tha name o the protocol, the class that handls it is conventionally called Handler. To allow handles for a variety of protocols to be installed, each Handler class is placed in a package that reflects tha protocol name. Ffor example, given the textual name of a protocol, finger, the Handle class is located in a subpackage called finger. This subpackage is located in a particular parent package that is called, by default, sun.net.www, so the full class name is sun.net.www.protocol.finger.Handler. NOTE The Finger protocol, where available, allows you to find out information about users on othr machines. Conventionally, Finger would report the full name, last login time, and related personal information about either users currently logged in or about an individual specified by logi name. The finger service is often disabled, because this kind of information is of potential use to malicious hackets.