P2J Project Guide

Contents

Introduction

• conversion - convert Progress 4GL source code into a functionally equivalent, drop-in replacement written in the Java language
• runtime - run the resulting converted Java application, providing the functions and features of Progress 4GL in a compatible manner

Installation and Configuration

Directory Structure

Prerequisites

1. The TAB key can be recognized as F67! The reason is: the TAB key, which is Ctrl-I, is assigned twice, for ht and knxt attributes.
2. The HOME key is determined as the sequence of ESC-O, H keys and mapped to GET, H key-functions instead of HOME key-function.
3. The END key is determined as the sequence of ESC-O, F keys and mapped to GET, F key-functions instead of END key-function.

infocmp vt320 > vt320.tmp

/usr/share/terminfo/v/vt320

ht=^I,

knxt=^I,

khome=

khome=\EOH,

kend=\EOF,

cd /usr/share/terminfo/v

sudo mv vt320 vt320-bak

sudo tic -o/usr/share/terminfo vt320.tmp

infocmp vt220 > vt220.tmp

/usr/share/terminfo/v/vt220

kend=\E[F,

civis=\E[?25l,

cnorm=\E[?25h

cd /usr/share/terminfo/v

sudo mv vt220 vt220-bak

sudo tic -o/usr/share/terminfo vt220.tmp

infocmp xterm > xterm.tmp

/usr/share/terminfo/x/xterm

kbs=^H,

cd /usr/share/terminfo/x

sudo mv xterm xterm-bak

sudo tic -o/usr/share/terminfo xterm.tmp

• ANTLR 2.7.4
• antlr.jar
  
• Apache Jakarta
• Schema namespace and configuration processing:
• commons-beanutils-core.jar
• commons-collections-2.1.1.jar
• commons-digester.jar
• commons-logging-1.0.4.jar
• Encoded (as a string) raw variable processing:
• commons-codec-1.3.jar
  
• PostgreSQL
• postgresql-8.1-408.jdbc3.jar
• H2 Database
• h2.jar
• Hibernate
• asm.jar
• c3p0-0.9.1.jar
• cglib-2.1_3.jar
• dom4j-1.6.jar
• ehcache-1.1.jar
  
• hibernate3.jar (modified as noted above)
  
• jta.jar
• Jetty
• jetty-6.1.14.jar (modified as noted above)
• jetty-util-6.1.14.jar
• servlet-api-2.5-6.1.14.jar
  
• CHARVA
• charva.jar (modified as noted above)

• The SUN's Next Generation Java plugin is required. It comes with the JDK version 1.6.0 update 10 and later, so the JDK should be upgraded.
• Since this version if the plugin is compatible only with the most recent versions of browsers, the browser should be at the compatible level. Firefox 3 is acceptable, but not Firefox 2.

Installation

P2J Development Environment Configuration

The P2J_HOME System Property

• that <some_directory> exists in the local file system;
• that <some_directory> is in fact a directory;
• and that <some_directory> contains a cfg subdirectory which in turn contains XML configuration files.

How to Build P2J

Quick Start (Converting a Simple Testcase and Running the Result)

Preparing a Project for Conversion

Schema Loader

Building Java Data Model Classes

Generating Data Definition Language (DDL)

Progress 4GL to Java Source Code Conversion

1. unreachable/unreachable (using an .ast file as input) - analyzes the source ASTs and annotates all nodes regarding whether they can ever be executed or not
   
2. annotations/annotations (using an .ast file as input) - inspects the tree, calculates names and many other important values then stores these in annotations
   
3. convert/frame_generator (using an .ast file as input) - generates 1 interface definition Java AST and 1 class definition Java AST for each frame used in a Progress source file
   
4. convert/base_structure (using an .ast file as input) - generates the top level structure of the Java source file to which the rest of the converted code can be grafted
   
5. convert/core_conversion (using an .ast file as input) - walks the source AST nodes and generates the proper Java AST nodes using expressions and some conversion helpers
   
6. convert/brew (using a .jast file as input) - translates the Java ASTs into Java source code
   

Data Migration

Exporting Data from Progress

1. Open the Data Dictionary
2. If necessary, connect to the target database and make it the working database
3. Select from the menu:  Admin --> Dump Data and Definitions --> Table Contents (.d file)...
4. Select all tables to be migrated to the new database and GO (generally F1)
   
5. Select a target directory, use the NO-MAP option for character mapping, use code page ISO8859-15;  choose OK

Importing Data into the Target Database

• <p2j_project_root>/p2j/build/classes
• antlr.jar
• commons-beanutils-core.jar
• commons-digester.jar
• commons-collections-2.1.1.jar
• commons-logging-1.0.4.jar
• hibernate3.jar
• dom4j-1.6.jar
• postgresql-8.1-405.jdbc3.jar
• jta.jar
• cglib-2.1.jar
• asm.jar
• c3p0-0.8.5.2.jar
• ehcache-1.1.jar
• <p2j_home>/cfg
• .
  

java -Xmx128m
  -DP2J_HOME=<home_directory>
  com.goldencode.p2j.pattern.PatternEngine
  -d 2
  schema/import
  data/namespace
  "<db_name>*.p2o"
  2>&1 | tee schema_import.log

Logging

Debugging

• the original 4GL program works as expected
• this 4GL program was converted to its Java equivalent via the P2J conversion process
• neither the 4GL program nor the converted Java program have been manually modified since the conversion ran
• the behavior for the Java program deviates from the original 4GL behavior

• database schema
• database contents/data
• the same application source code (being run in Progress and as a conversion input to the P2J process)
• the same terminal types (e.g. VT320) and sizes (80x24) in CHUI applications

• error message
• Error messages can be application-level or they can be originated in the P2J runtime. Either way, they would be displayed on the screen (often in one of the "message" lines, sometimes in an alert box).
• A runtime error message will usually begin with two asterisk characters, followed by the error text and an error number in parenthesis.  For example: ** Some error message text. (-1)
• Runtime errors will also be written to the logging implementation.  This may be useful to put the problem in the context of the larger log file OR in the case where a user reports that he or she saw an error message, but did not report the exact text of the message.
• The specific error text of a given runtime error will be easily traced back to a small number of locations (usually only one location in practice) in the runtime code.
• If the error message displayed is an application message, then the error text can be traced back to its source in the application code.
• Once the source of the message is found, a debugging breakpoint can be set at that location such that an effective debugging session can be started.
• Of course, it is possible that the error message itself contains enough information to diagnose the problem, avoiding the need for a debugger session.
• exception stack trace
• Some abends are accompanied by such a specific exception that the problem is self-evident.  If this is not the case, then a more thorough investigation will be needed.
• There are 4 common or "expected" conditions that can be normally encountered by Progress 4GL code.  These conditions are ERROR, END-KEY, STOP and QUIT.  These conditions map to a sub-class of the ConditionException which is a P2J runtime class.  Any such conditions that are raised by the operation of a converted application will not cause an abnormal end (abend). Rather, these exceptions are naturally handled and in fact are necessary to ensure the compatible application control flow.
• Other than these expected ConditionException instances, if an unhandled exception is encountered by the application code, this will naturally unwind the stack completely and the user's session will exit (abnormally).
• Before exiting, the runtime will generally log the stack trace for any such exception.  So when a user reports that their session abended, the stack trace can usually be found in the server's log file.  In some cases, the STDERR of the client may have received the stack trace output.
• When an abend occurs on the server, it will usually be generated on a user's session thread. This means that only that user will be affected by the abend.  The server will continue running and all other users will continue working without any affect.  All other (non-user) threads are especially well protected from exceptions and are running a small, well tested and well known code base.  Since all real work occurs on user-session threads, this is where the problems can occur.  At the root of a server stack trace will usually be a Thread.run() and a Conversation.run() call respectively.  User session threads are "conversation" threads that are dynamically created and used for the lifetime of the user's session.  This is a dedicated thread for that specific user and it will not return until the user exits the application, generates an unhandled STOP condition (usually via CTRL-C on the client) or encounters an abend.  Further up the stack trace one will usually find a reference to StandardServer.standardEntry() which is the primary entry point on the server for interactive clients.  The Java reflection classes are used in many places to implement dynamic invocation of classes and methods.  Further up the stack will be an invocation of the "top-level" application entry point.  This is the execute() method of the Java class which was generated from the Progress 4GL program that is normally used at startup of the application.  From there the stack trace will be completely dependent upon the call chain of processing in the application.
• When an abend occurs on the client, this will almost always be thrown on the "main" thread of the application. For an interactive client, the root of the stack would normally be ClientDriver.main().  Further up the stack is usually a reference to something like $Proxy2.standardEntry() which is a remote invocation of the StandardServer.standardEntry() method that exists on the server side.  Above there, one will normally see Dispatcher.processInbound() which is an indication that the server has called a client-side exported API to obtain some kind of service such as rendering an application frame (a screen).
• Note that exceptions thrown on the client during the processing of some server-driven request (this is almost always the case) will unwind the stack "over" the network and be re-thrown on the server side.  This means that client side stack traces can and will be seen in the server's log file.  Just because the stack trace is present in the server log, don't assume it is a server-side issue.
• Near the top of the stack (client or server) will usually be a good location where one can set a breakpoint to start a productive debugging session.
• More information about the roles of specific threads in the system can be found here.
• thread dump
• If one does not have any error message or exception stack trace from which to start, one can generate a thread dump on either the client and/or the server. A thread dump is a listing of all currently existing threads in the JVM and a stack trace from each of those threads. By interpreting these stack traces, one can get a very clear snapshot of the status of the client and/or server.
• Before triggering the thread dump, it is best to recreate the problem and to get as close to the failure point as possible without passing the failure point.  It is also important to ensure that the processing stays at that location long enough for one to trigger the dump.
• The thread dumping feature is a standard facility of the Sun HotSpot based JVM, however virtually all JVMs will have this feature.  In the Sun JVM, there is a simple mechanism to notify the JVM that a thread dump needs to be produced.  The JVM will pause all threads, for each one it will write the stack trace to STDOUT and then the threads will be resumed.  The threads do not halt permanently and there is no negative side effects of this thread dump.  So this procedure is safe to use on a production server.
• On Linux, one must know the process ID (pid) of the client or server process which needs to produce the dump.  This can normally be obtained via the ps command.  To generate the dump, run the command kill -SIGQUIT <pid> OR kill -3 <pid>
• On Windows, one must find the console in which the client or server is running and then manually execute the CTRL-BREAK key combination while that console has the "focus" (while user input is directed to that console).
• Please note that the server output will be cleanly captured on STDOUT, but on an interactive CHUI client, STDOUT is in use for the application itself.  In other words, generating a thread dump on a Linux CHUI client process will corrupt the screen.  In addition, it is likely that the terminal is not in a scrolling mode.  This would cause most of the thread dump to be "lost" since the user will not be able to scroll up the terminal buffer to see all of the output.  On Linux, in the KDE Konsole terminal application, this problem can be resolved by executing the "Edit -> Reset & Clear Terminal" menu item BEFORE the thread dump is triggered. That will allow the terminal buffer to be scrolled and the full thread dump output will be visible. It is likely that after this the CHUI client will not operate properly so it may need to be exited.
• It is perfectly acceptable to generate thread dumps more than once for the same process.  There is no adverse affect, however one will need to be careful in the interpretation of the STDOUT contents as the correct thread dump must be found.
• Once the thread dump is available, it can be used just like an exception stack trace to get a starting point for debugging.
• logging
• When all else fails, logging can be a useful fallback plan. The reason one doesn't usually start with logging is that the output from logging can be quite voluminous and thus very time consuming to interpret.
• Please see the section on the logging facilities built into the runtime. These facilities would be used to configure each server's logging settings. Note that after changing any of the directory configuration for logging, the server will need to be restarted for those settings to take effect.
• The following classes have highly useful, general purpose logging implemented:
• com.goldencode.p2j.util.TransactionManager will provide output of every block related event and its current state using the FINE logging level
• com.goldencode.net.RemoteObject will provide a log entry for every outbound remote call in FINER logging level and with FINEST level, it provides a dump of the remote call parameters and a log entry (including the elapsed time) for when the remote call completes
• com.goldencode.net.Dispatcher will provide a log entry for every inbound remote call in FINER logging level and with FINEST level, it provides a dump of the remote call parameters and a log entry (including the elapsed time) for when the call completes

How to Run Testcases

Preprocessor Testcases

Progress Lexer Testcases

Progress Parser Testcases

Progress Expression Evaluation Testcases

Progress Lexer and Parser Automated Regression Testing

Bitset Dumping

Schema Lexer Test Driver

Schema Parser Test Driver

SchemaDictionary Symbol Resolver

• <database_name>

• <database_name>.<table_name>
• <table_name>

• <database_name>.<table_name>.<field_name>
• <table_name>.<field_name>
• <field_name>

• the database name associated with this namespace;
• the XML filename where the namespace dictionary information for this database resides;
• optionally, whether this database should be loaded into the SchemaDictionary by default at dictionary construction time.

Compiled Expression Engine Test Driver

• <properties> is the name of the properties file
• <type> is 'A' for an arithmetic expression, 'L' for a logical expression
• <expression> is an expression in double quotes
• <first> is the optional 1-based index of the first record to access
• <last> is the optional 1-based index of the last record to access

• name (string) - an employee name
• dob (date) - employee date of birth; must be in one of the following formats, within single quotes:
• overtime (double) - overtime hours for the current period
• city (string) - employee's city
  
• union (boolean) - employee's union affiliation status
• begin (date) - time of day employee begins work shift
• end (date) - time of day employee ends work shift
• @now() (date) - a macro which expands to the current system time
  

• yyyy.MM.dd (date)
• MM/dd/yyyy (date)
• MMM dd, yyyy (date)
• HH:mm:ss (time)
• yyyy/MM/dd HH:mm:ss (timestamp)

Directory Package Test Applications

LDAP Directory Back-end implementation notes

Test environment

Runtime DirectoryNetworking/Security Packages Test Applications

• unified command line drivers for both the client and server sides of the P2J application
  
• encrypted XML bootstrap configuration files
• application classes supplied as elements of the configuration files
  
• shared trust stores
• private key stores
  

• -1 this level is assigned to error messages and cannot be disabled;
• 0 warnings;
• 1 statistics;
• 2 detailed lists;
• 3 even more detailed traces;
• 4 detailed traces that may include sensitive security data like passwords;
• higher levels may be defined later.

• client to run ClientTest (can be omitted as this is the default);
• address to run AddressTest;
• echo to run EchoTest;
• shutdown to run ShutdownTest;
• dir to run DirTest;

• -m to include the meta information into the printout
• starting-node to print only the specified branch of the directory
  

Production Level Client and Server Test

• configuration files may be either encrypted or in plain text; if no password is given with the command line, the file is assumed in plain text;
• configuration file name is no longer a required parameter; if no file name is given with the command line, a default file name is assumed (standard_client.xml or standard_server.xml, depending on the driver type);
• configuration file does not have to even exist; all required configuration items can be specified with the command line;
• if the configuration file (either specified or assumed) does exist and there are configuration items with the command line, the latter add to or override the items from the file.

• directory based server initialization; a list of classes to load and methods to call at startup;
• directory based application exports; these are application methods that the NET package makes visible over the network;
• directory based users main entry points.

• user ID abc for tests;
• this user's password as password;
• a test main entry point StandardTransaction.java assigned to the user abc;
• exports for use with the updated DirectoryEdit utility.
  

Understanding P2J Threading

Documentation

Legal Notices

• Golden Code and the GC logo are registered trademarks of Golden Code Development Corporation.
• Java, J2SE are trademarks or registered trademarks of Sun Microsystems, Inc. Java Compatible and the Java Compatible coffee cup logo are trademarks of Sun Microsystems, Inc. used under license agreement with Sun Microsystems, Inc.
• Progress is a registered trademark of Progress Software Corporation.

Appendix A. OpenLDAP Step By Step Configuration Guide 

Prerequisites

1. OpenLDAP software is installed using standard tools (e.g. SuSE YaST2).
2. OpenLDAP configuration files are located in the /etc/openldap.
3. Data files, certificates, sample configurations, etc. are located in the ~/p2j/testcases/test/ldap directory.
4. Certification Authority (CA) certificate, server certificate and server key file are prepared and named respectively: gcd-root-ca-cert.pem, p2jserver-cert.pem, p2jserver-key.pem.
5. Currently user is logged in as a regular user.
6. Samples below assume the current user is 'user' at host 'host'.

Preliminary Steps

1. Sample slapd.conf must be updated to match desired configuration:
   Entries below should contain desired domain name. Sample uses goldencode.com:
   
   ...
suffix "dc=goldencode,dc=com"
rootdn "cn=Manager,dc=goldencode,dc=com"
...

   Also, in some cases following entry must be uncommented and changed to match real certificate:
   
   ...
# Uncomment and change to match actual certificate CN:
#sasl-regexp
# cn=p2j\ server,ou=it\ operations,o=golden\ code\ development\ corporation,l=atlanta,st=georgia,c=us
# cn=Manager,dc=goldencode,dc=com
...

   
   The purpose of this expression is to let OpenLDAP assign rights of one CN to the other CN. In particular this might be necessary to provide read/write access to the P2J server when certificate with CN which does not match DN in the directory is used. Without it connected client will have only guest level rights. Refer to OpenLDAP documentation for mode details about writing sasl-regexp expressions, rights assignment and other administrative tasks.
   Note 1: slapd converts all data from CN of the certificate to lower case before performing match.
   Note 2: In some cases it might be helpful to comment out the statement, restart slapd in debug mode (by specifying -d -1 in command line) and try to connect to LDAP server using P2J server (or other utility such as StartupDirectory or DirectoryCopy) and watch certificate CN in the debug output. Then found CN just copy as is into the slapd.conf and insert back slash before each space (see example above).
   
   
2. Initialization file init.ldif must be updated to match actual domain name, organization name, etc.
   
3. Script file initDir must be updated to use correct administrative DN (most likely - one listed in the slapd.conf as rootdn).
   
4. LdapMapGen configuration file mapping.xml, server configuration files (required for the use of StartupDirectory, DirectoryCopy, and so on) must be updated to include proper LDAP parameters: URL, credentials, location of the mapping data (if necessary), etc.

Main Steps

Appendix B. P2J Directory Configuration Options List

Introduction

Bootstrap Config

P2J Directory

1. /server/<serverID>/runtime/<user_or_process_account>/<id>
2. /server/<serverID>/runtime/<group>/<id>
3. /server/<serverID>/runtime/default/<id>
4. /server/default/runtime/<user_or_process_account>/<id>
5. /server/default/runtime/<group>/<id>
6. /server/default/runtime/default/<id>

Appendix C. Setting Up a Certificate Authority Using OpenSSL

1. Locate the file CA.pl. This file is part of the OpenSSL. A typical location is /usr/local/ssl/misc/CA.pl. Edit the file and change these two keywords: $SSLEAY_CONFIG and $CATOP. The first keyword specifies the configuration file to use. Set it as follows:
   $SSLEAY_CONFIG="-config /etc/openssl.cnf";
   
   The second keyword specifies a writeable location in the filesystem where the CA infrastructure will reside. Let's set it as follows:
   $CATOP="/var/ssl";.
   
   Copy the resulting file to /usr/local/bin/CA.pl and make it executable:
   chmod +x /usr/local/bin/CA.pl
   
   
2. Create the configuration file /etc/openssl.cnf  Take the following configuration as a base and modify it accordingly. Replace every occurance of Golden Code Development and gcd with a different name and abbreviation. You may also changes some defaults, like default_days, which sets the certificate validity period.
   
   #
   # OpenSSL example configuration file.
   # This is mostly being used for generation of certificate requests.
   #
   
   # This definition stops the following lines choking if HOME isn't
   # defined.
   HOME            = .
   RANDFILE        = $ENV::HOME/.rnd
   
   # Extra OBJECT IDENTIFIER info:
   #oid_file        = $ENV::HOME/.oid
   oid_section        = new_oids
   
   # To use this configuration file with the "-extfile" option of the
   # "openssl x509" utility, name here the section containing the
   # X.509v3 extensions to use:
   # extensions        =
   # (Alternatively, use a configuration file that has only
   # X.509v3 extensions in its main [= default] section.)
   
   [ new_oids ]
   
   # We can add new OIDs in here for use by 'ca' and 'req'.
   # Add a simple OID like this:
   # testoid1=1.2.3.4
   # Or use config file substitution like this:
   # testoid2=${testoid1}.5.6
   
   ####################################################################
   [ ca ]
   default_ca    = CA_default        # The default ca section
   
   ####################################################################
   [ CA_default ]
   
   dir             = /var/ssl                # Where everything is kept
   certs        = $dir/certs        # Where the issued certs are kept
   crl_dir        = $dir/crl        # Where the issued crl are kept
   database    = $dir/index.txt    # database index file.
   #unique_subject    = no            # Set to 'no' to allow creation of
                       # several ctificates with same subject.
   new_certs_dir    = $dir/newcerts        # default place for new certs.
   
   certificate    = $dir/gcd-root-ca-cert.pem     # The CA certificate
   serial        = $dir/gcd-root-ca-cert.srl     # serial number
   #crlnumber    = $dir/crlnumber    # the current crl number must be
                       # commented out to leave a V1 CRL
   crl        = $dir/crl.pem         # The current CRL
   private_key    = $dir/private/gcd-root-ca-key.pem # The private key
   RANDFILE    = $dir/private/.rand    # private random number file
   
   x509_extensions    = usr_cert        # The extentions to add to the cert
   
   # Comment out the following two lines for the "traditional"
   # (and highly broken) format.
   name_opt     = ca_default        # Subject Name options
   cert_opt     = ca_default        # Certificate field options
   
   # Extension copying option: use with caution.
   # copy_extensions = copy
   
   # Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
   # so this is commented out by default to leave a V1 CRL.
   # crlnumber must also be commented out to leave a V1 CRL.
   # crl_extensions    = crl_ext
   
   default_days    = 365            # how long to certify for
   default_crl_days= 30            # how long before next CRL
   default_md    = sha1                   # which md to use.
   preserve    = no            # keep passed DN ordering
   
   # A few difference way of specifying how similar the request should look
   # For type CA, the listed attributes must be the same, and the optional
   # and supplied fields are just that :-)
   policy        = policy_match
   
   # For the CA policy
   [ policy_match ]
   countryName        = match
   stateOrProvinceName    = match
   organizationName    = match
   organizationalUnitName    = optional
   commonName        = supplied
   emailAddress        = optional
   
   # For the 'anything' policy
   # At this point in time, you must list all acceptable 'object'
   # types.
   [ policy_anything ]
   countryName        = optional
   stateOrProvinceName    = optional
   localityName        = optional
   organizationName    = optional
   organizationalUnitName    = optional
   commonName        = supplied
   emailAddress        = optional
   
   ####################################################################
   [ req ]
   default_bits        = 1024
   default_keyfile     = privkey.pem
   distinguished_name    = req_distinguished_name
   attributes        = req_attributes
   x509_extensions    = v3_ca    # The extentions to add to the self signed cert
   
   # Passwords for private keys if not present they will be prompted for
   # input_password = secret
   # output_password = secret
   
   # This sets a mask for permitted string types. There are several options.
   # default: PrintableString, T61String, BMPString.
   # pkix     : PrintableString, BMPString.
   # utf8only: only UTF8Strings.
   # nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
   # MASK:XXXX a literal mask value.
   # WARNING: current versions of Netscape crash on BMPStrings or UTF8Strings
   # so use this option with caution!
   string_mask = nombstr
   
   # req_extensions = v3_req # The extensions to add to a certificate request
   
   [ req_distinguished_name ]
   countryName            = Country Name
   countryName_default        = US
   countryName_min            = 2
   countryName_max            = 2
   
   stateOrProvinceName        = State
   stateOrProvinceName_default    = Georgia
   
   localityName            = Locality (city etc)
   localityName_default            = Atlanta
   
   0.organizationName        = Golden Code Development Corporation
   0.organizationName_default    = Golden Code Development Corporation
   
   # we can do this but it is not needed normally :-)
   #1.organizationName        = Second Organization Name (eg, company)
   #1.organizationName_default    = World Wide Web Pty Ltd
   
   organizationalUnitName        = Organizational Unit
   organizationalUnitName_default    = IT Operations
   
   commonName            = Subject Name
   commonName_max            = 64
   
   emailAddress            = email
   emailAddress_max        = 64
   
   # SET-ex3            = SET extension number 3
   
   [ req_attributes ]
   challengePassword        = A challenge password
   challengePassword_min        = 4
   challengePassword_max        = 20
   
   unstructuredName        = An optional company name
   
   [ usr_cert ]
   
   # These extensions are added when 'ca' signs a request.
   
   # This goes against PKIX guidelines but some CAs do it and some software
   # requires this to avoid interpreting an end user certificate as a CA.
   
   basicConstraints=CA:FALSE
   
   # Here are some examples of the usage of nsCertType. If it is omitted
   # the certificate can be used for anything *except* object signing.
   
   # This is OK for an SSL server.
   # nsCertType            = server
   
   # For an object signing certificate this would be used.
   # nsCertType = objsign
   
   # For normal client use this is typical
   # nsCertType = client, email
   
   # and for everything including object signing:
   #nsCertType = client, email, objsign
   
   # This is typical in keyUsage for a client certificate.
   # keyUsage = nonRepudiation, digitalSignature, keyEncipherment
   
   # This will be displayed in Netscape's comment listbox.
   nsComment            = "OpenSSL Generated Certificate"
   
   # PKIX recommendations harmless if included in all certificates.
   subjectKeyIdentifier=hash
   authorityKeyIdentifier=keyid,issuer:always
   
   # This stuff is for subjectAltName and issuerAltname.
   # Import the email address.
   # subjectAltName=email:copy
   # An alternative to produce certificates that aren't
   # deprecated according to PKIX.
   # subjectAltName=email:move
   
   # Copy subject details
   # issuerAltName=issuer:copy
   
   #nsCaRevocationUrl        = http://www.domain.dom/ca-crl.pem
   #nsBaseUrl
   #nsRevocationUrl
   #nsRenewalUrl
   #nsCaPolicyUrl
   #nsSslServerName
   
   [ v3_req ]
   
   # Extensions to add to a certificate request
   
   basicConstraints = CA:FALSE
   keyUsage = nonRepudiation, digitalSignature, keyEncipherment
   
   [ v3_ca ]
   
   
   # Extensions for a typical CA
   
   
   # PKIX recommendation.
   
   subjectKeyIdentifier=hash
   
   authorityKeyIdentifier=keyid:always,issuer:always
   
   # This is what PKIX recommends but some broken software chokes on critical
   # extensions.
   #basicConstraints = critical,CA:true
   # So we do this instead.
   basicConstraints = CA:true
   
   # Key usage: this is typical for a CA certificate. However since it will
   # prevent it being used as an test self-signed certificate it is best
   # left out by default.
   # keyUsage = cRLSign, keyCertSign
   
   # Some might want this also
   # nsCertType = sslCA, emailCA
   
   # Include email address in subject alt name: another PKIX recommendation
   # subjectAltName=email:copy
   # Copy issuer details
   # issuerAltName=issuer:copy
   
   # DER hex encoding of an extension: beware experts only!
   # obj=DER:02:03
   # Where 'obj' is a standard or added object
   # You can even override a supported extension:
   # basicConstraints= critical, DER:30:03:01:01:FF
   
   [ crl_ext ]
   
   # CRL extensions.
   # Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.
   
   # issuerAltName=issuer:copy
   authorityKeyIdentifier=keyid:always,issuer:always


3. Create /var/ssl directory.
   
   
4. Run the CA creation command:
   /usr/local/bin/CA.pl -newca


5. Switch to the /var/ssl directory. The following steps are taken from there.


6. Create a self-signed root CA certificate (passphrase: 1qaz), valid for 10 years, using this command: openssl req -config /etc/openssl.cnf -new -x509 -keyout private/gcd-root-ca-key.pem -out gcd-root-ca-cert.pem -days 3650 


7. Using your favorite editor, create the serial number file gcd-root-ca-cert.srl and put characters 01 there.

Appendix D. Issuing Sample SSL Certificates Using OpenSSL and Your Own CA

Creating the P2J Server Certificate

1. Change the directory to /var/ssl.


2. Enter the superuser mode su to obtain the write access to the CA files.
   
   
3. Generate a new pair: private key and public certificate using this command:
   openssl req -config /etc/openssl.cnf -new -keyout newreq.pem -out newreq.pem
   
   The dialog should look like this:
   Country Name [US]:
   State [Georgia]:
   Locality (city etc) [Atlanta]:
   Golden Code Development Corporation [Golden Code Development Corporation]:
   Organizational Unit [IT Operations]:
   Subject Name []:P2J Server
   email []:
   
   Please enter the following 'extra' attributes
   to be sent with your certificate request
   A challenge password []:
   An optional company name []:
   
   
4. Sign the newly created certificate using this command and the root CA password 1qaz:
   openssl ca -config /etc/openssl.cnf -policy policy_anything -out newcert.pem -infiles newreq.pem
   


5. Rename and save the private key file:
   mv newreq.pem p2jserver-key.pem 


6. Verify the information in the certificate:
   openssl x509 -in newcert.pem -noout -text


7. Save the certificate:
   openssl x509 -in newcert.pem -out p2jserver-cert.pem
   rm newcert.pem
   

Creating the Key Store and the Trust Store Files

1. Copy the root CA certificate gcd-root-ca-cert.pem and the P2J server certificate p2jserver-cert.pem into your target test directory (testcases/simple/server_prep). 
   Make it your current directory.


2. Import the root CA certificate into a new trust store shtrust.store under the alias gcdrootca:
   keytool -import -keystore shtrust.store -alias gcdrootca -file gcd-root-ca-cert.pem
   
   The dialog should look like this:
   Enter keystore password:  poiuyt
   Owner: CN=GCD Certification Authority, OU=IT Operations, O=Golden Code Development Corporation, L=Atlanta, ST=Georgia, C=US
   Issuer: CN=GCD Certification Authority, OU=IT Operations, O=Golden Code Development Corporation, L=Atlanta, ST=Georgia, C=US
   Serial number: 0
   Valid from: Mon Feb 14 11:44:36 EST 2005 until: Thu Feb 12 11:44:36 EST 2015
   Certificate fingerprints:
            MD5:  72:7F:DC:1F:BF:2B:B8:60:E0:1B:89:0E:8A:27:5F:DA
            SHA1: 78:A1:B7:F3:80:2E:C9:D6:46:62:09:95:03:EC:D1:F5:DC:A1:B8:DA
   Trust this certificate? [no]:  yes
   Certificate was added to keystore


3. Import the P2J server certificate into the same trust store under the alias p2jserver:
   keytool -import -keystore shtrust.store -alias p2jserver -file p2jserver-cert.pem


4. Prepare the P2J server's private key for import into a key store:
   openssl pkcs8 -in p2jserver-key.pem -topk8 -outform DER -nocrypt -out p2jserver-key.der
   
   Use 1234 as a passphrase.
   
   
5. Import the P2J server's private key and public certificate into a new key store stdsrvkey.store under the alias  standard:
   java com.goldencode.p2j.security.KeyImport stdsrvkey.store standard p2jserver-key.der p2jserver-cert.pem
   
   The dialog should look like this:
   Enter keystore password:xcvbnm
   Enter key entry password:876543
   Keystore: stdsrvkey.store, alias standard, RSA private key imported.
   
   
6. Remove the temporary key file:
   rm p2jserver-key.der
   
   

Importing certificates into the directory

1. Remove the existing directory file:
   rm min_directory.xml


2. Rerun the directory creation utility:
   java com.goldencode.p2j.test.MinStartupDirectory standard_server.xml
   

Appendix E.  Vendor-Specific Database Setup

PostgreSQL

• Main Page:  http://www.postgresql.org
• 8.1.3 Core Distribution:  http://wwwmaster.postgresql.org/download/mirrors-ftp?file=source%2Fv8.1.3%2Fpostgresql-8.1.3.tar.bz2
• 8.1.3-compatible JDBC driver (already included in the P2J distribution):  http://jdbc.postgresql.org/download/postgresql-8.1-405.jdbc3.jar
• 8.1 User Manual (PDF - US version):  http://www.postgresql.org/files/documentation/pdf/8.1/postgresql-8.1-US.pdf
• 8.1 User Manual (PDF - A4 version):  http://www.postgresql.org/files/documentation/pdf/8.1/postgresql-8.1-A4.pdf

Special Preparation on Linux - Collation Fix

1. Ensure the Linux package which provides the libc locale database sources is installed on the target machine.
2. Run localedef --help and review the bottom of the output to determine which directories contain these source files (as well as the path which contains the system's binary locales).  The source will often reside in some derivative of i18n, such as /usr/share/i18n.  The binaries will often reside in subdirectories of /usr/lib/locale.
   
3. Login as the system's superuser.
4. Switch to the directory containing the charmap files (e.g., /usr/share/i18n/charmaps).  Locate the archive containing the ISO-8859-1 charmap definition.  Decompress it if necessary (it may be gzipped or otherwise archived).
5. Copy the custom P2J locale source file from the p2j/locale subdirectory into the system's locales source directory (e.g., /usr/share/i18n/locales).
6. Run the locale compiler:  localedef -c -f ISO-8859-1 -i en_US@p2j_basic /usr/lib/locale/en_US@p2j_basic/.  If the directory for locale binaries is not /usr/lib/locale, replace this portion of the target path accordingly.

Installation

Launch the Server

su postgres -c "/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data 2>&1 | tee pgsql.log"

Create the gc Superuser

createuser -s -P -E gc

Configure the Server

# "local" is for Unix domain socket connections only
local all all trust
# IPv4 local connections:
host all all 127.0.0.1/32 trust
# IPv6 local connections:
host all all ::1/128 trust

# "local" is for Unix domain socket connections only
#local all all trust
# IPv4 local connections:
host all gc 127.0.0.1/32 md5
# IPv6 local connections:
host all gc ::1/128 md5

Test the Client Connection

createdb -U gc -h localhost test
psql -U gc -h localhost test
dropdb -U gc -h localhost test

Create the P2J Target Database(s)

createdb -U gc -h localhost -E LATIN1 xyz

psql -U gc -h localhost <schema-create-xyz.sql

Appendix F.  Notes on Running a P2J Client

Job Control and P2J Client

Appendix G.  Making Admin Client Use Separate JVM

1. Download the latest JDK from http://java.sun.com/javase/downloads/index.jsp and install it somewhere (here - /opt/java)
2. Create a symbolic link from /usr/lib/jvm to the installed JDK:

   cd /usr/lib/jvm
   sudo ln -s /opt/java/jdk1.6.0_12 java-6u12-sun

3. Create /usr/lib/jvm/.java-6u12-sun.jinfo as follows:

   me=java-6-sun-1.6.0.12
   alias=java-6u12-sun
   priority=64
   section=non-free
   jre ControlPanel /usr/lib/jvm/java-6u12-sun/jre/bin/ControlPanel
   jre java /usr/lib/jvm/java-6u12-sun/jre/bin/java
   jre java_vm /usr/lib/jvm/java-6u12-sun/jre/bin/java_vm
   jre javaws /usr/lib/jvm/java-6u12-sun/jre/bin/javaws
   jre jcontrol /usr/lib/jvm/java-6u12-sun/jre/bin/jcontrol
   jre keytool /usr/lib/jvm/java-6u12-sun/jre/bin/keytool
   jre pack200 /usr/lib/jvm/java-6u12-sun/jre/bin/pack200
   jre policytool /usr/lib/jvm/java-6u12-sun/jre/bin/policytool
   jre rmid /usr/lib/jvm/java-6u12-sun/jre/bin/rmid
   jre rmiregistry /usr/lib/jvm/java-6u12-sun/jre/bin/rmiregistry
   jre unpack200 /usr/lib/jvm/java-6u12-sun/jre/bin/unpack200
   jre orbd /usr/lib/jvm/java-6u12-sun/jre/bin/orbd
   jre servertool /usr/lib/jvm/java-6u12-sun/jre/bin/servertool
   jre tnameserv /usr/lib/jvm/java-6u12-sun/jre/bin/tnameserv
   jre jexec /usr/lib/jvm/java-6u12-sun/jre/lib/jexec
   jdk HtmlConverter /usr/lib/jvm/java-6u12-sun/bin/HtmlConverter
   jdk appletviewer /usr/lib/jvm/java-6u12-sun/bin/appletviewer
   jdk apt /usr/lib/jvm/java-6u12-sun/bin/apt
   jdk extcheck /usr/lib/jvm/java-6u12-sun/bin/extcheck
   jdk idlj /usr/lib/jvm/java-6u12-sun/bin/idlj
   jdk jar /usr/lib/jvm/java-6u12-sun/bin/jar
   jdk jarsigner /usr/lib/jvm/java-6u12-sun/bin/jarsigner
   jdk java-rmi.cgi /usr/lib/jvm/java-6u12-sun/bin/java-rmi.cgi
   jdk javac /usr/lib/jvm/java-6u12-sun/bin/javac
   jdk javadoc /usr/lib/jvm/java-6u12-sun/bin/javadoc
   jdk javah /usr/lib/jvm/java-6u12-sun/bin/javah
   jdk javap /usr/lib/jvm/java-6u12-sun/bin/javap
   jdk jconsole /usr/lib/jvm/java-6u12-sun/bin/jconsole
   jdk jdb /usr/lib/jvm/java-6u12-sun/bin/jdb
   jdk jhat /usr/lib/jvm/java-6u12-sun/bin/jhat
   jdk jinfo /usr/lib/jvm/java-6u12-sun/bin/jinfo
   jdk jmap /usr/lib/jvm/java-6u12-sun/bin/jmap
   jdk jps /usr/lib/jvm/java-6u12-sun/bin/jps
   jdk jrunscript /usr/lib/jvm/java-6u12-sun/bin/jrunscript
   jdk jsadebugd /usr/lib/jvm/java-6u12-sun/bin/jsadebugd
   jdk jstack /usr/lib/jvm/java-6u12-sun/bin/jstack
   jdk jstat /usr/lib/jvm/java-6u12-sun/bin/jstat
   jdk jstatd /usr/lib/jvm/java-6u12-sun/bin/jstatd
   jdk jvisualvm /usr/lib/jvm/java-6u12-sun/bin/jvisualvm
   jdk native2ascii /usr/lib/jvm/java-6u12-sun/bin/native2ascii
   jdk rmic /usr/lib/jvm/java-6u12-sun/bin/rmic
   jdk schemagen /usr/lib/jvm/java-6u12-sun/bin/schemagen
   jdk serialver /usr/lib/jvm/java-6u12-sun/bin/serialver
   jdk wsgen /usr/lib/jvm/java-6u12-sun/bin/wsgen
   jdk wsimport /usr/lib/jvm/java-6u12-sun/bin/wsimport
   jdk xjc /usr/lib/jvm/java-6u12-sun/bin/xjc
   plugin xulrunner-1.9-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin firefox-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin firefox-3.0-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin iceape-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin iceweasel-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin mozilla-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin midbrowser-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   plugin xulrunner-javaplugin.so /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so
   

4. Create a Perl script for one time use and save it as /tmp/java6u12sun.pl:

   #!/usr/bin/perl
   
   use strict;
   
   # Read .jinfo file.
   my @lines = ();
   open(JINFO, '/usr/lib/jvm/.java-6u12-sun.jinfo')
   or die "Can't open .jinfo file.";
   @lines = <JINFO>;
   close(JINFO);
   
   # Install alternatives.
   
   for (@lines)
   {
   if ($_=~ m+/usr/lib/jvm/java-6u12-sun+)
   {
   my @split = split ' ', $_;
   system "update-alternatives --install /usr/bin/@split[1] @split[1] @split[2] 64";
   }
   }
   1;
   

5. Run the script to install alternatives:

   cd /tmp
   chmod +x java6u12sun.pl
   sudo ./java6u12sun.pl
   

6. Select the java-6u12-sun jav alternative, i.e.

   sudo update-java-alternatives -s java-6u12-sun
   

7. Make sure you use FIrefox 3. Check the plugins directory of the Firefox profile. If there is no symbolic link from there to the /usr/lib/jvm/java-6u12-sun/jre/lib/i386/libnpjp2.so file, then create it using ln -s ... command.
8. Run ControlPanel. This utility has multiple tabs. Select the Java tab and press the View button in the Java Applet Runtime Settings pane. Make sure there is only one checked box in the Enabled column and that the line is for the JRE version you've just installed.
9. Restart the browser and now everything is ready. 
10. Note that multiple JVMs for applets will cause multiple Java Console windows to appear if they are configured to be open automatically.