iamjerryyeung

internet to cisco

2012-01-26T20:21:00.000-08:00

1. mac book connect to ethernet, then VPN
2. turn on air port
3. Use "sharing", check internet sharing with from "ethernet" to "airport"
4. run Charles, change the HTTP Proxy port to 9988
5. on iPad, go to wifi -> linksys -> Proxy, click manual, type in the ip address of air port and port of HTTP proxy defined in charles

2011-12-06T22:59:00.000-08:00

http://www.javamex.com/tutorials/memory/instrumentation.shtml

classmexer to find out the size of an Java object (could be deep) using Instrumentation

hibernate insert false

2011-11-13T14:02:00.001-08:00

http://stackoverflow.com/questions/2468106/hibernate-update-jpa-foreign-key

android phone gap plugin

2011-09-28T23:04:00.001-07:00

http://wiki.phonegap.com/w/page/36753494/How%20to%20Create%20a%20PhoneGap%20Plugin%20for%20Android

android certificate

2011-09-28T22:53:00.001-07:00

http://www.realmb.com/droidCert/

stock essp sale

2011-09-19T12:58:00.000-07:00

on 9-19-2011 492 + 365 =857

12-2004, 6-2005

certificate checking

2011-09-12T17:15:00.001-07:00

http://jcalcote.wordpress.com/2010/06/22/managing-a-dynamic-java-trust-store/

xcodebuild

2011-09-11T12:16:00.000-07:00

http://stackoverflow.com/questions/2327257/name-of-provisioning-profile-used-to-sign-an-iphone-app

security find-identity -p codesigning -v;

http://stackoverflow.com/questions/866761/setting-a-provisioning-profile-from-within-xcodebuild-when-making-iphone-apps

http://nachbaur.com/blog/how-to-automate-your-iphone-app-builds-with-hudson

#!/bin/bash

TARGET="Your App"
CONFIGURATION="Release"
SDK="iphoneos"
PROFILE_PATH="/Users/jkp/Desktop/foo.mobileprovision"
IDENTITY="iPhone Distribution: Your Company Ltd"
KEYCHAIN="/Users/jkp/Desktop/keychain"
PASSWORD="foobar"

open "${PROFILE_PATH}"
sleep 5
osascript -e "tell application \"Xcode\" to quit"
security unlock-keychain -p ${PASSWORD} ${KEYCHAIN}
xcodebuild -target "${TARGET}" -configuration ${CONFIGURATION} -sdk iphoneos CODE_SIGN_IDENTITY="${IDENTITY}" OTHER_CODE_SIGN_FLAGS="--keychain ${KEYCHAIN}"

mobile web app add to home screen scripthttp://cubiq.org/add-to-home-screen

2011-08-19T16:16:00.001-07:00

http://cubiq.org/add-to-home-screen

javascript debug

2011-08-19T15:21:00.001-07:00

http://pmuellr.blogspot.com/2009/09/javascript-tracing.html

debug iphone app

2011-08-19T15:14:00.000-07:00

http://muellerware.org/papers/remote-web-inspector-baby-steps.html

push notitfication

2011-05-07T16:06:00.000-07:00

http://dalelane.co.uk/blog/?p=938

xtify

MQTT

browser url checking for certificate

2010-09-09T17:13:00.000-07:00

http://fusesource.com/docs/broker/5.3/security/i382183.html

The HTTPS URL integrity check is specified by RFC 2818, published by the Internet Engineering Task Force (IETF) at http://www.ietf.org/rfc/rfc2818.txt.

How to specify the certificate identity

The certificate identity used in the URL integrity check can be specified in one of the following ways:

Using commonName

The usual way to specify the certificate identity (for the purpose of the URL integrity check) is through the Common Name (CN) in the subject DN of the certificate.

For example, if a server supports secure TLS connections at the following URL:

https://www.progress.com/secure

The corresponding server certificate would have the following subject DN:

C=IE,ST=Co. Dublin,L=Dublin,O=Progress,
OU=System,CN=www.progress.com

Where the CN has been set to the host name, www.progress.com.

For details of how to set the subject DN in a new certificate, see Use the CA to Create Signed Certificates in a Java Keystore and Use the CA to Create Signed Certificates in a Java Keystore .

Using subjectAltName (multi-homed hosts)

Using the subject DN’s Common Name for the certificate identity has the disadvantage that only one host name can be specified at a time. If you deploy a certificate on a multi-homed host, however, you might find it is practical to allow the certificate to be used with any of the multi-homed host names. In this case, it is necessary to define a certificate with multiple, alternative identities, and this is only possible using the subjectAltName certificate extension.

For example, if you have a multi-homed host that supports connections to either of the following host names:

www.progress.com
fusesource.com

Then you can define a subjectAltName that explicitly lists both of these DNS host names. If you generate your certificates using the openssl utility, edit the relevant line of your openssl.cnf configuration file to specify the value of the subjectAltName extension, as follows:

subjectAltName=DNS:www.progress.com,DNS:fusesource.com

Where the HTTPS protocol matches the server host name against either of the DNS host names listed in the subjectAltName (the subjectAltName takes precedence over the Common Name).

The HTTPS protocol also supports the wildcard character, *, in host names. For example, you can define the subjectAltName as follows:

subjectAltName=DNS:*.progress.com

This certificate identity matches any three-component host name in the domain progress.com. For example, the wildcarded host name matches either www.progress.com or fusesource.com, but does not match www.fusesource.com.

GC

2010-05-18T22:46:00.001-07:00

http://it.cybergav.in/2009/09/22/how-to-deal-with-concurrent-mode-failures-in-the-hotspot-jvm/

http://java.sun.com/developer/technicalArticles/Programming/GCPortal/

http://web.princeton.edu/sites/isapps/jasig/2004summerWestminster/Presentations/java-sig2004_garbagecollection.pdf

http://developers.sun.com/mobility/midp/articles/garbage/#14.2.2

find out disk space usage

2009-05-25T22:19:00.001-07:00

#!/bin/sh df -H | grep -vE '^Filesystem|tmpfs|cdrom' | awk '{ print $5 " " $1 }' | while read output; do   echo $output   usep=$(echo $output | awk '{ print $1}' | cut -d'%' -f1  )   partition=$(echo $output | awk '{ print $2 }' )   if [ $usep -ge 90 ]; then     echo "Running out of space \"$partition ($usep%)\" on $(hostname) as on $(date)" |      mail -s "Alert: Almost out of disk space $usep%" you@somewhere.com   fi done

MySql show table status

information retrieval search

2009-05-25T20:40:00.000-07:00

http://people.ischool.berkeley.edu/~hearst/irbook/
http://www.stanford.edu/class/cs240/readings/dean.pdf

skip DTD validation

2009-04-20T10:45:00.001-07:00

http://stackoverflow.com/questions/243728/how-to-disable-dtd-at-runtime-in-javas-xpath

DAO

2009-04-08T16:11:00.001-07:00

http://www.ibm.com/developerworks/library/j-dao/

http://java.sun.com/blueprints/patterns/DAO.html

java tip

2009-04-04T20:38:00.001-07:00

http://www.javaspecialists.eu/archive/Issue142.html

http://www.1001javatips.com/

javascript template

2008-10-08T21:48:00.000-07:00

http://code.google.com/p/trimpath/wiki/JavaScriptTemplates

TrimPath

keytool keystore

2008-09-09T16:53:00.000-07:00

(Java 6 allows user to import private key and cert now)

http://cunning.sharp.fm/2008/06/importing_private_keys_into_a.html

(For older library, you may need the keyimport program)

http://www.nealgroothuis.name/import-a-private-key-into-a-java-keystore/

ssl certificate openssl

2008-08-13T23:55:00.000-07:00

http://www.noah.org/wiki/CSR_Apache

openssl conver pem der ber

2008-08-06T21:05:00.001-07:00

http://www.middleware.vt.edu/doku.php?id=middleware:ed:edid:usage%20

hibernate lazy

2008-07-23T14:08:00.000-07:00

http://blog.xebia.com/2008/03/08/advanced-hibernate-proxy-pitfalls/

trapgen

2008-07-12T17:50:00.001-07:00

http://www.ncomtech.com/trapgen.html

mysql vs postgres comparison

2008-07-11T20:47:00.000-07:00

http://www-css.fnal.gov/dsg/external/freeware/pgsql-vs-mysql.html

wireshark ssl

2008-06-28T17:43:00.001-07:00

http://blogs.sun.com/beuchelt/entry/decrypting_ssl_traffic_with_wireshark

mysql

2008-06-27T23:04:00.000-07:00

http://hackmysql.com/mysqlsla_filters

openssl

2008-06-04T10:33:00.000-07:00

http://security.ncsa.uiuc.edu/research/grid-howtos/usefulopenssl.php

ldap

2008-05-17T16:15:00.001-07:00

http://www.sybase.com/content/1026313/SYSD1039LDAP_WP.pdf

memory leak

2008-03-30T22:23:00.001-07:00

http://www.ibm.com/developerworks/java/library/j-jtp11225/index.html

certificate management tool

2008-03-30T16:12:00.000-07:00

TinyCA

garbage collector

2008-03-23T20:03:00.000-07:00

http://chaoticjava.com/posts/parallel-and-concurrent-garbage-collectors/

java nio

2008-03-10T22:08:00.000-07:00

http://www.particle.kth.se/~lindsey/JavaCourse/Book/Part1/Supplements/Chapter09/nio.html

http://access1.sun.com/techarticles/BuffersAPI/BuffersAPIFundamentals.html#buf2

java nio

2008-03-10T21:04:00.001-07:00

http://www.scribd.com/doc/267405/-Java-NIO-with-Grizzly

threadlocal

2008-03-10T15:17:00.000-07:00

http://www.ddj.com/java/184405382

static final private anonymous class for the threadlocal subclass
each thread will have the container ( the get()) which has a reference to the instance of threadlocal. conceptually, there is a map with key the currentthread and the object.

HTML calendar

2008-03-04T13:22:00.001-08:00

Bazillyo's Spiffy DHTML Popup Calendar

webservice nillable null value

2008-02-19T18:59:00.000-08:00

http://www.ibm.com/developerworks/xml/library/ws-tip-null.html

escape urlencode

2008-02-18T13:06:00.001-08:00

http://xkr.us/articles/javascript/encode-compare/

firefox clipboard

2008-01-26T19:41:00.001-08:00

http://www.jeffothy.com/weblog/clipboard-copy/

javascript diff tool

2008-01-20T22:52:00.001-08:00

http://snowtide.com/jsdifflib

xsd import include

2007-11-30T09:30:00.000-08:00

http://developers.sun.com/jsenterprise/nb_enterprise_pack/reference/techart/namespaces2.html

wsdl

2007-11-17T18:23:00.000-08:00

http://www.ibm.com/developerworks/webservices/library/ws-castor/

pkcs

2007-11-06T16:54:00.000-08:00

http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/sag_cmimportexport.mspx?mfr=true

http://support.citrix.com/article/CTX109031&printable=true

About exporting certificate from IIS to netscaler

http://dev2dev.bea.com/pub/a/2006/08/pfx-pem-certificate-formats.html

http://www.grennan.com/CA-HOWTO-1.html

vmware standford

2007-10-25T11:23:00.000-07:00

http://forum.stanford.edu/events/archive/security-workshop/CSW-02-Speaker-Slides/Edouard-Bugnion.ppt#362,18,I/O Interposition example: Networking

http://download3.vmware.com/vmworld/2005/pac195-a.pdf

http://www.cs.binghamton.edu/~kchiu/cs552-f04/slides/virtual_machines.ppt#280,5,Advantages/Disadvantages of Virtual Machines

xmlresponse AJAX

2007-08-04T19:50:00.000-07:00

catch xmlHttp.responseXML
if(!xmlResponse !xmlResponse.documentElement) throw
var nodeName = xmlResponse.documentElmeent.nodeName;
if(nodeName == "parsererror") throw ...

create XML document

2007-08-04T19:38:00.000-07:00

if(document.implementation && document.implementation.createDocument){ xmlDoc = document.implementation.createDocument("","",null); } else if (window.ActiveXObject){ xmlDoc = new ActiveXObject("Microsoft.XMLDOM");
}

velocity event cartridge

2007-08-04T19:32:00.001-07:00

http://www.java2s.com/Code/Java/Velocity/AsimpledemonstrationofhowtheeventhandlingfeaturesoftheVelocityServletEngineareused.htm

stop a thread

2007-07-18T22:23:00.001-07:00

http://www.forward.com.au/javaProgramming/threadReturnsPackage/ToCatchAThread.html

html hint

2007-03-28T10:46:00.001-07:00

http://www.cs.tut.fi/~jkorpela/

youtube

2007-03-18T18:30:00.000-07:00

http://blog.go4teams.com/?p=56

certiface PKCS12

2007-03-13T17:15:00.000-07:00

http://www.dartmouth.edu/~pkilab/pages/Move_Keypair.html

Moving Keys and Certificates
Your private key and public key certificate are saved on the computer from which you enrolled in the PKI system. For the purposes of web authentication it is possible to enroll more than once, but this can be confusing for other uses of PKI like encryption and digital signature. In those cases it is preferrable to use the same private key and public key certificate on multiple web browsers and computers. This page explains how to move your PKI private key and personal certificate to another web browser or computer. There are 3 steps, exporting the keys to a file, transferring the file and importing the keys into another configuration. Because the applications of a PKI rely on keeping your private key "private", the process for doing this keeps the information encrypted as it is being moved.
The PKCS standards define a format called PKCS #12 for transferring a private key and a public key certificates. (A PKCS #7 file is used to transfer only public key certificates and NOT the private key.) PKCS #12 is supported by Nestcape, Mozilla and versions of Internet Explorer after 5.5. On Windows, the filetype .pfx is a synonym for the .p12 file type used by Netscape/Mozilla. Some older versions of Windows need file extension definitions to be added for ".p12".
A PKCS #12 file includes a password-encrypted envelope to protect the private key. This password is used only for this file and has no connection to the password used to secure your keys in your web browser or operating system key storage. The password is created when you create the .p12 export file and must be provided to decrypt the contents when you import the file somewhere else. The key export and import functions are usually part of the user interface provided to manage certificates in web browser. Be sure to transfer the binary file by a method that doesn't mistakenly convert it to text. This is easy to do since the settings in many programs default to "text" files. The file can be e-mailed as a binary attachment, transferred as a binary file with FTP or copied to and from a removable or shared disk. A copy of a PKCS #12 file containing your provate key and certificate the on a removable disk can be a useful backup if the hard disk on your computer fails.

http://wso2.org/library/767

About Feedback wso2.com
-->
Home
Library
SVN
Wiki
JIRA
Mail
Forum
Downloads
Tools
Blog
Library
Articles
Tutorials
Interviews
Presentations
Podcasts
Knowledge Base
Submit Story
Aggregator
Projects
WSO2
Web Services Framework
Web Services Application Server
Enterprise Service Bus
Commons
Apache
Axis
Axis2
AXIOM
Kandula
Neethi
Rampart
Sandesha
Sandesha2
Savan
Synapse
WSS4J
Hot on The Tank
IDE Integration for WSO2 WSAS - Lahiru Sandakith
10 Minute Guide to Installing WSO2 WSAS on WebLogic- Afkham Azeez
W3C Workshop on Web of Services for Enterprise Computing- Jonathan Marsh
Download WSO2 ESB for Java, v1.0 beta 1
Flows, Phases, Handlers, and Modules- Samisa Abeysinghe
JSON Support for Apache Axis2- Isuru Suriarachchi

Personalize
Login
Register
Search

Google Ads

OpenSSL Tutorial for Apache Rampart/C
Submitted on February 14, 2007 - 22:59. Tutorials Rampart > C
This tutorial by Kaushalye Kapuruge explains how to use the OpenSSL toolkit to configure Apache Rampart/C, security module of Apache Axis2/C in your system. This includes the necessary practical knowledge as well as the conceptual knowledge. For example, installing OpenSSL, obtaining certificates, how to configure a key store, etc. You are always welcome to refer to OpenSSL documentation and other related resources, but it usually takes time to connect them together. We suggest that you to complete this tutorial before configuring Rampart/C.
X509 Certificates, Public and Private Keys in Brief
In public key infrastructure we use two keys, namely Public key and Private key. The relationship between these two is that one encrypts data, and the other decrypts it. The difference is that one is kept a secret (hence named private key) whilst the other is published. An x509 certificate is issued by a certificate authority binding such a public key. A Certificate Authority (CA) is a trusted third party that issues digital certificates for other parties. In Rampart/C, we use X509 certificates to encrypt messages and corresponding private keys to decrypt the messages.
Ways You Can Use Certificates/Keys in Rampart/C
There are two ways you can use x509 certificates and keys.
As a single entity - PEM format
In a Key Store - PKCS12 format
PEM Format
Privacy Enhanced Mail (PEM) is the widely used format for certificates and keys. A PEM file contains two header lines that wraps base64 encoded certificate data. The format of a X509 certificate is as follows.------BEGIN CERTIFICATE-----(Base64 encoded certificate data)------END CERTIFICATE----If you need to configure the receiver's certificate to encrypt data, you have to have it in PEM format.
PKCS12 Key Stores
PKCS12 is a standard that stores certificate and private key pairs in a secure way. Usually, a certificate/key pair is stored with a password. Unlike a PEM file, PKCS12 contains binary data and may contain more than one certificate. OpenSSL provides tools to convert from/to PKCS12 format. We will describe how to do this later. Rampart/C supports PKCS12 key stores. The file extension should be .pfx.
Installing OpenSSL
UNIX
The quickest and easiest way to install OpenSSL in your system is through the Advanced Package Tool (apt).%apt-get install openssl.
This will install the latest OpenSSL version available in your system.
The other way is to download the tarball from the OpenSSL official Web site. For example, if you have downloaded openssl-0.9.x.tar.gz, extract it first.%gunzip openssl-0.9.x.tar.gz%tar xvf openssl-0.9.x.tarThen go to the directory openssl-0.9.x.
To install it in the default location (i.e./usr/local/ssl), use the following command sequence.%./config%make%make install
Win32
There are many vendors who provide binary distributions of the latest OpenSSL release. You can then follow the installation procedure, which is vendor specific.
Obtaining a Certificate
There are three methods to obtain an x509 certificate.
Generate a self-signed certificate.
Signed by a local CA
Signed by a recognized authority such as Verisign
Generate a Self-Signed Certificate
This is the simplest procedure, but is of very little use. For testing purposes you might need to generate a certificate quickly. Use the following command to generate a self-signed x509 certificate (mycert.pem), which is valid for 365 days and an RSA key (mykey.pem) of length 1024.openssl req -x509 -nodes -days 365 -newkey rsa:1024 \-keyout mykey.pem -out mycert.pem
Then you have to answer a few questions. The information you provide by answering these questions will be stored in the certificate.Country Name (2 letter code) [AU]:State or Province Name (full name) [Some-State]:Locality Name (eg, city) []:Organization Name (eg, company) [Internet Widgits Pty Ltd]:Organizational Unit Name (eg, section) []:Common Name (eg, YOUR name) []:Email Address []:
Create Your Own CA and Sign Your Certificates
A self-signed certificate is of no use as it is not signed by a third party. There are well known third parties like Verisign and Thawte. However, getting a certificate signed is a complex and costly process. If you need to form a small trust community (e.g. for your company or with your clients) you can create your own Certificate Authority. This process has been simplified thanks to a pearl script available in OpenSSL distribution. If you have used default installation settings, this script (CA.pl) can be located in /usr/lib/ssl/misc/CA.pl. First create a directory for your CA. Then copy CA.pl and /usr/lib/ssl/openssl.cnf to the directory you just created. Now run the CA.pl script.%./CA.pl -newca
If you press Enter, the script will create a new certificate/key pair for you. If you already have a certificate and you need to use it, just type the filename. Now you have a certificate authority setup in a sub directory called "demoCA". Simple, right?
Let's try to sign a certificate using the CA we have just set up. Copy your certificate request to the current directory and rename it to newreq.pem (In the next section, we will discuss how to generate a certificate request). Next, issue the following command.%./CA.pl -sign
If everything is successful and the request is a valid one, a new certificate called newcert.pem will be created in the same directory.
Sign Your Certificate by a Recognized Authority
Signing you certificate by a recognized certificate authority consists of two steps. First you have to generate a certificate request locally. Then you need to fill a form providing some information and send it to the CA.
Here we describe how to generate such a request using OpenSSL. First you need to generate a private key. If you already have a private key skip this step.%openssl genrsa -out x.key 1024
Then use that private key to generate your request to the CA.%openssl req -new -key x.key -out request.pem
This will create a file called request.pem from the private key (x.key). The requset file has the following format.-----BEGIN CERTIFICATE REQUEST-----(Base64 encoded certificate request data)-----END CERTIFICATE REQUEST-----
Then you have to provide your information to the certificate authority. Usually this can be done by sending a fax or by filling an online application. Make sure that you are sending accurate information and especially check your request and the information in it. Use the following commands for verification.%openssl req -noout -text -in request.pem%openssl req -noout -verify -key x.key -in request.pem
Exporting PEM Files to PKCS12 Key Stores
Use the openssl pkcs12 tool to export a certificate/key pair to a pkcs12 store. Assume that you have a key (x.key) and a certificate (x.cert). The first step is to have both of them in a single file (x.pem). Then export the pair to a pkcs12 keystore (x.pfx).%cat x.cert x.key > x.pem%openssl pkcs12 -export -in x.pem -out x.pfx
Then enter a password to secure your keys in the keystore.
Extracting Key/Cert Pair from a PKCS12 Key Store
If you have your keys/certificates in a pkcs12 keystore, you might need to extract them. For example, you might need to give you certificate to another party. Here, we will show you how you can do this.%openssl pkcs12 -in x.pfx -clcerts -nokeys -out x2.cert
Enter the password you used in the export process. Similarly, you can get the private key too.%openssl pkcs12 -in x.pfx -nocerts -out x2.key
Extract Information from a Certificate
If you get a certificate from another party, you might need to extract information from it. An x509 certificate contains the following information.
Certificate version
Serial Number
Algorithm ID
Issuer
Validity period
Subject
Public Key Algorithm
Subject Public Key
Issuer Unique Identifier (Optional)
Subject Unique Identifier (Optional)
Extensions (Optional)
Certificate Signature Algorithm
Certificate Signature Use the following command to extract information from a certificate in PEM format. %openssl x509 -noout -text -in x.cert
To extract information from a certificate, which is stored in a pkcs12 key store, use the following.%openssl pkcs12 -in x_store.pfx -nokeys -clcerts openssl x509 -noout -text
Glossary
PKCS12 : Public Key Cryptography Standards #12. Personal Information Exchange Syntax Standard.
PEM: Privacy Enhanced Mail, is a standard for exchanging mails over the web in a secure way.
X509: A standard for Public Key Infrastructure, defines formats for public key certificates and validation algorithms.
CA: An entity issuing and validating digital certificates.
References

http://gagravarr.org/writing/openssl-certs/general.shtml

firewall inspection SQLNET

2007-03-07T14:25:00.000-08:00

http://home.cfl.rr.com/dealgroup/pix/pix_page_4.htm

html legend fieldset

2007-02-07T22:32:00.000-08:00

http://www.htmldog.com/guides/htmladvanced/forms/

load balance

2007-01-14T15:59:00.000-08:00

http://1wt.eu/articles/2006_lb/index_04.html

grapher

2006-12-16T10:20:00.000-08:00

http://srufaculty.sru.edu/david.dailey/grapher/grapher.96.html

using javascript to draw graph.
similar to mxgraph using VML

open source network management

2006-11-20T21:36:00.000-08:00

http://www.mergere.com/m2book_download.jsp
ziptie.org
http://www.webtide.com/

certificate

2006-11-15T22:32:00.000-08:00

http://docs.codehaus.org/display/JETTY/How+to+configure+SSL
keytool - Key and Certificate Management Tool
Manages a keystore (database) of private keys and their associated X.509 certificate chains authenticating the corresponding public keys. Also manages certificates from trusted entities.
SYNOPSIS
keytool [ commands ]

DESCRIPTION
keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers.
A certificate is a digitally signed statement from one entity (person, company, etc.), saying that the public key (and some other information) of some other entity has a particular value. (See Certificates.) When data is digitally signed, the signature can be verified to check the data integrity and authenticity. Integrity means that the data has not been modified or tampered with, and authenticity means the data indeed comes from whoever claims to have created and signed it.

keytool stores the keys and certificates in a so-called keystore. The default keystore implementation implements the keystore as a file. It protects private keys with a password.

The jarsigner tool uses information from a keystore to generate or verify digital signatures for Java ARchive (JAR) files. (A JAR file packages class files, images, sounds, and/or other digital data in a single file). jarsigner verifies the digital signature of a JAR file, using the certificate that comes with it (it is included in the signature block file of the JAR file), and then checks whether or not the public key of that certificate is "trusted", i.e., is contained in the specified keystore.

Please note: the keytool and jarsigner tools completely replace the javakey tool provided in JDK 1.1. These new tools provide more features than javakey, including the ability to protect the keystore and private keys with passwords, and the ability to verify signatures in addition to generating them. The new keystore architecture replaces the identity database that javakey created and managed. It is possible to import the information from an identity database into a keystore, via the -identitydb keytool command.

Keystore Entries
There are two different types of entries in a keystore:
key entries - each holds very sensitive cryptographic key information, which is stored in a protected format to prevent unauthorized access. Typically, a key stored in this type of entry is a secret key, or a private key accompanied by the certificate "chain" for the corresponding public key. The keytool and jarsigner tools only handle the latter type of entry, that is private keys and their associated certificate chains.

trusted certificate entries - each contains a single public key certificate belonging to another party. It is called a "trusted certificate" because the keystore owner trusts that the public key in the certificate indeed belongs to the identity identified by the "subject" (owner) of the certificate. The issuer of the certificate vouches for this, by signing the certificate.
Keystore Aliases
All keystore entries (key and trusted certificate entries) are accessed via unique aliases. Aliases are case-insensitive; the aliases Hugo and hugo would refer to the same keystore entry.

An alias is specified when you add an entity to the keystore using the -genkey command to generate a key pair (public and private key) or the -import command to add a certificate or certificate chain to the list of trusted certificates. Subsequent keytool commands must use this same alias to refer to the entity.

For example, suppose you use the alias duke to generate a new public/private key pair and wrap the public key into a self-signed certificate (see Certificate Chains) via the following command:

keytool -genkey -alias duke -keypass dukekeypasswd

This specifies an inital password of "dukekeypasswd" required by subsequent commands to access the private key assocated with the alias duke. If you later want to change duke's private key password, you use a command like the following:
keytool -keypasswd -alias duke -keypass dukekeypasswd -new newpass

This changes the password from "dukekeypasswd" to "newpass".
Please note: A password should not actually be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system. If you don't specify a required password option on a command line, you will be prompted for it. When typing in a password at the password prompt, the password is currently echoed (displayed exactly as typed), so be careful not to type it in front of anyone.

Keystore Location
Each keytool command has a -keystore option for specifying the name and location of the persistent keystore file for the keystore managed by keytool. The keystore is by default stored in a file named .keystore in the user's home directory, as determined by the "user.home" system property. On Solaris systems "user.home" defaults to the user's home directory.
Keystore Creation
A keystore is created whenever you use a -genkey, -import, or -identitydb command to add data to a keystore that doesn't yet exist.
More specifically, if you specify, in the -keystore option, a keystore that doesn't yet exist, that keystore will be created.

If you don't specify a -keystore option, the default keystore is a file named .keystore in your home directory. If that file does not yet exist, it will be created.

Keystore Implementation
The KeyStore class provided in the java.security package supplies well-defined interfaces to access and modify the information in a keystore. It is possible for there to be multiple different concrete implementations, where each implementation is that for a particular type of keystore.
Currently, two command-line tools (keytool and jarsigner) and a GUI-based tool named Policy Tool make use of keystore implementations. Since KeyStore is publicly available, users can write additional security applications that use it.

There is a built-in default implementation, provided by Sun Microsystems. It implements the keystore as a file, utilizing a proprietary keystore type (format) named "JKS". It protects each private key with its individual password, and also protects the integrity of the entire keystore with a (possibly different) password.

Keystore implementations are provider-based. More specifically, the application interfaces supplied by KeyStore are implemented in terms of a "Service Provider Interface" (SPI). That is, there is a corresponding abstract KeystoreSpi class, also in the java.security package, which defines the Service Provider Interface methods that "providers" must implement. (The term "provider" refers to a package or a set of packages that supply a concrete implementation of a subset of services that can be accessed by the Java Security API.) Thus, to provide a keystore implementation, clients must implement a "provider" and supply a KeystoreSpi subclass implementation, as described in How to Implement a Provider for the Java Cryptography Architecture.

Applications can choose different types of keystore implementations from different providers, using the "getInstance" factory method supplied in the KeyStore class. A keystore type defines the storage and data format of the keystore information, and the algorithms used to protect private keys in the keystore and the integrity of the keystore itself. Keystore implementations of different types are not compatible.

keytool works on any file-based keystore implementation. (It treats the keytore location that is passed to it at the command line as a filename and converts it to a FileInputStream, from which it loads the keystore information.) The jarsigner and policytool tools, on the other hand, can read a keystore from any location that can be specified using a URL.

For keytool and jarsigner, you can specify a keystore type at the command line, via the -storetype option. For Policy Tool, you can specify a keystore type via the "Change Keystore" command in the Edit menu.

If you don't explicitly specify a keystore type, the tools choose a keystore implementation based simply on the value of the keystore.type property specified in the security properties file. The security properties file is called java.security, and it resides in the security properties directory, java.home/lib/security, where java.home is the runtime environment's directory (the jre directory in the SDK or the top-level directory of the Java 2 Runtime Environment).

Each tool gets the keystore.type value and then examines all the currently-installed providers until it finds one that implements keystores of that type. It then uses the keystore implementation from that provider.

The KeyStore class defines a static method named getDefaultType that lets applications and applets retrieve the value of the keystore.type property. The following line of code creates an instance of the default keystore type (as specified in the keystore.type property):

KeyStore keyStore = KeyStore.getInstance(KeyStore.getDefaultType());

The default keystore type is "jks" (the proprietary type of the keystore implementation provided by Sun). This is specified by the following line in the security properties file:

keystore.type=jks

To have the tools utilize a keystore implementation other than the default, you can change that line to specify a different keystore type.

For example, if you have a provider package that supplies a keystore implementation for a keystore type called "pkcs12", change the line to

keystore.type=pkcs12

Note: case doesn't matter in keystore type designations. For example, "JKS" would be considered the same as "jks".
Supported Algorithms and Key Sizes
keytool allows users to specify any key pair generation and signature algorithm supplied by any of the registered cryptographic service providers. That is, the keyalg and sigalg options for various commands must be supported by a provider implementation. The default key pair generation algorithm is "DSA". The signature algorithm is derived from the algorithm of the underlying private key: If the underlying private key is of type "DSA", the default signature algorithm is "SHA1withDSA", and if the underlying private key is of type "RSA", the default signature algorithm is "MD5withRSA".
When generating a DSA key pair, the key size must be in the range from 512 to 1024 bits, and must be a multiple of 64. The default key size for any algorithm is 1024 bits.

Certificates
A certificate (also known as a public-key certificate) is a digitally signed statement from one entity (the issuer), saying that the public key (and some other information) of another entity (the subject) has some specific value.
Let us expand on some of the key terms used in this sentence:

Public Keys
These are numbers associated with a particular entity, and are intended to be known to everyone who needs to have trusted interactions with that entity. Public keys are used to verify signatures.
Digitally Signed
If some data is digitally signed it has been stored with the "identity" of an entity, and a signature that proves that entity knows about the data. The data is rendered unforgeable by signing with the entity's private key.
Identity
A known way of addressing an entity. In some systems the identity is the public key, in others it can be anything from a Unix UID to an Email address to an X.509 Distinguished Name.
Signature
A signature is computed over some data using the private key of an entity (the signer, which in the case of a certificate is also known as the issuer).
Private Keys
These are numbers, each of which is supposed to be known only to the particular entity whose private key it is (that is, it's supposed to be kept secret). Private and public keys exist in pairs in all public key cryptography systems (also referred to as "public key crypto systems"). In a typical public key crypto system, such as DSA, a private key corresponds to exactly one public key. Private keys are used to compute signatures.
Entity
An entity is a person, organization, program, computer, business, bank, or something else you are trusting to some degree.
Basically, public key cryptography requires access to users' public keys. In a large-scale networked environment it is impossible to guarantee that prior relationships between communicating entities have been established or that a trusted repository exists with all used public keys. Certificates were invented as a solution to this public key distribution problem. Now a Certification Authority (CA) can act as a trusted third party. CAs are entities (for example, businesses) that are trusted to sign (issue) certificates for other entities. It is assumed that CAs will only create valid and reliable certificates, as they are bound by legal agreements. There are many public Certification Authorities, such as VeriSign, Thawte, Entrust, and so on. You can also run your own Certification Authority using products such as the Netscape/Microsoft Certificate Servers or the Entrust CA product for your organization.

Using keytool, it is possible to display, import, and export certificates. It is also possible to generate self-signed certificates.

keytool currently handles X.509 certificates.

X.509 Certificates
The X.509 standard defines what information can go into a certificate, and describes how to write it down (the data format). All X.509 certificates have the following data, in addition to the signature:
Version
This identifies which version of the X.509 standard applies to this certificate, which affects what information can be specified in it. Thus far, three versions are defined. keytool can import and export v1, v2, and v3 certificates. It generates v1 certificates.
Serial Number
The entity that created the certificate is responsible for assigning it a serial number to distinguish it from other certificates it issues. This information is used in numerous ways, for example when a certificate is revoked its serial number is placed in a Certificate Revocation List (CRL).
Signature Algorithm Identifier
This identifies the algorithm used by the CA to sign the certificate.
Issuer Name
The X.500 Distinguished Name of the entity that signed the certificate. This is normally a CA. Using this certificate implies trusting the entity that signed this certificate. (Note that in some cases, such as root or top-level CA certificates, the issuer signs its own certificate.)
Validity Period
Each certificate is valid only for a limited amount of time. This period is described by a start date and time and an end date and time, and can be as short as a few seconds or almost as long as a century. The validity period chosen depends on a number of factors, such as the strength of the private key used to sign the certificate or the amount one is willing to pay for a certificate. This is the expected period that entities can rely on the public value, if the associated private key has not been compromised.
Subject Name
The name of the entity whose public key the certificate identifies. This name uses the X.500 standard, so it is intended to be unique across the Internet. This is the X.500 Distinguished Name (DN) of the entity, for example,
CN=Java Duke, OU=Java Software Division, O=Sun Microsystems Inc, C=US

(These refer to the subject's Common Name, Organizational Unit, Organization, and Country.)
Subject Public Key Information
This is the public key of the entity being named, together with an algorithm identifier which specifies which public key crypto system this key belongs to and any associated key parameters.
X.509 Version 1 has been available since 1988, is widely deployed, and is the most generic.

X.509 Version 2 introduced the concept of subject and issuer unique identifiers to handle the possibility of reuse of subject and/or issuer names over time. Most certificate profile documents strongly recommend that names not be reused, and that certificates should not make use of unique identifiers. Version 2 certificates are not widely used.

X.509 Version 3 is the most recent (1996) and supports the notion of extensions, whereby anyone can define an extension and include it in the certificate. Some common extensions in use today are: KeyUsage (limits the use of the keys to particular purposes such as "signing-only") and AlternativeNames (allows other identities to also be associated with this public key, e.g. DNS names, Email addresses, IP addresses). Extensions can be marked critical to indicate that the extension should be checked and enforced/used. For example, if a certificate has the KeyUsage extension marked critical and set to "keyCertSign" then if this certificate is presented during SSL communication, it should be rejected, as the certificate extension indicates that the associated private key should only be used for signing certificates and not for SSL use.

All the data in a certificate is encoded using two related standards called ASN.1/DER. Abstract Syntax Notation 1 describes data. The Definite Encoding Rules describe a single way to store and transfer that data.

X.500 Distinguished Names
X.500 Distinguished Names are used to identify entities, such as those which are named by the subject and issuer (signer) fields of X.509 certificates. keytool supports the following subparts:
commonName - common name of a person, e.g., "Susan Jones"

organizationUnit - small organization (e.g, department or division) name, e.g., "Purchasing"

organizationName - large organization name, e.g., "ABCSystems, Inc."

localityName - locality (city) name, e.g., "Palo Alto"

stateName - state or province name, e.g., "California"

country - two-letter country code, e.g., "CH"

When supplying a distinguished name string as the value of a -dname option, as for the -genkey or -selfcert commands, the string must be in the following format:

CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCode

where all the italicized items represent actual values and the above keywords are abbreviations for the following:

CN=commonName
OU=organizationUnit
O=organizationName
L=localityName
S=stateName
C=country

A sample distinguished name string is

CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=US

and a sample command using such a string is
keytool -genkey -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino,
S=California, C=US" -alias mark

Case does not matter for the keyword abbreviations. For example, "CN", "cn", and "Cn" are all treated the same.

Order matters; each subcomponent must appear in the designated order. However, it is not necessary to have all the subcomponents. You may use a subset, for example:

CN=Steve Meier, OU=SunSoft, O=Sun, C=US

If a distinguished name string value contains a comma, the comma must be escaped by a "\" character when you specify the string on a command line, as in

cn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=us

It is never necessary to specify a distinguished name string on a command line. If it is needed for a command, but not supplied on the command line, the user is prompted for each of the subcomponents. In this case, a comma does not need to be escaped by a "\".

The Internet RFC 1421 Certificate Encoding Standard
Certificates are often stored using the printable encoding format defined by the Internet RFC 1421 standard, instead of their binary encoding. This certificate format, also known as "Base 64 encoding", facilitates exporting certificates to other applications by email or through some other mechanism.

Certificates read by the -import and -printcert commands can be in either this format or binary encoded.

The -export command by default outputs a certificate in binary encoding, but will instead output a certificate in the printable encoding format, if the -rfc option is specified.

The -list command by default prints the MD5 fingerprint of a certificate. If the -v option is specified, the certificate is printed in human-readable format, while if the -rfc option is specified, the certificate is output in the printable encoding format.

In its printable encoding format, the encoded certificate is bounded at the beginning by

-----BEGIN CERTIFICATE-----

and at the end by

-----END CERTIFICATE-----

Certificate Chains
keytool can create and manage keystore "key" entries that each contain a private key and an associated certificate "chain". The first certificate in the chain contains the public key corresponding to the private key.

When keys are first generated (see the -genkey command), the chain starts off containing a single element, a self-signed certificate. A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). Whenever the -genkey command is called to generate a new public/private key pair, it also wraps the public key into a self-signed certificate.

Later, after a Certificate Signing Request (CSR) has been generated (see the -certreq command) and sent to a Certification Authority (CA), the response from the CA is imported (see -import), and the self-signed certificate is replaced by a chain of certificates. At the bottom of the chain is the certificate (reply) issued by the CA authenticating the subject's public key. The next certificate in the chain is one that authenticates the CA's public key.

In many cases, this is a self-signed certificate (that is, a certificate from the CA authenticating its own public key) and the last certificate in the chain. In other cases, the CA may return a chain of certificates. In this case, the bottom certificate in the chain is the same (a certificate signed by the CA, authenticating the public key of the key entry), but the second certificate in the chain is a certificate signed by a different CA, authenticating the public key of the CA you sent the CSR to. Then, the next certificate in the chain will be a certificate authenticating the second CA's key, and so on, until a self-signed "root" certificate is reached. Each certificate in the chain (after the first) thus authenticates the public key of the signer of the previous certificate in the chain.

Many CAs only return the issued certificate, with no supporting chain, especially when there is a flat hierarchy (no intermediates CAs). In this case, the certificate chain must be established from trusted certificate information already stored in the keystore.

A different reply format (defined by the PKCS#7 standard) also includes the supporting certificate chain, in addition to the issued certificate. Both reply formats can be handled by keytool.

The top-level (root) CA certificate is self-signed. However, the trust into the root's public key does not come from the root certificate itself (anybody could generate a self-signed certificate with the distinguished name of say, the VeriSign root CA!), but from other sources like a newspaper. The root CA public key is widely known. The only reason it is stored in a certificate is because this is the format understood by most tools, so the certificate in this case is only used as a "vehicle" to transport the root CA's public key. Before you add the root CA certificate to your keystore, you should view it (using the -printcert option) and compare the displayed fingerprint with the well-known fingerprint (obtained from a newspaper, the root CA's webpage, etc.).

Importing Certificates
To import a certificate from a file, use the -import command, as in

keytool -import -alias joe -file jcertfile.cer

This sample command imports the certificate(s) in the file jcertfile.cer and stores it in the keystore entry identified by the alias joe.

You import a certificate for two reasons:

to add it to the list of trusted certificates, or

to import a certificate reply received from a CA as the result of submitting a Certificate Signing Request (see the -certreq command) to that CA.
Which type of import is intended is indicated by the value of the -alias option:

If the alias points to a key entry, then keytool assumes you are importing a certificate reply. keytool checks whether the public key in the certificate reply matches the public key stored with the alias, and exits if they are different.

If the alias does not point to a key entry, then keytool assumes you are adding a trusted certificate entry. In this case, the alias should not already exist in the keystore. If the alias does already exist, then keytool outputs an error, since there is already a trusted certificate for that alias, and does not import the certificate. If the alias does not exist in the keystore, keytool creates a trusted certificate entry with the specified alias and associates it with the imported certificate.
WARNING Regarding Importing Trusted Certificates
IMPORTANT: Be sure to check a certificate very carefully before importing it as a trusted certificate!
View it first (using the -printcert command, or the -import command without the -noprompt option), and make sure that the displayed certificate fingerprint(s) match the expected ones. For example, suppose someone sends or emails you a certificate, and you put it in a file named /tmp/cert. Before you consider adding the certificate to your list of trusted certificates, you can execute a -printcert command to view its fingerprints, as in

keytool -printcert -file /tmp/cert
Owner: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
Issuer: CN=ll, OU=ll, O=ll, L=ll, S=ll, C=ll
Serial Number: 59092b34
Valid from: Thu Sep 25 18:01:13 PDT 1997 until: Wed Dec 24 17:01:13 PST 1997
Certificate Fingerprints:
MD5: 11:81:AD:92:C8:E5:0E:A2:01:2E:D4:7A:D7:5F:07:6F
SHA1: 20:B6:17:FA:EF:E5:55:8A:D0:71:1F:E8:D6:9D:C0:37:13:0E:5E:FE

Then call or otherwise contact the person who sent the certificate, and compare the fingerprint(s) that you see with the ones that they show. Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (for example, an attacker's) certificate. If such an attack took place, and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed (for example, a JAR file with malicious class files inside).
Note: it is not required that you execute a -printcert command prior to importing a certificate, since before adding a certificate to the list of trusted certificates in the keystore, the -import command prints out the certificate information and prompts you to verify it. You then have the option of aborting the import operation. Note, however, this is only the case if you invoke the -import command without the -noprompt option. If the -noprompt option is given, there is no interaction with the user.

Exporting Certificates
To export a certificate to a file, use the -export command, as in

keytool -export -alias jane -file janecertfile.cer

This sample command exports jane's certificate to the file janecertfile.cer. That is, if jane is the alias for a key entry, the command exports the certificate at the bottom of the certificate chain in that keystore entry. This is the certificate that authenticates jane's public key.
If, instead, jane is the alias for a trusted certificate entry, then that trusted certificate is exported.

Displaying Certificates
To print out the contents of a keystore entry, use the -list command, as in

keytool -list -alias joe

If you don't specify an alias, as in
keytool -list

the contents of the entire keystore are printed.
To display the contents of a certificate stored in a file, use the -printcert command, as in

keytool -printcert -file certfile.cer

This displays information about the certificate stored in the file certfile.cer.

Note: This works independently of a keystore, i.e., you do not need a keystore in order to display a certificate that's stored in a file.

Generating a self-signed certificate
A self-signed certificate is one for which the issuer (signer) is the same as the subject (the entity whose public key is being authenticated by the certificate). Whenever the -genkey command is called to generate a new public/private key pair, it also wraps the public key into a self-signed certificate.

You may occasionally wish to generate a new self-signed certificate. For example, you may want to use the same key pair under a different identity (distinguished name). For example, suppose you change departments. You can then:

copy (clone) the original key entry. See -keyclone.

generate a new self-signed certificate for the cloned entry, using your new distinguished name. See below.

generate a Certificate Signing Requests for the cloned entry, and import the reply certificate or certificate chain. See the -certreq and -import commands.

delete the original (now obsolete) entry. See -delete.

To generate a self-signed certificate, use the -selfcert command, as in
keytool -selfcert -alias dukeNew -keypass b92kqmp
-dname "cn=Duke Smith, ou=Purchasing, o=BlueSoft, c=US"

The generated certificate is stored as a single-element certificate chain in the keystore entry identified by the specified alias (in this case "dukeNew"), where it replaces the existing certificate chain.
COMMAND AND OPTION NOTES
The various commands and their options are listed and described below . Note:

All command and option names are preceded by a minus sign (-).

The options for each command may be provided in any order.

All items not italicized or in braces or square brackets are required to appear as is.

Braces surrounding an option generally signify that a default value will be used if the option is not specified on the command line. Braces are also used around the -v, -rfc, and -J options, which only have meaning if they appear on the command line (that is, they don't have any "default" values other than not existing).

Brackets surrounding an option signify that the user is prompted for the value(s) if the option is not specified on the command line. (For a -keypass option, if you do not specify the option on the command line, keytool will first attempt to use the keystore password to recover the private key, and if this fails, will then prompt you for the private key password.)

Items in italics (option values) represent the actual values that must be supplied. For example, here is the format of the -printcert command:
keytool -printcert {-file cert_file} {-v}

When specifying a -printcert command, replace cert_file with the actual file name, as in:

keytool -printcert -file VScert.cer

Option values must be quoted if they contain a blank (space).

The -help command is the default. Thus, the command line
keytool

is equivalent to
keytool -help

Option Defaults
Below are the defaults for various option values.
-alias "mykey"

-keyalg "DSA"

-keysize 1024

-validity 90

-keystore the file named .keystore in the user's home directory

-file stdin if reading, stdout if writing

The signature algorithm (-sigalg option) is derived from the algorithm of the underlying private key: If the underlying private key is of type "DSA", the -sigalg option defaults to "SHA1withDSA", and if the underlying private key is of type "RSA", -sigalg defaults to "MD5withRSA".
Options that Appear for Most Commands
The -v option can appear for all commands except -help. If it appears, it signifies "verbose" mode; detailed certificate information will be output.
There is also a -Jjavaoption option that may appear for any command. If it appears, the specified javaoption string is passed through directly to the Java interpreter. (keytool is actually a "wrapper" around the interpreter.) This option should not contain any spaces. It is useful for adjusting the execution environment or memory usage. For a list of possible interpreter options, type java -h or java -X at the command line.

These options may appear for all commands operating on a keystore:

-storetype storetype
This qualifier specifies the type of keystore to be instantiated. The default keystore type is the one that is specified as the value of the "keystore.type" property in the security properties file, which is returned by the static getDefaultType method in java.security.KeyStore.

-keystore keystore
The keystore (database file) location. Defaults to the file .keystore in the user's home directory, as determined by the "user.home" system property. On Solaris systems "user.home" defaults to the user's home directory.

-storepass storepass
The password which is used to protect the integrity of the keystore.
storepass must be at least 6 characters long. It must be provided to all commands that access the keystore contents. For such commands, if a -storepass option is not provided at the command line, the user is prompted for it.

When retrieving information from the keystore, the password is optional; if no password is given, the integrity of the retrieved information cannot be checked and a warning is displayed.

Be careful with passwords - see Warning Regarding Passwords.

-provider provider-class-name
Used to specify the name of cryptographic service provider's master class file when the service provider is not listed in the security properties file.

Warning Regarding Passwords
Most commands operating on a keystore require the store password. Some commands require a private key password.

Passwords can be specified on the command line (in the -storepass and -keypass options, respectively). However, a password should not be specified on a command line or in a script unless it is for testing purposes, or you are on a secure system.

If you don't specify a required password option on a command line, you will be prompted for it. When typing in a password at the password prompt, the password is currently echoed (displayed exactly as typed), so be careful not to type it in front of anyone.

COMMANDS
See also the Command and Option Notes.
Adding Data to the Keystore
-genkey {-alias alias} {-keyalg keyalg} {-keysize keysize} {-sigalg sigalg} [-dname dname] [-keypass keypass] {-validity valDays} {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Generates a key pair (a public key and associated private key). Wraps the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.

keyalg specifies the algorithm to be used to generate the key pair, and keysize specifies the size of each key to be generated. sigalg specifies the algorithm that should be used to sign the self-signed certificate; this algorithm must be compatible with keyalg. See Supported Algorithms and Key Sizes.

dname specifies the X.500 Distinguished Name to be associated with alias, and is used as the issuer and subject fields in the self-signed certificate. If no distinguished name is provided at the command line, the user will be prompted for one.

keypass is a password used to protect the private key of the generated key pair. If no password is provided, the user is prompted for it. If you press RETURN at the prompt, the key password is set to the same password as that used for the keystore. keypass must be at least 6 characters long. Be careful with passwords - see Warning Regarding Passwords.

valDays tells the number of days for which the certificate should be considered valid.

-import {-alias alias} {-file cert_file} [-keypass keypass] {-noprompt} {-trustcacerts} {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Reads the certificate or certificate chain (where the latter is supplied in a PKCS#7 formatted reply) from the file cert_file, and stores it in the keystore entry identified by alias. If no file is given, the certificate or PKCS#7 reply is read from stdin.

keytool can import X.509 v1, v2, and v3 certificates, and PKCS#7 formatted certificate chains consisting of certificates of that type. The data to be imported must be provided either in binary encoding format, or in printable encoding format (also known as Base64 encoding) as defined by the Internet RFC 1421 standard. In the latter case, the encoding must be bounded at the beginning by a string that starts with "-----BEGIN", and bounded at the end by a string that starts with "-----END".

You import a certificate for two reasons:

to add it to the list of trusted certificates, or

to import a certificate reply received from a CA as the result of submitting a Certificate Signing Request (see the -certreq command) to that CA.
Importing a New Trusted Certificate
When importing a new trusted certificate, alias must not yet exist in the keystore. Before adding the certificate to the keystore, keytool tries to verify it by attempting to construct a chain of trust from that certificate to a self-signed certificate (belonging to a root CA), using trusted certificates that are already available in the keystore.

If the -trustcacerts option has been specified, additional certificates are considered for the chain of trust, namely the certificates in a file named "cacerts".

If keytool fails to establish a trust path from the certificate to be imported up to a self-signed certificate (either from the keystore or the "cacerts" file), the certificate information is printed out, and the user is prompted to verify it, e.g., by comparing the displayed certificate fingerprints with the fingerprints obtained from some other (trusted) source of information, which might be the certificate owner himself/herself. Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! -- see WARNING Regarding Importing Trusted Certificates. The user then has the option of aborting the import operation. If the -noprompt option is given, however, there will be no interaction with the user.

Importing a Certificate Reply
When importing a certificate reply, the certificate reply is validated using trusted certificates from the keystore, and optionally using the certificates configured in the "cacerts" keystore file (if the -trustcacerts option was specified).

The methods of determining whether the certificate reply is trusted are described in the following:

If the reply is a single X.509 certificate, keytool attempts to establish a trust chain, starting at the certificate reply and ending at a self-signed certificate (belonging to a root CA). The certificate reply and the hierarchy of certificates used to authenticate the certificate reply form the new certificate chain of alias. If a trust chain cannot be established, the certificate reply is not imported. In this case, keytool does not print out the certificate and prompt the user to verify it, because it is very hard (if not impossible) for a user to determine the authenticity of the certificate reply.

If the reply is a PKCS#7 formatted certificate chain, the chain is first ordered (with the user certificate first and the self-signed root CA certificate last), before keytool attempts to match the root CA certificate provided in the reply with any of the trusted certificates in the keystore or the "cacerts" keystore file (if the -trustcacerts option was specified). If no match can be found, the information of the root CA certificate is printed out, and the user is prompted to verify it, e.g., by comparing the displayed certificate fingerprints with the fingerprints obtained from some other (trusted) source of information, which might be the root CA itself. The user then has the option of aborting the import operation. If the -noprompt option is given, however, there will be no interaction with the user.
The new certificate chain of alias replaces the old certificate chain associated with this entry. The old chain can only be replaced if a valid keypass, the password used to protect the private key of the entry, is supplied. If no password is provided, and the private key password is different from the keystore password, the user is prompted for it. Be careful with passwords - see Warning Regarding Passwords.

The cacerts Certificates File
A certificates file named "cacerts" resides in the security properties directory, java.home/lib/security, where java.home is the runtime environment's directory (the jre directory in the SDK or the top-level directory of the Java 2 Runtime Environment).

The "cacerts" file represents a system-wide keystore with CA certificates. System administrators can configure and manage that file using keytool, specifying "jks" as the keystore type. The "cacerts" keystore file ships with several root CA certificates with the following aliases and X.500 owner distinguished names:

Alias: thawtepersonalfreemailca
Owner DN: EmailAddress=personal-freemail@thawte.com,
CN=Thawte Personal Freemail CA,
OU=Certification Services Division,
O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

Alias: thawtepersonalbasicca
Owner DN: EmailAddress=personal-basic@thawte.com,
CN=Thawte Personal Basic CA,
OU=Certification Services Division,
O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

Alias: thawtepersonalpremiumca
Owner DN: EmailAddress=personal-premium@thawte.com,
CN=Thawte Personal Premium CA,
OU=Certification Services Division,
O=Thawte Consulting, L=Cape Town, ST=Western Cape, C=ZA

Alias: thawteserverca
Owner DN: EmailAddress=server-certs@thawte.com,
CN=Thawte Server CA, OU=Certification Services Division,
O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Alias: thawtepremiumserverca
Owner DN: EmailAddress=premium-server@thawte.com,
CN=Thawte Premium Server CA,
OU=Certification Services Division,
O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Alias: verisignclass1ca
Owner DN: OU=Class 1 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

Alias: verisignclass2ca
Owner DN: OU=Class 2 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

Alias: verisignclass3ca
Owner DN: OU=Class 3 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

Alias: verisignclass4ca
Owner DN: OU=Class 4 Public Primary Certification Authority,
O="VeriSign, Inc.", C=US

Alias: verisignserverca
Owner DN: OU=Secure Server Certification Authority,
O="RSA Data Security, Inc.", C=US

Alias: baltimorecodesigningca
Owner DN: CN=Baltimore CyberTrust Code Signing Root,
OU=CyberTrust, O=Baltimore, C=IE

Alias: gtecybertrustglobalca
Owner DN: CN=GTE CyberTrust Global Root,
OU="GTE CyberTrust Solutions, Inc.", O=GTE Corporation, C=US

Alias: baltimorecybertrustca
Owner DN: CN=Baltimore CyberTrust Root,
OU=CyberTrust, O=Baltimore, C=IE

Alias: gtecybertrustca
Owner DN: CN=GTE CyberTrust Root,
O=GTE Corporation, C=US

Alias: gtecybertrust5ca
Owner DN: CN=GTE CyberTrust Root 5,
OU="GTE CyberTrust Solutions, Inc.", O=GTE Corporation, C=US
The initial password of the "cacerts" keystore file is "changeit". System administrators should change that password and the default access permission of that file upon installing the SDK.

--------------------------------------------------------------------------------
IMPORTANT: Verify Your cacerts File
Since you trust the CAs in the cacerts file as entities for signing and issuing certificates to other entities, you must manage the cacerts file carefully. The cacerts file should contain only certificates of the CAs you trust. It is your responsibility to verify the trusted root CA certificates bundled in the cacerts file and make your own trust decisions. To remove an untrusted CA certificate from the cacerts file, use the delete option of the keytool command. You can find the cacerts file in the JRE installation directory. Contact your system administrator if you do not have permission to edit this file.

--------------------------------------------------------------------------------

-selfcert {-alias alias} {-sigalg sigalg} {-dname dname} {-validity valDays} [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Generates an X.509 v1 self-signed certificate, using keystore information including the private key and public key associated with alias. If dname is supplied at the command line, it is used as the X.500 Distinguished Name for both the issuer and subject of the certificate. Otherwise, the X.500 Distinguished Name associated with alias (at the bottom of its existing certificate chain) is used.

The generated certificate is stored as a single-element certificate chain in the keystore entry identified by alias, where it replaces the existing certificate chain.

sigalg specifies the algorithm that should be used to sign the certificate. See Supported Algorithms and Key Sizes.

In order to access the private key, the appropriate password must be provided, since private keys are protected in the keystore with a password. If keypass is not provided at the command line, and is different from the password used to protect the integrity of the keystore, the user is prompted for it. Be careful with passwords - see Warning Regarding Passwords.

valDays tells the number of days for which the certificate should be considered valid.

-identitydb {-file idb_file} {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Reads the JDK 1.1.x-style identity database from the file idb_file, and adds its entries to the keystore. If no file is given, the identity database is read from stdin. If a keystore does not exist, it is created.

Only identity database entries ("identities") that were marked as trusted will be imported in the keystore. All other identities will be ignored. For each trusted identity, a keystore entry will be created. The identity's name is used as the "alias" for the keystore entry.

The private keys from trusted identities will all be encrypted under the same password, storepass. This is the same password that is used to protect the keystore's integrity. Users can later assign individual passwords to those private keys by using the "-keypasswd" keytool command option.

An identity in an identity database may hold more than one certificate, each certifying the same public key. But a keystore key entry for a private key has that private key and a single "certificate chain" (initially just a single certificate), where the first certificate in the chain contains the public key corresponding to the private key. When importing the information from an identity, only the first certificate of the identity is stored in the keystore. This is because an identity's name in an identity database is used as the alias for its corresponding keystore entry, and alias names are unique within a keystore,

Exporting Data
-certreq {-alias alias} {-sigalg sigalg} {-file certreq_file} [-keypass keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Generates a Certificate Signing Request (CSR), using the PKCS#10 format.

A CSR is intended to be sent to a certificate authority (CA). The CA will authenticate the certificate requestor (usually off-line) and will return a certificate or certificate chain, used to replace the existing certificate chain (which initially consists of a self-signed certificate) in the keystore.

The private key and X.500 Distinguished Name associated with alias are used to create the PKCS#10 certificate request. In order to access the private key, the appropriate password must be provided, since private keys are protected in the keystore with a password. If keypass is not provided at the command line, and is different from the password used to protect the integrity of the keystore, the user is prompted for it.

Be careful with passwords - see Warning Regarding Passwords.

sigalg specifies the algorithm that should be used to sign the CSR. See Supported Algorithms and Key Sizes.

The CSR is stored in the file certreq_file. If no file is given, the CSR is output to stdout.

Use the import command to import the response from the CA.

-export {-alias alias} {-file cert_file} {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-rfc} {-v} {-Jjavaoption}
Reads (from the keystore) the certificate associated with alias, and stores it in the file cert_file.

If no file is given, the certificate is output to stdout.

The certificate is by default output in binary encoding, but will instead be output in the printable encoding format, as defined by the Internet RFC 1421 standard, if the -rfc option is specified.

If alias refers to a trusted certificate, that certificate is output. Otherwise, alias refers to a key entry with an associated certificate chain. In that case, the first certificate in the chain is returned. This certificate authenticates the public key of the entity addressed by alias.

Displaying Data
-list {-alias alias} {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v | -rfc} {-Jjavaoption}
Prints (to stdout) the contents of the keystore entry identified by alias. If no alias is specified, the contents of the entire keystore are printed.

This command by default prints the MD5 fingerprint of a certificate. If the -v option is specified, the certificate is printed in human-readable format, with additional information such as the owner, issuer, and serial number. If the -rfc option is specified, certificate contents are printed using the printable encoding format, as defined by the Internet RFC 1421 standard

You cannot specify both -v and -rfc.

-printcert {-file cert_file} {-v} {-Jjavaoption}
Reads the certificate from the file cert_file, and prints its contents in a human-readable format. If no file is given, the certificate is read from stdin.

The certificate may be either binary encoded or in printable encoding format, as defined by the Internet RFC 1421 standard.

Note: This option can be used independently of a keystore.

Managing the Keystore
-keyclone {-alias alias} [-dest dest_alias] [-keypass keypass] [-new new_keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Creates a new keystore entry, which has the same private key and certificate chain as the original entry.

The original entry is identified by alias (which defaults to "mykey" if not provided). The new (destination) entry is identified by dest_alias. If no destination alias is supplied at the command line, the user is prompted for it.

If the private key password is different from the keystore password, then the entry will only be cloned if a valid keypass is supplied. This is the password used to protect the private key associated with alias. If no key password is supplied at the command line, and the private key password is different from the keystore password, the user is prompted for it. The private key in the cloned entry may be protected with a different password, if desired. If no -new option is supplied at the command line, the user is prompted for the new entry's password (and may choose to let it be the same as for the cloned entry's private key).

Be careful with passwords - see Warning Regarding Passwords.

This command can be used to establish multiple certificate chains corresponding to a given key pair, or for backup purposes.

-storepasswd [-new new_storepass] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Changes the password used to protect the integrity of the keystore contents. The new password is new_storepass, which must be at least 6 characters long.

Be careful with passwords - see Warning Regarding Passwords.

-keypasswd {-alias alias} [-keypass old_keypass] [-new new_keypass] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Changes the password under which the private key identified by alias is protected, from old_keypass to new_keypass.

If the -keypass option is not provided at the command line, and the private key password is different from the keystore password, the user is prompted for it.

If the -new option is not provided at the command line, the user is prompted for it.

Be careful with passwords - see Warning Regarding Passwords.

-delete [-alias alias] {-storetype storetype} {-keystore keystore} [-storepass storepass] [-provider provider_class_name] {-v} {-Jjavaoption}
Deletes from the keystore the entry identified by alias. The user is prompted for the alias, if no alias is provided at the command line.

Getting Help
-help
Lists all the commands and their options.

EXAMPLES
Suppose you want to create a keystore for managing your public/private key pair and certificates from entities you trust.

Generating Your Key Pair
The first thing you need to do is create a keystore and generate the key pair. You could use a command such as the following:

keytool -genkey -dname "cn=Mark Jones, ou=JavaSoft, o=Sun, c=US"
-alias business -keypass kpi135 -keystore /working/mykeystore
-storepass ab987c -validity 180

(Please note: This must be typed as a single line. Multiple lines are used in the examples just for legibility purposes.)

This command creates the keystore named "mykeystore" in the "working" directory (assuming it doesn't already exist), and assigns it the password "ab987c". It generates a public/private key pair for the entity whose "distinguished name" has a common name of "Mark Jones", organizational unit of "JavaSoft", organization of "Sun" and two-letter country code of "US". It uses the default "DSA" key generation algorithm to create the keys, both 1024 bits long.

It creates a self-signed certificate (using the default "SHA1withDSA" signature algorithm) that includes the public key and the distinguished name information. This certificate will be valid for 180 days, and is associated with the private key in a keystore entry referred to by the alias "business". The private key is assigned the password "kpi135".

The command could be significantly shorter if option defaults were accepted. As a matter of fact, no options are required; defaults are used for unspecified options that have default values, and you are prompted for any required values. Thus, you could simply have the following:

keytool -genkey

In this case, a keystore entry with alias "mykey" is created, with a newly-generated key pair and a certificate that is valid for 90 days. This entry is placed in the keystore named ".keystore" in your home directory. (The keystore is created if it doesn't already exist.) You will be prompted for the distinguished name information, the keystore password, and the private key password.
The rest of the examples assume you executed the -genkey command without options specified, and that you responded to the prompts with values equal to those given in the first -genkey command, above (a private key password of "kpi135", etc.)

Requesting a Signed Certificate from a Certification Authority
So far all we've got is a self-signed certificate. A certificate is more likely to be trusted by others if it is signed by a Certification Authority (CA). To get such a signature, you first generate a Certificate Signing Request (CSR), via the following:

keytool -certreq -file MarkJ.csr

This creates a CSR (for the entity identified by the default alias "mykey") and puts the request in the file named "MarkJ.csr". Submit this file to a CA, such as VeriSign, Inc. The CA will authenticate you, the requestor (usually off-line), and then will return a certificate, signed by them, authenticating your public key. (In some cases, they will actually return a chain of certificates, each one authenticating the public key of the signer of the previous certificate in the chain.)
Importing a Certificate for the CA
You need to replace your self-signed certificate with a certificate chain, where each certificate in the chain authenticates the public key of the signer of the previous certificate in the chain, up to a "root" CA.

Before you import the certificate reply from a CA, you need one or more "trusted certificates" in your keystore or in the cacerts keystore file (which is described in import command):

If the certificate reply is a certificate chain, you just need the top certificate of the chain (that is, the "root" CA certificate authenticating that CA's public key).

If the certificate reply is a single certificate, you need a certificate for the issuing CA (the one that signed it), and if that certificate is not self-signed, you need a certificate for its signer, and so on, up to a self-signed "root" CA certificate.
The "cacerts" keystore file ships with five VeriSign root CA certificates, so you probably won't need to import a VeriSign certificate as a trusted certificate in your keystore. But if you request a signed certificate from a different CA, and a certificate authenticating that CA's public key hasn't been added to "cacerts", you will need to import a certificate from the CA as a "trusted certificate".

A certificate from a CA is usually either self-signed, or signed by another CA (in which case you also need a certificate authenticating that CA's public key). Suppose company ABC, Inc., is a CA, and you obtain a file named "ABCCA.cer" that is purportedly a self-signed certificate from ABC, authenticating that CA's public key.

Be very careful to ensure the certificate is valid prior to importing it as a "trusted" certificate! View it first (using the keytool -printcert command, or the keytool -import command without the -noprompt option), and make sure that the displayed certificate fingerprint(s) match the expected ones. You can call the person who sent the certificate, and compare the fingerprint(s) that you see with the ones that they show (or that a secure public key repository shows). Only if the fingerprints are equal is it guaranteed that the certificate has not been replaced in transit with somebody else's (for example, an attacker's) certificate. If such an attack took place, and you did not check the certificate before you imported it, you would end up trusting anything the attacker has signed.

If you trust that the certificate is valid, then you can add it to your keystore via the following:

keytool -import -alias abc -file ABCCA.cer

This creates a "trusted certificate" entry in the keystore, with the data from the file "ABCCA.cer", and assigns the alias "abc" to the entry.
Importing the Certificate Reply from the CA
Once you've imported a certificate authenticating the public key of the CA you submitted your certificate signing request to (or there's already such a certificate in the "cacerts" file), you can import the certificate reply and thereby replace your self-signed certificate with a certificate chain. This chain is the one returned by the CA in response to your request (if the CA reply is a chain), or one constructed (if the CA reply is a single certificate) using the certificate reply and trusted certificates that are already available in the keystore where you import the reply or in the "cacerts" keystore file.

For example, suppose you sent your certificate signing request to VeriSign. You can then import the reply via the following, which assumes the returned certificate is named "VSMarkJ.cer":

keytool -import -trustcacerts -file VSMarkJ.cer

Exporting a Certificate Authenticating Your Public Key
Suppose you have used the jarsigner tool to sign a Java ARchive (JAR) file. Clients that want to use the file will want to authenticate your signature.
One way they can do this is by first importing your public key certificate into their keystore as a "trusted" entry. You can export the certificate and supply it to your clients. As an example, you can copy your certificate to a file named MJ.cer via the following, assuming the entry is aliased by "mykey":

keytool -export -alias mykey -file MJ.cer

Given that certificate, and the signed JAR file, a client can use the jarsigner tool to authenticate your signature.
Changing Your Distinguished Name but Keeping your Key Pair
Suppose your distinguished name changes, for example because you have changed departments or moved to a different city. If desired, you may still use the public/private key pair you've previously used, and yet update your distinguished name. For example, suppose your name is Susan Miller, and you created your initial key entry with the alias sMiller and the distinguished name
"cn=Susan Miller, ou=Finance Department, o=BlueSoft, c=us"

Suppose you change from the Finance Department to the Accounting Department. You can still use the previously-generated public/private key pair and yet update your distinguished name by doing the following. First, copy (clone) your key entry:
keytool -keyclone -alias sMiller -dest sMillerNew

(This prompts for the store password and for the initial and destination private key passwords, since they aren't provided at the command line.) Now you need to change the certificate chain associated with the copy, so that the first certificate in the chain uses your different distinguished name. Start by generating a self-signed certificate with the appropriate name:
keytool -selfcert -alias sMillerNew
-dname "cn=Susan Miller, ou=Accounting Department, o=BlueSoft, c=us"

Then generate a Certificate Signing Request based on the information in this new certificate:

keytool -certreq -alias sMillerNew

When you get the CA certificate reply, import it:
keytool -import -alias sMillerNew -file VSSMillerNew.cer

After importing the certificate reply, you may want to remove the initial key entry that used your old distinguished name:
keytool -delete -alias sMiller

SEE ALSO
jar tool documentation

jarsigner tool documentation

the Security trail of the Java Tutorial for examples of the use of keytool

--------------------------------------------------------------------------------
Copyright 1994-2004 Sun Microsystems, Inc.

Java Software

How to configure SSL
This is an overview of how to configure SSL for Jetty, which uses Sun's reference implementation for the Java Secure Sockets Extension (JSSE).

Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding
of the basics. The following links provide some good starting points:

Certificates:
SSL Certificates HOWTO
Mindprod Java Glossary definition
*Keytool:
Keytool for Unix
Keytool for Windows
Other tools:
IBM Keyman
Open SSL:
Mindprod Java Glossary definition
FAQ
The Basics
The following steps are required to configure Jetty for SSL:
Step 1: Generate or obtain a public/private key pair and x509 certificate.
Step 2: Optionally obtain a certificate from a known certificate authority.
Step 3: Load the keys and the certificates into a JSSE Keystore.
Step 4: Configure a JsseListener with the location and passwords for the keystore.

OpenSSL Versus Keytool
For testing, keytool is probably the simplest way to generate the key and certificate you will need. However, IBMs keyman is also pretty good and provides a GUI rather than a command line.

The OpenSSL tools can also be used to generate keys and certificates or to convert ones that have been used with Apache or other servers.
The OpenSSL tool suite is commonly used by other servers such as Apache to generate manipulate keys and certificates. So you may already have some keys and certificates created by openssl, or openssl may be more trusted than keytool or some certificate authorities for step 2 may also prefer the formats produced by ssl.

If you want the option of using the same certificate with Jetty or a web server such as Apache not written in Java, you may prefer to
generate your private key and certificate with openSSL. The Java keytool does not provide options for exporting private keys, and Apache
needs the private key. If you create the key and certificate with openSSL your non-Java web server will have ready access to it.

Step 1: Keys and Certificates
The simplest way generate keys and certificates is to use the keytool application that comes with the JDK, as it generates keys and certificates directly into the keystore. See Step 1a.

If you already have keys and certificates, please goto Step 3 to load them into a JSSE key store.

If you have a renewal certificate to replace one that is expiring, take a look at [Renewing Certificates#renewals].

The commands below only generate minimal keys and certificates. You should read the full manuals of the tools you are using if you wish to specify:

Key size.
Certificate expiry.
Alternate security providers.

Step 1a: Generating a certificate with JDK keytool
The following command will generate a key pair and certificate directly into a keystore:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA
This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt. For example:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA
Enter keystore password: password
What is your first and last name?
[Unknown]: jetty.mortbay.org
What is the name of your organizational unit?
[Unknown]: Jetty
What is the name of your organization?
[Unknown]: Mort Bay Consulting Pty. Ltd.
What is the name of your City or Locality?
[Unknown]:
What is the name of your State or Province?
[Unknown]:
What is the two-letter country code for this unit?
[Unknown]:
Is CN=jetty.mortbay.org, OU=Jetty, O=Mort Bay Consulting Pty. Ltd.,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes

Enter key password for
(RETURN if same as keystore password): password
You now have the minimal requirements to run an SSL connection and could proceed directly to Step 4 to configure an SSL connector.
However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public site will need to Step 2a to obtain a certificate trusted by most popular clients.

Step 1b: Keys and Certificates with openssl
The following command generates a key pair in the file jetty.key:

openssl genrsa -des3 -out jetty.key
You may also wish to use the -rand file argument to provide an arbitrary file to help seed the random number generator.

The following command generates a certificate for the key into the file jetty.crt:

# openssl req -new -x509 -key jetty.key -out jetty.crt
This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:

openssl genrsa -des3 -out jetty.key
Generating RSA private key, 512 bit long modulus
...........................++++++++++++
..++++++++++++
e is 65537 (0x10001)
Enter pass phrase for jetty.key:
Verifying - Enter pass phrase for jetty.key:

# openssl req -new -x509 -key jetty.key -out jetty.crt
Enter pass phrase for jetty.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:.
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgets Pty Ltd]:Mort Bay Consulting Pty. Ltd.
Organizational Unit Name (eg, section) []:Jetty
Common Name (eg, YOUR name) []:jetty.mortbay.org
Email Address []:

#
You now have the minimal requirements to run an SSL connection and could proceed directly to Step 3 to load these keys and certificates into a JSSE keystore. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public site will need to Step 2b to obtain a certificate trusted by most popular clients.

Step 1c: Keys and Certificates from other sources
If you have keys and certificates from other sources, then you can proceed directly to Step 3.

Step 2: Request a trusted certificate
The keys and certificats generated in steps 1a and 1b are sufficient to run an SSL connector. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect.

To obtain a certificate that will be trusted by most common browsers, you need to request a well known certificate authority (CA) to sign your key/certificate. Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, beTRUSTed, among others.

Each CA will have their own instructions which should be followed (look for JSSE or openssl sections), but all will involved a step to
generate a certificate signing request (CSR).

Step 2a: CSR from keytool
The following commands generates the file jetty.csr using keytool for a key/cert already in the keystore:

keytool -certreq -alias jetty -keystore keystore -file jetty.csr

Step 2b: CSR from openssl
The following commands generates the file jetty.csr using openssl for a key in the file jetty.key:

openssl req -new -key jetty.key -out jetty.csr
Note that this command only uses the existing key from jetty.key file and not a certificate in jetty.crt generated by step 1b. The details for the certificate need to be entered again.

Step 3: Loading Keys and Certificates
Once a CA has sent you a certificate, or if you generated your own certificate without keytool, then it will need to be loaded into
a JSSE keystore. If you did not use keytool to generate the key, then it will also need to be loaded into the keystore.

Step 3a: Loading Certificates with keytool
A certificate in PEM form may be directly loaded into a keystore with keytool. The PEM format is a text encoding of certificates and is produced by openssl (as in step 1b) and is returned by some CAs. An example PEM file is:

jetty.crt
-----BEGIN CERTIFICATE-----
MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0
IEJheSBDb25zdWx0aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNV
BAMTEWpldHR5Lm1vcnRiYXkub3JnMB4XDTAzMDQwNjEzMTk1MFoXDTAzMDUwNjEz
MTk1MFowVDEmMCQGA1UEChMdTW9ydCBCYXkgQ29uc3VsdGluZyBQdHkuIEx0ZC4x
DjAMBgNVBAsTBUpldHR5MRowGAYDVQQDExFqZXR0eS5tb3J0YmF5Lm9yZzBcMA0G
CSqGSIb3DQEBAQUAA0sAMEgCQQC5V4oZeVdhdhHqa9L2/ZnKySPWUqqy81riNfAJ
7uALW0kEv/LtlG34dOOcVVt/PK8/bU4dlolnJx1SpiMZbKsFAgMBAAGjga4wgasw
HQYDVR0OBBYEFFV1gbB1XRvUx1UofmifQJS/MCYwMHwGA1UdIwR1MHOAFFV1gbB1
XRvUx1UofmifQJS/MCYwoVikVjBUMSYwJAYDVQQKEx1Nb3J0IEJheSBDb25zdWx0
aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNVBAMTEWpldHR5Lm1v
cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV
OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8
Rcz6oCRvCGCe5kDB
-----END CERTIFICATE-----
The following command will load a PEM encoded certificate in the jetty.crt file into a JSSE keystore:

keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts
Depending on the situation you may not require the -trustcacerts option. Try the operation without it if you like.

NOTE That you need both the private key and the certificate in the keystore. So the certificate should be loaded into the keystore used to generate the CSR (step 2a). If your key pair is not in a keystore (eg if generated as step 1b), then you will need to use the PKCS12 format to load both key and certificate as in step 3b.

If the certificate your receive from the CA is not in a format that keytool understands, then the openssl command can be used to convert
formats:

openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt
Step 3b) Loading keys and certificates via PKCS12

If you have a key and certificate in separate files, they need to be combined into a PKCS12 format file to be loaded into a new keystore. The certificate can be one you generated yourself or one that has been returned from a CA in response to your CSR.

The following openssl command will combine the keys in jetty.key and the certificate in the jetty.crt file into the jetty.pkcs12 file:

openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12
If you have a chain of certificates, because your CA is an intermediary, build the pkcs12 file like this:

# cat example.crt intermediate.crt [intermediate2.crt]... rootCA.crt > cert-chain.txt
# openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
The order of certificates must be from server to rootCA, as per RFC2246 section 7.4.2.

OpenSSL is going to ask you for an "export password". A non-empty password seems to be required to make the next step work. The
resulting PKCS12 file may be loaded into a JSSE keystore with the following jetty utility class:

java -classpath $JETTY_HOME/lib/org.mortbay.jetty.jar org.mortbay.util.PKCS12Import jetty.pkcs12 keystore
This asks for two passphrases. Give the password from the last step as the input passphrase and you are set. The "output passphrase" will need to appear in your jetty.xml config file as both the Password and KeyPassword of the SunJsseListener that will use the certificate.

Step 4: Configure Jetty

8443
30000
/etc/keystore
OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
OBF:1u2u1wml1z7s1z7a1wnl1u2g
/etc/keystore
OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4

Remember that the default port for https is 443 not 80, so change 8443 to 443 if you want to be able to use URL's without explicit port numbers. For a production site it normally makes sense to have a HttpListener on port 80 and a SunJsseListener on port 443. Note that as these are privileged ports, you may want to use a redirection mechanism to map port 80 to eg 8080 and 443 to eg 8443. For details on this, see the [Running Jetty as a non-root user].

The keystore file in this example is given relative to the jetty home directory. For production, choose a private directory with restricted access to keep your keystore in. Even though it has a password on it, the password may be configured into the runtime environment so is vulnerable to theft.

Jetty can now be started the normal way (make sure that jcert.jar, jnet.jar and jsse.jar are on your classpath) and SSL can be used with a URL like:

https://localhost:8443/
Note: The most common mistake at this point is to try to access port 8443 with http rather than https.

If CONFIDENTIAL or INTEGRAL security constraints are being used, then you should also configure the normal HTTP connector with which port to use for SSL:

8080
30000
2
8443

Password Issues
If the passwords are not provided in the configuration, they may be provided as java properties (jetty.ssl.password and jetty.ssl.keypassword) else they will be prompted for.

Remember that putting your password on the command line is a security risk. They can also be set as properties within the config file, but this risks accidental discovery by developers.

If jetty is given a password that begins with "OBF:" it is treated as an obfuscated password. Passwords can be obfuscated by
running org.mortbay.jetty.security.Password as a main class. This can protect passwords from casual observation.

Renewing Certificates
If you are updating your configuration to use a newer certificate, as when the old one is expiring, just do Step 3. If you imported the key and certificate originally using the PKCS 12 method, use an alias of "1" rather than "jetty", because that is the alias the PKCS12 process enters into the keystore.

Site powered by a free Open Source Project / Non-profit License (more) of Confluence - the Enterprise wiki.
Learn more or evaluate Confluence for your organisation.

Powered by Atlassian Confluence

DNS diable java

2006-09-27T09:31:00.000-07:00
http://www.rgagnon.com/javadetails/java-0445.html

ethernet duplex problem

2006-07-05T13:11:00.000-07:00
http://www.cisco.com/warp/public/473/46.html#auto_neg_valid

InterruptException

2006-07-04T11:21:00.000-07:00
Java theory and practice: Dealing with InterruptedException
You caught it, now what are you going to do with it?

Document options
Print this page

E-mail this page

Discuss

New site feature
dW radio -- Listen to our podcasts

Rate this page
Help us improve this content

Level: Introductory

Brian Goetz (brian@quiotix.com), Principal Consultant, Quiotix

23 May 2006

Many Java™ language methods, such as Thread.sleep() and Object.wait(), throw InterruptedException. You can't ignore it because it's a checked exception, but what should you do with it? In this month's Java theory and practice, concurrency expert Brian Goetz explains what InterruptedException means, why it is thrown, and what you should do when you catch one.
This story is probably familiar: You're writing a test program and you need to pause for some amount of time, so you call Thread.sleep(). But then the compiler or IDE balks that you haven't dealt with the checked InterruptedException. What is InterruptedException, and why do you have to deal with it?

The most common response to InterruptedException is to swallow it -- catch it and do nothing (or perhaps log it, which isn't any better) -- as we'll see later in Listing 4. Unfortunately, this approach throws away important information about the fact that an interrupt occurred, which could compromise the application's ability to cancel activities or shut down in a timely manner.

Blocking methods

When a method throws InterruptedException, it is telling you several things in addition to the fact that it can throw a particular checked exception. It is telling you that it is a blocking method and that it will make an attempt to unblock and return early -- if you ask nicely.

A blocking method is different from an ordinary method that just takes a long time to run. The completion of an ordinary method is dependent only on how much work you've asked it to do and whether adequate computing resources (CPU cycles and memory) are available. The completion of a blocking method, on the other hand, is also dependent on some external event, such as timer expiration, I/O completion, or the action of another thread (releasing a lock, setting a flag, or placing a task on a work queue). Ordinary methods complete as soon as their work can be done, but blocking methods are less predictable because they depend on external events. Blocking methods can compromise responsiveness because it can be hard to predict when they will complete.
Because blocking methods can potentially take forever if the event they are waiting for never occurs, it is often useful for blocking operations to be cancelable. (It is often useful for long-running non-blocking methods to be cancelable as well.) A cancelable operation is one that can be externally moved to completion in advance of when it would ordinarily complete on its own. The interruption mechanism provided by Thread and supported by Thread.sleep() and Object.wait() is a cancellation mechanism; it allows one thread to request that another thread stop what it is doing early. When a method throws InterruptedException, it is telling you that if the thread executing the method is interrupted, it will make an attempt to stop what it is doing and return early and indicate its early return by throwing InterruptedException. Well-behaved blocking library methods should be responsive to interruption and throw InterruptedException so they can be used within cancelable activities without compromising responsiveness.

Thread interruption

Every thread has a Boolean property associated with it that represents its interrupted status. The interrupted status is initially false; when a thread is interrupted by some other thread through a call to Thread.interrupt(), one of two things happens. If that thread is executing a low-level interruptible blocking method like Thread.sleep(), Thread.join(), or Object.wait(), it unblocks and throws InterruptedException. Otherwise, interrupt() merely sets the thread's interruption status. Code running in the interrupted thread can later poll the interrupted status to see if it has been requested to stop what it is doing; the interrupted status can be read with Thread.isInterrupted() and can be read and cleared in a single operation with the poorly named Thread.interrupted().

Interruption is a cooperative mechanism. When one thread interrupts another, the interrupted thread does not necessarily stop what it is doing immediately. Instead, interruption is a way of politely asking another thread to stop what it is doing if it wants to, at its convenience. Some methods, like Thread.sleep(), take this request seriously, but methods are not required to pay attention to interruption. Methods that do not block but that still may take a long time to execute can respect requests for interruption by polling the interrupted status and return early if interrupted. You are free to ignore an interruption request, but doing so may compromise responsiveness.

One of the benefits of the cooperative nature of interruption is that it provides more flexibility for safely constructing cancelable activities. We rarely want an activity to stop immediately; program data structures could be left in an inconsistent state if the activity were canceled mid-update. Interruption allows a cancelable activity to clean up any work in progress, restore invariants, notify other activities of the cancellation, and then terminate.

Back to top

Dealing with InterruptedException

If throwing InterruptedException means that a method is a blocking method, then calling a blocking method means that your method is a blocking method too, and you should have a strategy for dealing with InterruptedException. Often the easiest strategy is to throw InterruptedException yourself, as shown in the putTask() and getTask() methods in Listing 1. Doing so makes your method responsive to interruption as well and often requires nothing more than adding InterruptedException to your throws clause.

Listing 1. Propagating InterruptedException to callers by not catching it

public class TaskQueue {
private static final int MAX_TASKS = 1000;

private BlockingQueue queue
= new LinkedBlockingQueue(MAX_TASKS);

public void putTask(Task r) throws InterruptedException {
queue.put(r);
}

public Task getTask() throws InterruptedException {
return queue.take();
}
}

Sometimes it is necessary to do some amount of cleanup before propagating the exception. In this case, you can catch InterruptedException, perform the cleanup, and then rethrow the exception. Listing 2, a mechanism for matching players in an online game service, illustrates this technique. The matchPlayers() method waits for two players to arrive and then starts a new game. If it is interrupted after one player has arrived but before the second player arrives, it puts that player back on the queue before rethrowing the InterruptedException, so that the player's request to play is not lost.

Listing 2. Performing task-specific cleanup before rethrowing InterruptedException

public class PlayerMatcher {
private PlayerSource players;

public PlayerMatcher(PlayerSource players) {
this.players = players;
}

public void matchPlayers() throws InterruptedException {
try {
Player playerOne, playerTwo;
while (true) {
playerOne = playerTwo = null;
// Wait for two players to arrive and start a new game
playerOne = players.waitForPlayer(); // could throw IE
playerTwo = players.waitForPlayer(); // could throw IE
startNewGame(playerOne, playerTwo);
}
}
catch (InterruptedException e) {
// If we got one player and were interrupted, put that player back
if (playerOne != null)
players.addFirst(playerOne);
// Then propagate the exception
throw e;
}
}
}

Don't swallow interrupts

Sometimes throwing InterruptedException is not an option, such as when a task defined by Runnable calls an interruptible method. In this case, you can't rethrow InterruptedException, but you also do not want to do nothing. When a blocking method detects interruption and throws InterruptedException, it clears the interrupted status. If you catch InterruptedException but cannot rethrow it, you should preserve evidence that the interruption occurred so that code higher up on the call stack can learn of the interruption and respond to it if it wants to. This task is accomplished by calling interrupt() to "reinterrupt" the current thread, as shown in Listing 3. At the very least, whenever you catch InterruptedException and don't rethrow it, reinterrupt the current thread before returning.

Listing 3. Restoring the interrupted status after catching InterruptedException

public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException e) {
// Restore the interrupted status
Thread.currentThread().interrupt();
}
}
}

The worst thing you can do with InterruptedException is swallow it -- catch it and neither rethrow it nor reassert the thread's interrupted status. The standard approach to dealing with an exception you didn't plan for -- catch it and log it -- also counts as swallowing the interruption because code higher up on the call stack won't be able to find out about it. (Logging InterruptedException is also just silly because by the time a human reads the log, it is too late to do anything about it.) Listing 4 shows the all-too-common pattern of swallowing an interrupt:

Listing 4. Swallowing an interrupt -- don't do this

// Don't do this
public class TaskRunner implements Runnable {
private BlockingQueue queue;

public TaskRunner(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
while (true) {
Task task = queue.take(10, TimeUnit.SECONDS);
task.execute();
}
}
catch (InterruptedException swallowed) {
/* DON'T DO THIS - RESTORE THE INTERRUPTED STATUS INSTEAD */
}
}
}

If you cannot rethrow InterruptedException, whether or not you plan to act on the interrupt request, you still want to reinterrupt the current thread because a single interruption request may have multiple "recipients." The standard thread pool (ThreadPoolExecutor) worker thread implementation is responsive to interruption, so interrupting a task running in a thread pool may have the effect of both canceling the task and notifying the execution thread that the thread pool is shutting down. If the task were to swallow the interrupt request, the worker thread might not learn that an interrupt was requested, which could delay the application or service shutdown.

Back to top

Implementing cancelable tasks

Nothing in the language specification gives interruption any specific semantics, but in larger programs, it is difficult to maintain any semantics for interruption other than cancellation. Depending on the activity, a user could request cancellation through a GUI or through a network mechanism such as JMX or Web Services. It could also be requested by program logic. For example, a Web crawler might automatically shut itself down if it detects that the disk is full, or a parallel algorithm might start multiple threads to search different regions of the solution space and cancel them once one of them finds a solution.

Just because a task is cancelable does not mean it needs to respond to an interrupt request immediately. For tasks that execute code in a loop, it is common to check for interruption only once per loop iteration. Depending on how long the loop takes to execute, it could take some time before the task code notices the thread has been interrupted (either by polling the interrupted status with Thread.isInterrupted() or by calling a blocking method). If the task needs to be more responsive, it can poll the interrupted status more frequently. Blocking methods usually poll the interrupted status immediately on entry, throwing InterruptedException if it is set to improve responsiveness.

The one time it is acceptable to swallow an interrupt is when you know the thread is about to exit. This scenario only occurs when the class calling the interruptible method is part of a Thread, not a Runnable or general-purpose library code, as illustrated in Listing 5. It creates a thread that enumerates prime numbers until it is interrupted and allows the thread to exit upon interruption. The prime-seeking loop checks for interruption in two places: once by polling the isInterrupted() method in the header of the while loop and once when it calls the blocking BlockingQueue.put() method.

Listing 5. Interrupts can be swallowed if you know the thread is about to exit

public class PrimeProducer extends Thread {
private final BlockingQueue queue;

PrimeProducer(BlockingQueue queue) {
this.queue = queue;
}

public void run() {
try {
BigInteger p = BigInteger.ONE;
while (!Thread.currentThread().isInterrupted())
queue.put(p = p.nextProbablePrime());
} catch (InterruptedException consumed) {
/* Allow thread to exit */
}
}

public void cancel() { interrupt(); }
}

Noninterruptible blocking

Not all blocking methods throw InterruptedException. The input and output stream classes may block waiting for an I/O to complete, but they do not throw InterruptedException, and they do not return early if they are interrupted. However, in the case of socket I/O, if a thread closes the socket, blocking I/O operations on that socket in other threads will complete early with a SocketException. The nonblocking I/O classes in java.nio also do not support interruptible I/O, but blocking operations can similarly be canceled by closing the channel or requesting a wakeup on the Selector. Similarly, attempting to acquire an intrinsic lock (enter a synchronized block) cannot be interrupted, but ReentrantLock supports an interruptible acquisition mode.

Noncancelable tasks

Some tasks simply refuse to be interrupted, making them noncancelable. However, even noncancelable tasks should attempt to preserve the interrupted status in case code higher up on the call stack wants to act on the interruption after the noncancelable task completes. Listing 6 shows a method that waits on a blocking queue until an item is available, regardless of whether it is interrupted. To be a good citizen, it restores the interrupted status in a finally block after it is finished, so as not to deprive callers of the interruption request. (It can't restore the interrupted status earlier, as it would cause an infinite loop -- BlockingQueue.take() could poll the interrupted status immediately on entry and throws InterruptedException if it finds the interrupted status set.)

Listing 6. Noncancelable task that restores interrupted status before returning

public Task getNextTask(BlockingQueue queue) {
boolean interrupted = false;
try {
while (true) {
try {
return queue.take();
} catch (InterruptedException e) {
interrupted = true;
// fall through and retry
}
}
} finally {
if (interrupted)
Thread.currentThread().interrupt();
}
}

Back to top

Summary

You can use the cooperative interruption mechanism provided by the Java platform to construct flexible cancellation policies. Activities can decide if they are cancelable or not, how responsive they want to be to interruption, and they can defer interruption to perform task-specific cleanup if returning immediately would compromise application integrity. Even if you want to completely ignore interruption in your code, make sure to restore the interrupted status if you catch InterruptedException and do not rethrow it so that the code that calls it is not deprived of the knowledge that an interrupt occurred.

garbage collection trick

2006-07-02T22:15:00.000-07:00
http://www-128.ibm.com/developerworks/library/j-jtp01274.html

How expensive is allocation?

The 1.0 and 1.1 JDKs used a mark-sweep collector, which did compaction on some -- but not all -- collections, meaning that the heap might be fragmented after a garbage collection. Accordingly, memory allocation costs in the 1.0 and 1.1 JVMs were comparable to that in C or C++, where the allocator uses heuristics such as "first-first" or "best-fit" to manage the free heap space. Deallocation costs were also high, since the mark-sweep collector had to sweep the entire heap at every collection. No wonder we were advised to go easy on the allocator.

In HotSpot JVMs (Sun JDK 1.2 and later), things got a lot better -- the Sun JDKs moved to a generational collector. Because a copying collector is used for the young generation, the free space in the heap is always contiguous so that allocation of a new object from the heap can be done through a simple pointer addition, as shown in Listing 1. This makes object allocation in Java applications significantly cheaper than it is in C, a possibility that many developers at first have difficulty imagining. Similarly, because copying collectors do not visit dead objects, a heap with a large number of temporary objects, which is a common situation in Java applications, costs very little to collect; simply trace and copy the live objects to a survivor space and reclaim the entire heap in one fell swoop. No free lists, no block coalescing, no compacting -- just wipe the heap clean and start over. So both allocation and deallocation costs per object went way down in JDK 1.2.

Listing 1. Fast allocation in a contiguous heap

void *malloc(int n) {
synchronized (heapLock) {
if (heapTop - heapStart > n)
doGarbageCollection();

void *wasStart = heapStart;
heapStart += n;
return wasStart;
}
}

Performance advice often has a short shelf life; while it was once true that allocation was expensive, it is now no longer the case. In fact, it is downright cheap, and with a few very compute-intensive exceptions, performance considerations are generally no longer a good reason to avoid allocation. Sun estimates allocation costs at approximately ten machine instructions. That's pretty much free -- certainly no reason to complicate the structure of your program or incur additional maintenance risks for the sake of eliminating a few object creations.

Of course, allocation is only half the story -- most objects that are allocated are eventually garbage collected, which also has costs. But there's good news there, too. The vast majority of objects in most Java applications become garbage before the next collection. The cost of a minor garbage collection is proportional to the number of live objects in the young generation, not the number of objects allocated since the last collection. Because so few young generation objects survive to the next collection, the amortized cost of collection per allocation is fairly small (and can be made even smaller by simply increasing the heap size, subject to the availability of enough memory).

But wait, it gets better

The JIT compiler can perform additional optimizations that can reduce the cost of object allocation to zero. Consider the code in Listing 2, where the getPosition() method creates a temporary object to hold the coordinates of a point, and the calling method uses the Point object briefly and then discards it. The JIT will likely inline the call to getPosition() and, using a technique called escape analysis, can recognize that no reference to the Point object leaves the doSomething() method. Knowing this, the JIT can then allocate the object on the stack instead of the heap or, even better, optimize the allocation away completely and simply hoist the fields of the Point into registers. While the current Sun JVMs do not yet perform this optimization, future JVMs probably will. The fact that allocation can get even cheaper in the future, with no changes to your code, is just one more reason not to compromise the correctness or maintainability of your program for the sake of avoiding a few extra allocations.

Listing 2. Escape analysis can eliminate many temporary allocations entirely

void doSomething() {
Point p = someObject.getPosition();
System.out.println("Object is at (" + p.x, + ", " + p.y + ")");
}

...

Point getPosition() {
return new Point(myX, myY);
}

Isn't the allocator a scalability bottleneck?

Listing 1 shows that while allocation itself is fast, access to the heap structure must be synchronized across threads. So doesn't that make the allocator a scalability hazard? There are several clever tricks JVMs use to reduce this cost significantly. IBM JVMs use a technique called thread-local heaps, by which each thread requests a small block of memory (on the order of 1K) from the allocator, and small object allocations are satisfied out of that block. If the program requests a larger block than can be satisfied using the small thread-local heap, then the global allocator is used to either satisfy the request directly or to allocate a new thread-local heap. By this technique, a large percentage of allocations can be satisfied without contending for the shared heap lock. (Sun JVMs use a similar technique, instead using the term "Local Allocation Blocks.")

Back to top

Finalizers are not your friend

Objects with finalizers (those that have a non-trivial finalize() method) have significant overhead compared to objects without finalizers, and should be used sparingly. Finalizeable objects are both slower to allocate and slower to collect. At allocation time, the JVM must register any finalizeable objects with the garbage collector, and (at least in the HotSpot JVM implementation) finalizeable objects must follow a slower allocation path than most other objects. Similarly, finalizeable objects are slower to collect, too. It takes at least two garbage collection cycles (in the best case) before a finalizeable object can be reclaimed, and the garbage collector has to do extra work to invoke the finalizer. The result is more time spent allocating and collecting objects and more pressure on the garbage collector, because the memory used by unreachable finalizeable objects is retained longer. Combine that with the fact that finalizers are not guaranteed to run in any predictable timeframe, or even at all, and you can see that there are relatively few situations for which finalization is the right tool to use.

If you must use finalizers, there are a few guidelines you can follow that will help contain the damage. Limit the number of finalizeable objects, which will minimize the number of objects that have to incur the allocation and collection costs of finalization. Organize your classes so that finalizeable objects hold no other data, which will minimize the amount of memory tied up in finalizeable objects after they become unreachable, as there can be a long delay before they are actually reclaimed. In particular, beware when extending finalizeable classes from standard libraries.

Back to top

Helping the garbage collector . . . not

Because allocation and garbage collection at one time imposed significant performance costs on Java programs, many clever tricks were developed to reduce these costs, such as object pooling and nulling. Unfortunately, in many cases these techniques can do more harm than good to your program's performance.

Object pooling

Object pooling is a straightforward concept -- maintain a pool of frequently used objects and grab one from the pool instead of creating a new one whenever needed. The theory is that pooling spreads out the allocation costs over many more uses. When the object creation cost is high, such as with database connections or threads, or the pooled object represents a limited and costly resource, such as with database connections, this makes sense. However, the number of situations where these conditions apply is fairly small.

In addition, object pooling has some serious downsides. Because the object pool is generally shared across all threads, allocation from the object pool can be a synchronization bottleneck. Pooling also forces you to manage deallocation explicitly, which reintroduces the risks of dangling pointers. Also, the pool size must be properly tuned to get the desired performance result. If it is too small, it will not prevent allocation; and if it is too large, resources that could get reclaimed will instead sit idle in the pool. By tying up memory that could be reclaimed, the use of object pools places additional pressure on the garbage collector. Writing an effective pool implementation is not simple.

In his "Performance Myths Exposed" talk at JavaOne 2003 (see Resources), Dr. Cliff Click offered concrete benchmarking data showing that object pooling is a performance loss for all but the most heavyweight objects on modern JVMs. Add in the serialization of allocation and the dangling-pointer risks, and it's clear that pooling should be avoided in all but the most extreme cases.

Explicit nulling

Explicit nulling is simply the practice of setting reference objects to null when you are finished with them. The idea behind nulling is that it assists the garbage collector by making objects unreachable earlier. Or at least that's the theory.

There is one case where the use of explicit nulling is not only helpful, but virtually required, and that is where a reference to an object is scoped more broadly than it is used or considered valid by the program's specification. This includes cases such as using a static or instance field to store a reference to a temporary buffer, rather than a local variable (see Resources for a link to "Eye on performance: Referencing objects" for an example), or using an array to store references that may remain reachable by the runtime but not by the implied semantics of the program. Consider the class in Listing 3, which is an implementation of a simple bounded stack backed by an array. When pop() is called, without the explicit nulling in the example, the class could cause a memory leak (more properly called "unintentional object retention," or sometimes called "object loitering") because the reference stored in stack[top+1] is no longer reachable by the program, but still considered reachable by the garbage collector.

Listing 3. Avoiding object loitering in a stack implementation

public class SimpleBoundedStack {
private static final int MAXLEN = 100;
private Object stack[] = new Object[MAXLEN];
private int top = -1;

public void push(Object p) { stack [++top] = p;}

public Object pop() {
Object p = stack [top];
stack [top--] = null; // explicit null
return p;
}
}

In the September 1997 "Java Developer Connection Tech Tips" column (see Resources), Sun warned of this risk and explained how explicit nulling was needed in cases like the pop() example above. Unfortunately, programmers often take this advice too far, using explicit nulling in the hope of helping the garbage collector. But in most cases, it doesn't help the garbage collector at all, and in some cases, it can actually hurt your program's performance.

Consider the code in Listing 4, which combines several really bad ideas. The listing is a linked list implementation that uses a finalizer to walk the list and null out all the forward links. We've already discussed why finalizers are bad. This case is even worse because now the class is doing extra work, ostensibly to help the garbage collector, but that will not actually help -- and might even hurt. Walking the list takes CPU cycles and will have the effect of visiting all those dead objects and pulling them into the cache -- work that the garbage collector might be able to avoid entirely, because copying collectors do not visit dead objects at all. Nulling the references doesn't help a tracing garbage collector anyway; if the head of the list is unreachable, the rest of the list won't be traced anyway.

Listing 4. Combining finalizers and explicit nulling for a total performance disaster -- don't do this!

public class LinkedList {

private static class ListElement {
private ListElement nextElement;
private Object value;
}

private ListElement head;

...

public void finalize() {
try {
ListElement p = head;
while (p != null) {
p.value = null;
ListElement q = p.nextElement;
p.nextElement = null;
p = q;
}
head = null;
}
finally {
super.finalize();
}
}
}

Explicit nulling should be saved for cases where your program is subverting normal scoping rules for performance reasons, such as the stack example in Listing 3 (a more correct -- but poorly performing -- implementation would be to reallocate and copy the stack array each time it is changed).

Explicit garbage collection

A third category where developers often mistakenly think they are helping the garbage collector is the use of System.gc(), which triggers a garbage collection (actually, it merely suggests that this might be a good time for a garbage collection). Unfortunately, System.gc() triggers a full collection, which includes tracing all live objects in the heap and sweeping and compacting the old generation. This can be a lot of work. In general, it is better to let the system decide when it needs to collect the heap, and whether or not to do a full collection. Most of the time, a minor collection will do the job. Worse, calls to System.gc() are often deeply buried where developers may be unaware of their presence, and where they might get triggered far more often than necessary. If you are concerned that your application might have hidden calls to System.gc() buried in libraries, you can invoke the JVM with the -XX:+DisableExplicitGC option to prevent calls to System.gc() and triggering a garbage collection.

Immutability, again

No installment of Java theory and practice would be complete without some sort of plug for immutability. Making objects immutable eliminates entire classes of programming errors. One of the most common reasons given for not making a class immutable is the belief that doing so would compromise performance. While this is true sometimes, it is often not -- and sometimes the use of immutable objects has significant, and perhaps surprising, performance advantages.

Many objects function as containers for references to other objects. When the referenced object needs to change, we have two choices: update the reference (as we would in a mutable container class) or re-create the container to hold a new reference (as we would in an immutable container class). Listing 5 shows two ways to implement a simple holder class. Assuming the containing object is small, which is often the case (such as a Map.Entry element in a Map or a linked list element), allocating a new immutable object has some hidden performance advantages that come from the way generational garbage collectors work, having to do with the relative age of objects.

Listing 5. Mutable and immutable object holders

public class MutableHolder {
private Object value;
public Object getValue() { return value; }
public void setValue(Object o) { value = o; }
}

public class ImmutableHolder {
private final Object value;
public ImmutableHolder(Object o) { value = o; }
public Object getValue() { return value; }
}

In most cases, when a holder object is updated to reference a different object, the new referent is a young object. If we update a MutableHolder by calling setValue(), we have created a situation where an older object references a younger one. On the other hand, by creating a new ImmutableHolder object instead, a younger object is referencing an older one. The latter situation, where most objects point to older objects, is much more gentle on a generational garbage collector. If a MutableHolder that lives in the old generation is mutated, all the objects on the card that contain the MutableHolder must be scanned for old-to-young references at the next minor collection. The use of mutable references for long-lived container objects increases the work done to track old-to-young references at collection time. (See last month's article and this month's Resources, which explain the card-marking algorithm used to implement the write barrier in the generational collector used by current Sun JVMs).

Back to top

When good performance advice goes bad

A cover story in the July 2003 Java Developer's Journal illustrates how easy it is for good performance advice to become bad performance advice by simply failing to adequately identify the conditions under which the advice should be applied or the problem it was intended to solve. While the article contains some useful analysis, it will likely do more harm than good (and, unfortunately, far too much performance-oriented advice falls into this same trap).

The article opens with a set of requirements from a realtime environment, where unpredictable garbage collection pauses are unacceptable and there are strict operational requirements on how long a pause can be tolerated. The authors then recommend nulling references, object pooling, and scheduling explicit garbage collection to meet the performance goals. So far, so good -- they had a problem and they figured out what they had to do to solve it (although they appear to have failed to identify what the costs of these practices were or explore some less intrusive alternatives, such as concurrent collection). Unfortunately, the article's title ("Avoid Bothersome Garbage Collection Pauses") and presentation suggest that this advice would be useful for a wide range of applications -- perhaps all Java applications. This is terrible, dangerous performance advice!

For most applications, explicit nulling, object pooling, and explicit garbage collection will harm the throughput of your application, not improve it -- not to mention the intrusiveness of these techniques on your program design. In certain situations, it may be acceptable to trade throughput for predictability -- such as real-time or embedded applications. But for many Java applications, including most server-side applications, you probably would rather have the throughput.

The moral of the story is that performance advice is highly situational (and has a short shelf life). Performance advice is by definition reactive -- it is designed to address a particular problem that occurred in a particular set of circumstances. If the underlying circumstances change, or they are simply not applicable to your situation, the advice may not be applicable, either. Before you muck up your program's design to improve its performance, first make sure you have a performance problem and that following the advice will solve that problem.

Back to top

Summary

Garbage collection has come a long way in the last several years. Modern JVMs offer fast allocation and do their job fairly well on their own, with shorter garbage collection pauses than in previous JVMs. Tricks such as object pooling or explicit nulling, which were once considered sensible techniques for improving performance, are no longer necessary or helpful (and may even be harmful) as the cost of allocation and garbage collection has been reduced considerably.

Back to top

Resources

Participate in the discussion forum.

Read the complete Java theory and practice series by Brian Goetz.

The previous two installments of Java theory and practice, "A brief history of garbage collection" and "Garbage collection in the 1.4.1 JVM," cover some of the basics of garbage collection in Java virtual machines.

Garbage Collection: Algorithms for Automatic Dynamic Memory Management (John Wiley & Sons, 1997) is a comprehensive survey of garbage collection algorithms, with an extensive bibliography. The author, Richard Jones, maintains an updated bibliography of nearly 2000 papers on garbage collection on his Garbage Collection Page.

The Garbage Collection mailing list maintains a GC FAQ.

The IBM 1.4 SDK for the Java plaform uses a mark-sweep-compact collector, which supports incremental compaction to reduce pause times.

The three-part series, Sensible sanitation by Sam Borman (developerWorks, August 2002), describes the garbage collection strategy employed by the IBM 1.2 and 1.3 SDKs for the Java platform.

This article from the IBM Systems Journal describes some of the lessons learned building the IBM 1.1.x JDKs, including the details of mark-sweep and mark-sweep-compact garbage collection.

The example in Listing 3 was raised by Sun in a 1997 Tech Tip.

The paper "Removing GC Sychronisation" is a nice survey of potential scalability bottlenecks in garbage collection implementations.

In the paper "A fast write barrier for generational garbage collectors," Urs Hoeltze covers both the classical card-marking algorithm and an improvement that can reduce the cost of marking significantly by slightly increasing the cost of scanning dirty cards at collection time.

"Eye on performance: Referencing objects" (developerWorks, August 2003) by Jack Shirazi and Kirk Pepperdine offers some insight into improperly scoped variables and the need for explicit nulling.

Find hundreds more Java technology resources on the developerWorks Java technology zone.

Browse for books on these and other technical topics.

different java reference

2006-06-15T17:07:00.000-07:00
http://tutorials.beginners.co.uk/integrate_read/i/216/vs_p/p/p/3

Java: Performance Tuning and Memory Management Part 4 - Memory Utilization
Submitted By: Wrox Books
Published Date: 9th March 2001
Viewed: 19,664 times

Full computer related training courses are available in our membership area. To view over 400 Beginners.co.uk courses, click here. An annual training membership costs only £99 OR $149.

Although Java's performance problems have often been exaggerated, it is true that Java programs sometimes use a large amount of memory.

Garbage Collection and the finalize() Method

Before an object is destroyed by the garbage collector, the object's finalize() method is called to allow it to perform any necessary cleanup tasks. For example, if the object had used native methods to obtain resources (allocate memory, create network connections, etc.), it might be necessary to release those resources explicitly before the object is destroyed.

Just as you cannot be guaranteed that an object will ever be garbage collected, you cannot be certain that its finalize() method will be called. In Java 1.1, you could use the static runFinalizersOnExit() method in the java.lang.System class to force each object's finalize() method to be called prior to the termination of the JVM process. However, that method is deprecated in Java 2 because of problems that can occur when an object's finalize() method is invoked by one thread while another thread may be modifying the same object's state. In other words, runFinalizersOnExit() causes the finalize() method to be called for every object not previously finalized, even those that are still reachable.

To illustrate the fact that it's not possible to predict when or if the garbage collector will run, we can make some minor modifications to the GarbageTest class defined earlier. Specifically, we'll override finalize() in GarbageTest and TestClass so that they'll issue messages before instances are garbage collected:
public class GarbageTest {

protected Object objectRef;

public static void main(String[] args) {
GarbageTest gt = new GarbageTest();
System.out.println("Exiting main()");
}

public GarbageTest() {
objectRef = new TestClass(this);
}

protected void finalize() throws Throwable {
System.out.println("Finalizing GarbageTest");
}

class TestClass {

Object testref;

public TestClass(Object objref) {
testref = objref;
}

protected void finalize() throws Throwable {
System.out.println("Finalizing TestClass");
}

}

}

When this code is executed, neither finalize() method is called prior to termination of the JVM, so the only output produced is the message issued from the main() method as shown below:

Exiting main()

However, the main() method can be modified to force the execution of the objects' finalize() methods prior to exit by using the deprecated runFinalizersOnExit() method as shown below:

public static void main(String[] args) {
GarbageTest gt = new GarbageTest();
System.runFinalizersOnExit(true);
System.out.println("Exiting main()");
}

Executing this modified version of GarbageTest produces the following output, illustrating that the finalize() methods of both the GarbageTest and TestClass instances were called prior to termination of the JVM:

Exiting main()
Finalizing TestClass
Finalizing GarbageTest

Ensuring that the finalize() methods are called without using the deprecated runFinalizersOnExit() method is slightly more complex, and as we'll see, depends upon the garbage collector implementation. For example, we can attempt to make this occur by making the GarbageTest instance unreachable while still executing the main() and then calling System.gc() as shown below:

public static void main(String[] args) {
GarbageTest gt = new GarbageTest();
// System.runFinalizersOnExit(true);
gt = null;
System.gc();
System.out.println("Exiting main()");
}

Since the only reference to the GarbageTest instance is the local variable defined in the main() method, the following line makes that object unreachable:

gt = null;

Since the object is unreachable, the call to System.gc() should cause the garbage collector to reclaim both the GarbageTest object and the TestClass instance to which it maintains a reference, and this is what happens with the "HotSpot" JVM in JDK 1.3 on Win32. However, if you execute this code using release 1.2.2 of JavaSoft's JVM for Win32 platforms, the following output is produced:

Exiting main()

In other words, although both objects are unreachable, they are incorrectly ignored by the garbage collector, which occurs because the garbage collector in 1.2.2 is a partially accurate implementation. Its design makes it unable to identify some objects that are legitimate targets for collection, which can lead to memory leaks in your code. Interestingly enough, if you make the following minor change to the GarbageTest class and execute the modified version, the results will be different:

public static void main(String[] args) {
createAndRelease();
System.gc();
System.out.println("Exiting main()");
}

private static void createAndRelease() {
GarbageTest gt = new GarbageTest();
gt = null;
}

Running this version of the GarbageTest program causes the garbage collector to correctly reclaim both the GarbageTest object and the TestClass instance to which it maintains a reference. The output produced by running the code is shown below:

Finalizing GarbageTest
Finalizing TestClass
Exiting main()

Perhaps even more strangely, eliminating the second line (gt = null;) in the createAndRelease() method shown above causes the garbage collector to again fail to reclaim the two unreachable objects. These variations on the GarbageTest class and the different results that they produce illustrate the unreliability of partially accurate garbage collector algorithms. In a small application that runs for only a short length of time, such omissions may not be significant. However, for an application that is expected to continue running for a long time, the failure to reclaim unused heap space can become a serious problem and even cause the application to fail with an OutOfMemoryError.

Fortunately, the HotSpot technology included in the JDK 1.3 JVM includes a fully accurate garbage collector. It will correctly reclaim the GarbageTest and TestClass objects with any of the implementations of the GarbageTest code described above: with or without the createAndRelease() method, and with or without assigning a null value to the gt variable.

Reference Objects

Prior to Java 2, object instances were garbage collected only when there were no more references to them from live threads. However, Java 2 includes classes that allow you to maintain special types of references to objects, and those new reference types will not prevent objects from being garbage collected.

The classes are defined in the java.lang.ref package, and the Reference class is the superclass of the three new reference types: SoftReference, WeakReference, and PhantomReference. In addition to these classes, the ReferenceQueue class allows you to determine when references to an object have been cleared. References are normally cleared by the garbage collector when it prepares to reclaim an object, but you can explicitly clear a reference by calling the Reference object's clear() method.

The traditional type of object reference provided in earlier releases of Java is referred to as a strong reference, and object instances with strong references cannot be garbage collected. The new reference types provide what are known collectively as weak references, which is somewhat confusing since the WeakReference class represents only one of these types. To create a weak reference to an object, you simply create an instance of the appropriate class, passing its constructor a reference to the object as shown below:

// The myObject variable represents a strong reference
Object o = new Object();
// The softRef variable represents a soft reference
SoftReference softRef = new SoftReference(o);
// The weakRef variable represents a weak reference
WeakReference weakRef = new WeakReference(o);
// The phantomRef variable represents a phantom reference
// When creating a phantom reference, you must specify a reference
// queue (discussed later)
ReferenceQueue rq = new ReferenceQueue();
PhantomReference phantomRef = new PhantomReference(o, rg);

SoftReference and WeakReference instances can be used to create additional (possibly strong) references to the referenced object (also known as the referent) through the get() method. For example, the following code illustrates how a SoftReference is created, and is later used to create a strong reference to the referent:

byte[] buffer = new byte[10000];
SoftReference bufferRef = new SoftReference(buffer);
// Eliminate the strong reference
buffer = null;
// ...

// Create a new strong reference
byte[] bufferData = (byte[])(bufferRef.get());

Note, however, that the get() method will return a null value if the reference was reclaimed by the garbage collector after the weak reference was created. Therefore, when you do use get() to attempt to access the referent, you should ensure that it did not return a null before you use the return value.

An object is classified based on the strongest type of reference that exists to that object, and will be one of the following five values:

A strongly reachable object has strong references and may have soft, weak, or phantom references.
A softly reachable object has soft references and may have weak or phantom references, but does not have strong references.
A weakly reachable object has weak references and may have phantom references, but does not have strong or soft references.
A phantomly reachable object has only phantom references; it does not have strong, soft, or weak references.
An unreachable object is one for which there are no references of any kind.
In contrast, an object that is referenced through a chain of references is only as reachable as the weakest reference in the chain. For example, the following illustrates how a string of references can be created:

SoftReference sr = new SoftReference(new WeakReference(new Date()));

In this case, the Date instance is only weakly reachable, because it is referenced through a chain of two references, one of which is a WeakReference.

At this point, you may be wondering why there are three different types of weak references, and how their behavior differs. SoftReference and WeakReference are very similar in function and behavior, but there is one important difference. Garbage collector implementations are discouraged (but not prevented) from reclaiming softly reachable objects, especially those that have been created or accessed recently. In contrast, the garbage collector will reclaim a weakly reachable object just as if no references existed to it at all.

Phantom references are very different from the other two types, and are intended to be used specifically to allow you to determine when an object is about to be destroyed by the garbage collector. In fact, the get() method of a PhantomReference always returns null, even when the referent has not yet been garbage collected. After the referent's finalize() method has been called but before it is destroyed, any PhantomReference instances that refer to the referent are added to the appropriate ReferenceQueue.

Garbage collection of the referent will not be completed until the PhantomReference's clear() method is called, so it is the responsibility of your application to do so when using phantom references. Your code should wait for PhantomReference instances to be placed on the queue by the garbage collector, perform the appropriate cleanup for the referent, and then call the clear() method to allow the referent to be reclaimed.

The methods defined in ReferenceQueue simply allow you to retrieve Reference objects that have been placed on the queue. One implementation of the remove() method waits indefinitely until a Reference appears in the queue and returns that object. The other version of remove() allows you to specify the maximum number of milliseconds that it will wait for a Reference to be queued, and if none becomes available within that time, it returns a null value.

Finally, the poll() method always returns immediately, providing the caller with either a Reference that was queued or with a null value if none is available. In other words, the remove() method blocks the calling thread until an entry is available in queue or until the specified amount of time elapses, while poll() never blocks the caller.

How Reference Objects can be Used

Now that the behavior of the three Reference subclasses has been described, we'll briefly examine how each one can be used. Although many of the examples shown here use the java.lang.ref classes directly, you'll often find it more useful to subclass one of those when using weak references with your application. By creating a subclass, you can associate more information with the reference about how it is used and/or what action to take when you detect that its referent was cleared.

SoftReference

You can use SoftReference instances to cache information that should be discarded when your application begins to run low on memory. For example, if you're reading information from a database or files from a web browser, it may be useful to cache that data in memory as long as it does not cause your application to run out of memory. When the application needs to read information that was previously retrieved from the database or the network, it can first check the SoftReference-based cache. If the reference has not been cleared, the data can be quickly returned from the memory cache, but if it has been cleared, the data can again be retrieved from the database or network.

WeakReference

You'll sometimes wish to associate information with an object without preventing that object from being garbage collected, and you'll want the information to be destroyed when the object is reclaimed. If you were to use a "traditional" (strong) reference to associate the object with its information the object would never be garbage collected. For example, suppose that you use a Hashtable to maintain a relationship between objects and their information as shown below:

Hashtable ht = new Hashtable();
// ...
MyObject myObj = new MyObject();
ht.put(myObj, "This is the associated information");

The problem with this approach is that as long as a reference to the Hashtable exists and as long as it contains a strong reference to the MyObject instance, that object will never be reclaimed. However, by creating an association with a WeakReference, you can define a mapping that lasts only for the lifetime of the MyObject instance without affecting the garbage collector's ability to reclaim the object. In fact, that is exactly what the java.util.WeakHashMap class does, and an example of how it might be used is provided below:

WeakHashMap map = new WeakHashMap();
// ...
MyObject myObj = new MyObject();
map.put(myObj, "This is the associated information");

Each key in a WeakHashMap is an instance of a subclass of WeakReference, which allows the MyObject instance to be reclaimed by the garbage collector when there are no more strong references to it. Once that does occur, the WeakReference key entry in the map will remain, but its referent will be cleared and it will be placed on a ReferenceQueue. When an entry is added to or removed from the WeakHashMap, it checks the queue to see if any of its entries have been cleared and removes those that represent items that were garbage collected.

PhantomReference

As mentioned earlier, the purpose of the PhantomReference is to allow you to perform cleanup tasks for objects before they are destroyed by the garbage collector. Use of a ReferenceQueue with a SoftReference or WeakReference is optional, but each PhantomReference you construct must be associated with a ReferenceQueue as shown below:

MyObject myObj = new MyObject();
ReferenceQueue rq = new ReferenceQueue();
PhantomReference pr = new PhantomReference(myObj, rq);

You may wish to create a separate thread that waits for entries to be added to a ReferenceQueue, or you might design your code so that it periodically calls the poll() method. When a PhantomReference is retrieved from the queue, the appropriate cleanup should be performed for its reference and the clear() method called to allow the referent to be garbage collected.

Summary

In this chapter, we have looked at:

Using HPROF to examine the performance of a Java application, and to locate the source of a performance problem
Tips for improving the performance of your applications
The various types of Java compilers that are available, including Just-In-Time compilers and Sun's HotSpot technology
Memory management, including examination of garbage collection and reference objects

java profiler comparison

2006-05-20T11:37:00.000-07:00
http://www.javaworld.com/javaworld/jw-08-2003/jw-0822-profiler-p3.html

rmi without registry

2006-05-06T14:58:00.000-07:00
http://www.st.informatik.tu-darmstadt.de/static/staff/Haupt/rmi.html

Using Java RMI without rmiregistry
When I had to write a kind of small remote control for an application, I came across this. Normally, you have to start rmiregistry in order to let other machines access remote functionality. This was not applicable in my system, so I googled for some solution and finally came across something that worked out. Here is a step-by-step list of things to do.

Create an interface for the service.
Implement the service. Note that the implementation of the service is also the server application in this example.
Implement the client.
Compile and run.

The example consists of three small packages, namely simplermi containing the service interface, simplermi.server containing the server implementation, and simplermi.client containing the client.

If you have any objections or remarks, feel free to notify me.

--------------------------------------------------------------------------------
Create an Interface for the Service [Top]

The service used as an example is quite simple. It consists of a sole method named request() that returns a String.

package simplermi;

import java.rmi.Remote;
import java.rmi.RemoteException;

public interface SimpleServiceIfc extends Remote {
String request() throws RemoteException;
}

--------------------------------------------------------------------------------
Implement the Service [Top]

The service implementation is, in this example, also the server. To deploy the service, the application has to be started. All deployment action takes place in main().

package simplermi.server;

import java.rmi.AlreadyBoundException;
import java.rmi.Remote;
import java.rmi.RemoteException;
import java.rmi.registry.LocateRegistry;
import java.rmi.registry.Registry;
import java.rmi.server.UnicastRemoteObject;

import simplermi.SimpleServiceIfc;

public class SimpleService extends UnicastRemoteObject
implements SimpleServiceIfc {
public SimpleService(int port) throws RemoteException {
super(port);
}

public static void main(String[] args)
throws AlreadyBoundException, RemoteException {
// Create a RMI registry listening on port 4242.
Registry localRegistry = LocateRegistry.createRegistry(4242);
// Create an instance of the service listening on the same port.
SimpleServiceIfc service = new SimpleService(4242);
// Deploy the service.
localRegistry.bind("SimpleService", service);

// loop forever
while(true);
}

/**
* The service routine.
*/
public String request() throws RemoteException {
return "Hello, world!";
}
}

--------------------------------------------------------------------------------
Implement the Client [Top]

The client just performs a lookup in the registry via the registry port, retrieves a service reference and calls the service routine.

package simplermi.client;

import java.net.MalformedURLException;
import java.rmi.Naming;
import java.rmi.NotBoundException;
import java.rmi.RemoteException;

import simplermi.SimpleServiceIfc;

public class SimpleClient {
public static void main(String[] args)
throws MalformedURLException, NotBoundException, RemoteException {
SimpleServiceIfc remoteService =
(SimpleServiceIfc) Naming.lookup("//localhost:4242/SimpleService");
System.out.println("Service returns: " + remoteService.request());
}
}

--------------------------------------------------------------------------------
Compile and Run [Top]

Here are the steps that are necessary to actually execute the simple example. I assume the source files are stored in the appropriate directories (according to the package structure) and that the current working directory is the one containing the root of the package hierarchy, simplermi/.

Compile the sources:
$ javac simplermi/*.java
$ javac simplermi/server/*.java
$ javac simplermi/client/*.java
Generate RMI stubs:
$ rmic -v1.2 simplermi.server.SimpleService
Start the service (in background):
$ java simplermi.server.SimpleService &
Run the client:
$ java simplermi.client.SimpleC

java NIO

2006-04-25T16:40:00.000-07:00
http://www.oracle.com/technology/oramag/webcolumns/2003/techarticles/hunter_j2se1.html

intercept linux call LD_PRELOAD

2006-04-24T10:36:00.000-07:00
Linux Function Interception - LD_PRELOADLinux Function Interception - LD_PRELOAD. Author: Austin Godber - created with KPresenter.
uberhip.com/godber/interception/html/slide_5.html - 2k - Cached - Similar pages

linux firewall thesis

2006-04-20T17:22:00.000-07:00
http://www.ee.calpoly.edu/3comproject/masters-thesis/americoM.pdf

garbage collection

2006-04-11T23:26:00.001-07:00
http://www-128.ibm.com/developerworks/java/library/j-jtp10283/

http://www-128.ibm.com/developerworks/java/library/j-jtp11253/

correlation

2006-04-11T23:26:00.000-07:00
http://www-128.ibm.com/developerworks/library/ac-acact/?ca=drs-t4605

C++ tutorial

2006-04-09T21:49:00.000-07:00
http://cplus.about.com/od/beginnerctutorial/l/aa072302f.htm

javascript closure

2006-04-03T23:10:00.000-07:00
http://jibbering.com/faq/faq_notes/closures.html

IE javascript memory leak

2006-04-03T18:29:00.000-07:00
http://www.outofhanwell.com/ieleak/

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/IETechCol/dnwebgen/ie_leak_patterns.asp

digital video

2006-03-28T09:38:00.000-08:00
http://www.idi.ntnu.no/grupper/su/publ/phd/sandstaa-thesis.pdf

linux kernel tutorial

2006-03-18T15:14:00.000-08:00
http://bravo.ce.uniroma2.it/kernelhacking2006/lkh06_3_s.pdf

ssl implementation

2006-03-02T13:49:00.000-08:00
http://piglet.uccs.edu/~gsc/pub/master/gkgodava/doc/

reverse engineering java from java to UML

2006-02-26T22:15:00.000-08:00
C:\public\essmodel
essmodel.sourceforge.net
http://forum.java.sun.com/thread.jspa?threadID=443226&messageID=2005619

wiki open source

2006-02-26T21:34:00.000-08:00
http://www.onlamp.com/pub/a/onlamp/2004/11/04/which_wiki.html

WSDM

2006-02-24T16:14:00.000-08:00
http://www.globusworld.org/2005Slides/Session%206b(1).pdf

inner class

2006-02-23T16:23:00.000-08:00
http://www.javaworld.com/javaworld/javaqa/2001-08/01-qa-0817-static.html

this Q&A I'll cover two popular and related questions: "What is the difference between an inner member class and an inner static member class?" And: "Why would I choose one over the other?"

Superficially, static and nonstatic inner member classes differ in how you declare them. A static member class will have the static keyword in its definition, while a member class will not:

public class InnerClassSyntax {

// A static member class
public static class StaticMember {
// ... code
}

// A member class
public class Member {
// ... code
}
}

More importantly, the static keyword limits what instances of the static member classes can do to instances of the class within which they are defined. To wit, when you declare a member class as static, instances of that inner class will have access only to the static methods and static members of the enclosing instance.

In contrast, plain old member classes can access any method or member of the enclosing class since member classes have access to the enclosing instance's this. (A static member class is limited to accessing only static attributes because it lacks access to the enclosing instance's this.)

Let's expand the original example to see these limitations in action:

public class InnerClassSyntax {

private static int _aStaticInstanceVariable;
private int _anInstanceVariable;

public void anInstanceMethod() {
// ... do something
}

public static void aStaticMethod() {
// ... do something
}

// A static member class
public static class StaticMember {
public void aMethod() {
// Legal calls
int staticValue = InnerClassSyntax._aStaticInstanceVariable;
InnerClassSyntax.aStaticMethod();

// Illegal calls -- will not compile if uncommented
// int value = _anInstanceVariable;
// anInstanceMethod();
// InnerClassSyntax.anInstanceMethod();
}
}

// A member class
public class Member {
public void aMethod() {
// Legal calls
int staticValue = _aStaticInstanceVariable;
int value = _anInstanceVariable;
aStaticMethod();
anInstanceMethod();
}
}

}

You see that the static member class can access only those attributes declared as static. Static member classes do not have access to the this reference -- in this case InnerClassSyntax.this. However, Member instances do have access to InnerClassSyntax.this, so they can access everything in the enclosing InnerClassSyntax instance.

The following code selection rewrites the Member class so that it explicitly uses the InnerClassSyntax.this reference (which normally happens by default):

public class Member {
public void aMethod() {
staticValue = InnerClassSyntax._aStaticInstanceVariable;
value = InnerClassSyntax.this._anInstanceVariable;
InnerClassSyntax.aStaticMethod();
InnerClassSyntax.this.anInstanceMethod();
}

Now, with all the syntactical goodies aside, why would you choose a static member class over a plain-old member class? Well, when designing an inner class, you need to ask what do that inner class's instances need? Ask yourself whether the instances depend on instance-specific information? If yes, you need a member class.

However, nonstatic member classes must maintain a reference to the enclosing instance. Maintenance of this reference consumes both memory and CPU time. Therefore, if your member class does not depend upon the enclosing class's instance data, you can, and should, declare it static.

Let's look at a static member class example:

public final class Text {

// List of valid justification constants
public static final Justification LEFT =
new Justification( "Left" );

public static final Justification RIGHT =
new Justification( "Right" );

public static final Justification CENTER =
new Justification( "Center" );

// Holder for this instance's justification
private Justification _justification;

public void setJustification( Justification justification ) {
_justification = justification;
}

// Other Text code omitted
// . . .

public static class Justification {

private String _label;

public Justification( String label ) {
_label = label;
}

public String toString() {
return _label;
}

}

}

In the code above, instances of Text might represent selections of text inside an editor. The text can have a justification. I declared the Justification member class as static since the Justification instances do not rely on instance-level information in the enclosing Text class. Instead, instances of Justification act as constants that work with any instance of Text. That's why we can get away with declaring Justification static; it is independent of any specific Text instances.

Now, let's look at a member class example:

public final class Text {

private String _text;
private Search _search = new Search();

public boolean contains( String text ) {
return _search.contains( text );
}

private class Search {
public boolean contains( String text ) {
// Do something to Text._text;
// Hardcode return so that this class can compile
return false;
}
// ... other methods
}

// Original justification code removed for brevity

}

In this example, Text implements its searching code as a member class. (Such an approach nicely partitions the code, rather than embedding the search code within the Text class itself.) In order to search, the Search object needs access to Text.this._text, thus the Search must not be declared static.

idiom

2006-02-21T22:43:00.000-08:00
http://www.wayabroad.com/pack/pack02/1846_1_1.html

certificate management

2006-02-21T18:42:00.000-08:00
http://www.bo.infn.it/alice/introgrd/certmgr/certmgr.html
http://forum.java.sun.com/thread.jspa?forumID=2&messageID=449486&threadID=154587

How to export private key from keystore?
Author: zendragon Posts: 4 Registered: 12/5/97
Jul 31, 2001 7:24 AM

I have the same problem as following

Hi
Does anybody know, how to export a private key from a keystore in a PEM-Encoded format, i.e. that is what openSSL for Apache is looking for.

What I got until now from the Keystore (and that's very easy) is an instance of the Key-class of the Private Key. From that Key instance I can call the encoded()-method to get a PKCS8-encoded byte-array. Now, what I want to is a PEM-Encoded String.

Any help greatly apreciated!

Re: How to export private key from keystore?
Author: thaisontn Posts: 1 Registered: 8/27/99
Sep 13, 2002 6:24 PM (reply 1 of 16)

I have the exact same issue. I have a certificate for a site that is incorporated in a Java keystore because the webserver is in Java. Now I want to migrate the site to a new setup (Apache/Tomcat) so I want to export the private key so that Apache/OpenSSL can use it. I've tried privKey.getEncoded()(which I assume is equivalent to OpenSSL's DER format) as well as Base64.encode(privKey.getEncoded()) (which I assume is equivalent to OpenSSL's PEM format). Neither of these approaches work. Am I missing something or is there a bug in the PKCS8EncodedKeySpec code or the OpenSSL code ? If anyone has any thoughts on this, I'd like to hear about it. Thanx !

Re: How to export private key from keystore?
Author: jheiss Posts: 3 Registered: 12/18/97
Sep 30, 2002 9:37 AM (reply 2 of 16)

You're on the right track. After Base64.encode(privKey.getEncoded()) you need
to wrap the lines at 64 characters and add the header and footer lines (these are documented in OpenSSL's pkcs8 man page).

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

Re: How to export private key from keystore?
Author: emoy2000 Posts: 1 Registered: 6/8/01
Dec 30, 2002 11:25 PM (reply 3 of 16)

Hi, I have the same problem as what you mentioned here (which I don't know how to export private key from keystore), could you share your solution with me here?
Thanks a lot
Mana

Re: How to export private key from keystore?
Author: amorrow5 Posts: 320 Registered: 8/27/01
Jan 8, 2003 2:00 AM (reply 4 of 16)

Here is a full code example

// How to export the private key from keystore?
// Does keytool not have an option to do so?
// This example use the "testkeys" file that comes with JSSE 1.0.3

import sun.misc.BASE64Encoder;
import java.security.cert.Certificate;
import java.security.*;
import java.io.File;
import java.io.FileInputStream;

class ExportPriv {
public static void main(String args[]) throws Exception{
ExportPriv myep = new ExportPriv();
myep.doit();
}

public void doit() throws Exception{

KeyStore ks = KeyStore.getInstance("JKS");
String fileName = "testkeys";

char[] passPhrase = "passphrase".toCharArray();
BASE64Encoder myB64 = new BASE64Encoder();

File certificateFile = new File(fileName);
ks.load(new FileInputStream(certificateFile), passPhrase);

KeyPair kp = getPrivateKey(ks, "duke", passPhrase);

PrivateKey privKey = kp.getPrivate();

String b64 = myB64.encode(privKey.getEncoded());

System.out.println("-----BEGIN PRIVATE KEY-----");
System.out.println(b64);
System.out.println("-----END PRIVATE KEY-----");

}

// From http://javaalmanac.com/egs/java.security/GetKeyFromKs.html

public KeyPair getPrivateKey(KeyStore keystore, String alias, char[] password) {
try {
// Get private key
Key key = keystore.getKey(alias, password);
if (key instanceof PrivateKey) {
// Get certificate of public key
Certificate cert = keystore.getCertificate(alias);

// Get public key
PublicKey publicKey = cert.getPublicKey();

// Return a key pair
return new KeyPair(publicKey, (PrivateKey)key);
}
} catch (UnrecoverableKeyException e) {
} catch (NoSuchAlgorithmException e) {
} catch (KeyStoreException e) {
}
return null;
}

}

Re: How to export private key from keystore?
Author: pchinns Posts: 1 Registered: 10/8/00
Mar 11, 2003 11:34 AM (reply 5 of 16)

Hi,

I have a problem related to keystore and certificates. Can you please throw some light on this.

JSSE expects two keystores one for loading the private keys and the other for loading public keys.

I created a certificate request using java keytool and obtained a trial certificate from a trusted CA. I imported the CA's trial root and trial certificate into the keystore which was intially used to generate certificate request. I believe this can now be used as the keystore that contains the private key. Now how do i get the keystore which contains the public keys.

Any help in this regard will be appreaciated

Thanks,
pradeep

Re: How to export private key from keystore?
Author: lpz Posts: 2 Registered: 9/25/98
Mar 18, 2003 5:59 PM (reply 6 of 16)

I have the opposite problem. How do you read in an encrypted private key from a PEM file? I can read in the public key certificate and get the public key, like this:

FileInputStream is = new FileInputStream(file);
CertificateFactory cf = CertificateFactory.getInstance("X.509");
java.security.cert.Certificate cert = cf.generateCertificate(is);

However, I cannot read in the private key and generate the private key:

FileInputStream in = new FileInputStream(file);
fileLength = (int) in.available();
byte[] base64Bytes = new byte[fileLength];
int inLength = in.read(base64Bytes, 0, fileLength);
String inputString = new String(base64Bytes);

// Here I tried all of the PEM file (including the ASCII armor) and just the base64 // characters. I get the same error either way
String keyString = new String(base64KeyBytes);
byte[]encryptedKeyBytes4 = Base64.decode(keyString);
EncryptedPrivateKeyInfo encryptedKeyInfo =
new EncryptedPrivateKeyInfo(encryptedKeyBytes);
// This always throws IOException

I have the same problem whether I use the java keystore or openssl to generate the key material.

Re: How to export private key from keystore?
Author: klmreddy Posts: 1 Registered: 11/21/02
Mar 22, 2003 6:25 AM (reply 7 of 16)

Hi ,

this code is working fine , but it is not maintaining 64 char for each line.
even if i made it 64 chars for line.this keyfile is not recognized by openssl.

the following converts pem cert to pkcs12 certificate ,we need to specify the private
key.

openssl pkcs12 -export -out file_name.p12 -inkey userkey.pem -in usercert.pem

I got the following error.

Error loading private key
15114:error:0D080071:asn1 encoding routines:d2i_ASN1_INTEGER:expecting an integer:a_int.c:204:
15114:error:0D09D082:asn1 encoding routines:d2i_RSAPrivateKey:parsing:d2i_r_pr.c:117:
15114:error:0D09B00D:asn1 encoding routines:d2i_PrivateKey:ASN1 lib:d2i_pr.c:89:
15114:error:0906700D:PEM routines:PEM_ASN1_read_bio:ASN1 lib:pem_lib.c:291:

this means private key is not in correct format.can somebody help me.

Thanks in advance,
klm.

Re: How to export private key from keystore?
Author: amorrow5 Posts: 320 Registered: 8/27/01
Jul 11, 2003 5:08 AM (reply 8 of 16)

It might be best to just try to dump out the the cert, rather than run your web server.

To review, on the cert (and public key):

keytool -export -rfc -keystore keyfile -alias duke > duke.cert.pem

openssl x509 -noout -text -in duke.cert.pem

but for the private key, you run the program and send the output to a file, say duke.key.pem and then you can:

openssl rsa -noout -text -in duke.key.pem

Note that the starting delimiter line is simply

"-----BEGIN PRIVATE KEY-----"

but if you have a password-protected (encrypted) private key, the line will be more like:

-----BEGIN RSA PRIVATE KEY-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,4ECDE43CCBDA9934

I think Java, using JCE's DES, can decrypt such a file, but I have not tried to make an implementation of such.

In thinking about it, I can understand who keytool does not provide the functionality my program does: the unencrypted private key becomes less secure when it is no longer protected by the keystore password.

Re: How to export private key from keystore?
Author: alef-sun Posts: 1 Registered: 6/6/03
Oct 9, 2003 8:42 AM (reply 9 of 16)

Hi, I have used succesfully this code and the script:

import java.io.FileInputStream;
import java.security.KeyStore;
import java.security.Key;

public class DumpPrivateKey {
static public void main(String[] args) {
try {
KeyStore ks = KeyStore.getInstance("jks");
ks.load(new FileInputStream("keystore"),
"password".toCharArray());
Key key = ks.getKey("youralias",
"password".toCharArray());
System.out.write(key.getEncoded());
} catch (Exception e) {
e.printStackTrace();
}
}
}

#!/bin/sh
ALIAS=youralias
PKEY_8=privatekey.pkcs8
PKEY_64=privatekey.b64
CERT_64=certificate.b64
CERT_12=certificate.p12
keytool -alias ${ALIAS} -export -rfc >${CERT_64}
java DumpPrivateKey >${PKEY_8}
(echo "-----BEGIN PRIVATE KEY-----" ;
openssl enc -in ${PKEY_8} -a;
echo "-----END PRIVATE KEY-----") >${PKEY_64}
openssl pkcs12 -inkey ${PKEY_64} -in ${CERT_64} -out ${CERT_12} -export
rm ${PKEY_8} ${PKEY_64} ${CERT_64}
echo ${CERT_12}

Hope could be useful. Regards.

Re: How to export private key from keystore?
Author: evilb69 Posts: 182 Registered: 4/8/03
Oct 13, 2003 1:26 AM (reply 10 of 16)

LPZ... in answer to reading IN a private key into the keystore, see my answer here:-

http://forum.java.sun.com/thread.jsp?forum=2&thread=161578&tstart=15&trange=15

Re: How to export private key from keystore?
Author: dwc_ Posts: 1 Registered: 2/27/04
Feb 27, 2004 10:52 AM (reply 11 of 16)

Thanks for the posts. They were just what I was looking for.

Re: How to export private key from keystore?
Author: svangasse Posts: 10 Registered: 3/21/03
May 27, 2004 2:03 PM (reply 12 of 16)

I'm very interested to see if anyone has managed to decrypt the (password protected) exported private key from a keystore.

I took amorrow5's advice and looked into using the JCE with DES but if, as I did, you created your key pair using keytool you won't know what parameters to use when initialising the Cipher object which is used to decrypt the private key.

I need the private key unencrypted to use with UW IMAP Mail Server.

If anyone has any pointers they would be very much appreciated.

Re: How to export private key from keystore?
Author: rdare Posts: 24 Registered: 9/2/99
Aug 10, 2004 1:56 PM (reply 13 of 16)

Using the cog-jglobus.jar and the BouncyCastle keyProvider classes,
one can load a password protected PrivateKey .pem file as such:

PrivateKey caPrivKey = null;
String fileName = null; // .pem file path
String caPassword = "some.password";
try {
// Now Generate the Cerificate
// OpenSSLKey key = new BouncyCastleOpenSSLKey(fileName);
OpenSSLKey key = new BouncyCastleOpenSSLKey(fileName);
// decrypt ca priv key
if (key.isEncrypted()) {
try {
if (caPassword == null) {
throw new GeneralSecurityException(
"A CA password is required");
}
key.decrypt(caPassword);
} catch (GeneralSecurityException e) {
System.out.println("Wrong CA password or other security error: "
+ e.getMessage());
e.printStackTrace();
}
}

caPrivKey = key.getPrivateKey();

Re: How to export private key from keystore?
Author: TJworld Posts: 1 Registered: 1/4/05
Jan 4, 2005 2:56 PM (reply 14 of 16)

Spurred on by the disparate articles and the code+script from alef-sun, I decided to put some tools together to make the job much easier, and to write a comprehensive illustrated guide to go with it, for Windows-based developers.

Here's how to get and use a FREE trusted Thawte digital certificate to sign your Java JAR and Microsoft CAB code archives, to create trusted applets for downloading over the Internet, and to convert the Java JKS key-store to Microsoft PFX Personal Information Exchange format to share the same certificate with Java JAR files and Microsoft CAB files.

Visit my guide "Trusted Code-Signing

heartbeat

2006-02-19T18:23:00.000-08:00
http://www-128.ibm.com/developerworks/linux/library/l-halinux/?ca=drs-

ssh no password

2006-02-17T11:47:00.000-08:00
http://www.emsei.psu.edu/ecf/alt/general/ssh.html

Example
Let's say you want to run a remote command on the machine "beta" from the machine "alpha" without supplying a password. Instead of authenticating using a password, you can use the command ssh-keygen to create a pair of public and private keys that can be used for authentication.

The first step is to create a set of public and private keys that uniquely identify your userid on "alpha". Log into alpha and run the command:
alpha% ssh-keygen -t rsa -N ''

(This command can take a long time to run on some machines). When it asks you what file you would like to save your key as, you can just press return, to accept the default location. This will create two files on alpha:

alpha% ls -l /home/woods/.ssh/id*
-rw------- 1 woods woods 530 Feb 8 18:13 /home/woods/.ssh/id_rsa
-rw-rw-r-- 1 woods woods 334 Feb 8 18:13 /home/woods/.ssh/id_rsa.pub
The id_rsa file contains the private key (note that it is not world or group readable) that represents your identity on that particular machine. The private key should never be transferred from the machine or have its modes changed. The id_rsa.pub file is the public key, which is world-readable. ssh and other programs can use this key to encrypt messages that only you can decrypt using the private key.
The -N '' argument to ssh-keygen specifies that there should be no password associated with these keys. Keys can have passwords just like accounts, but that would defeat the purpose here.

The next step is give alpha's public key to beta, and tell beta that alpha is authorized to run remote commands using RSA authentication.
You do this by copying the contents of alpha's id_rsa.pub (not id_rsa!) to a file called authorized_keys2 in your .ssh directory on beta:

beta% cd ~/.ssh
beta% ssh alpha 'cat .ssh/id_rsa.pub' >> authorized_keys2
alpha's public key is now in the authorized_keys2 file on beta, telling beta that alpha is authorized to use RSA authentication to log in.
By the way, it's fine to have more than one key in the authorized_keys2 file, in case you need more than one host to be able to do RSA authentication to beta.

The last step is to make sure the authorized_keys2 file on beta has modes 600. This ensures that no one else can view this file.
beta% chmod 600 authorized_keys2
beta% ls -l authorized_keys
-rw------- 1 woods woods 662 Feb 8 18:04 .ssh/authorized_keys2
The first command removes all of the bits for "group" and "world" permissions, making

dynamic html javascript

2006-01-30T13:45:00.000-08:00
http://catcode.com/domcontent/display/menus.html

stty erase

2006-01-24T23:12:00.000-08:00
bind '"\M-[3~":backward-delete-char'

ajax toolkit

2006-01-23T22:04:00.000-08:00
http://getahead.ltd.uk/dwr

http://dojotoolkit.org/

http://glm-ajax.sourceforge.net/

Runtime.exec

2006-01-14T00:14:00.000-08:00
http://www-128.ibm.com/developerworks/library/j-tiger09304.html?ca=dnt-540
Taming Tiger: Get environment variables and invoke subprocesses
When deprecated doesn't mean forever

Document options
Print this page

E-mail this page

Discuss

Sample code

Rate this page
Help us improve this content

Level: Introductory

John Zukowski (jaz@zukowski.net), President, JZ Ventures, Inc.

30 Sep 2004

Accessing platform-specific information hasn't always been easy. While you could certainly create processes with Runtime.exec(), dealing with differences across platforms to build parameter sets often led to headaches. In addition, the getenv() method of System has been deprecated since the beginning of Java programming time. Now, as columnist John Zukowski shows you, the new ProcessBuilder class makes accessing platform-specific information easier than ever. Share your thoughts on this article with the author and other readers in the accompanying discussion forum. (You can also click Discuss at the top or bottom of the article to access the forum.)
When is a deprecated method not deprecated? When you're using the getenv() method of System. Working in the pre-release versions of the original Java platform back in 1995, Tiger undeprecates the method, along with offering a new class called ProcessBuilder (in the java.lang package) for creating and interacting with system processes.

Getting environment variables

While I personally don't want to go back to the original event model for working with AWT components, one nice feature of the early access version of the Java platform (also known as the alpha releases) was the ability to access environment variables. This approach went against the "Write Once, Run Anywhere" mantra of the time, and the getenv() method of System was deprecated with the 1.0 release of the Java platform. Why something came out deprecated in a 1.0 release always confused me, but seeing the method there always seemed to spark interest in using it with new developers. Fast forward to 2004 and now you finally can. As Listing 1 shows, usage of the method is easy:

Listing 1. Calling getenv

public class EnvTest {
public static void main(String args[]) {
System.out.println(System.getenv(args[0]));
}
}

Simply provide the name on the command line, pass it along to the getenv call, and you'll get its current value. For instance, calling with a PROCESSOR_IDENTIFIER argument produces the results in Listing 2 for my two-year-old desktop system:

Listing 2. getenv sample output

java EnvTest PROCESSOR_IDENTIFIER
x86 Family 6 Model 8 Stepping 6, GenuineIntel

The first thing you should notice is that the method name, getenv(), is all lowercase, not mixed case as you might expect (getEnv()). The reason is because that's the way it was originally named back in pre-release days. Second, accessing environment variables tends to result in platform-specific code. That's all right if it is what you truly want, but it strays from the 100 percent Pure Java model. The code itself is still 100 percent pure, so using the method doesn't totally go against the principle, but after using system properties for so many years, having getenv() around just feels wrong.

Tiger offers two versions of the getenv() method, not just one. The second version returns a name-value pair mapping of all the environment variables currently set in the system. Listing 3 demonstrates the usage of this new method by printing out the key and value of all environment variables:

Listing 3. Getting all environment variables

import java.util.Map;

public class EnvDump {
public static void main(String args[]) {
for (Map.Entry entry: System.getenv().entrySet()) {
System.out.println(entry.getKey() + " / " +
entry.getValue());
}
}
}

Back to top

Understanding ProcessBuilder

This leads us to the new class, java.lang.ProcessBuilder. Earlier versions of the platform allowed you to create native processes through the exec() method of the Runtime class. This approach still works, but with just String arrays as arguments, and a File argument for a working directory, the manner of customizing the sub-process wasn't always that easy. The use of ProcessBuilder simplifies things by adding methods like directory(File) to change the working directory for the process and environment() for adding and removing environment variables from the process space. Listing 4 shows a simple usage of ProcessBuilder to get your Internet configuration with the ipconfig command. This approach should work on most platforms. If it doesn't, change ipconfig to a working command for your platform. After starting the process builder, you need to get its InputStream to read the results of the created process.

Listing 4. Using ProcessBuilder

import java.io.*;

public class ProcessTest {
public static void main(String args[]) throws IOException {
Process p = new ProcessBuilder("ipconfig").start();
InputStream is = p.getInputStream();
BufferedReader br = new BufferedReader(new InputStreamReader(is));
String line;
while ((line = br.readLine()) != null) {
System.out.println(line);
}
}
}

As Listing 5 shows, running this program produces output similar to running ipconfig from the command line (your results will most likely vary):

Listing 5. ProcessBuilder example output

Windows 2000 IP Configuration

Ethernet adapter Local Area Connection:

Connection-specific DNS Suffix . :
IP Address. . . . . . . . . . . . : 192.168.0.101
Subnet Mask . . . . . . . . . . . : 255.255.255.0
Default Gateway . . . . . . . . . : 192.168.0.1

As I already mentioned, the ProcessBuilder class is a bit more than just forking off a process and getting the results. Prior to calling its start() method, you can adjust the context for the process to execute in. Don't like the environment variables? Just get the current set with environment and clear() out the map. Need to add an environment variable? Call environment to get the current set, then put(name, value) in a new variable. Don't like the working directory? Call directory() with a new working directory as a File object. It really is that simple. Create the ProcessBuilder with a variable number of string arguments representing the command to run and that command's arguments. Once the ProcessBuilder is configured with new environment variables and a working directory, just call start() for the command to run.

Back to top

Ask and ye shall receive...maybe

Are you concerned that your favorite method got deprecated and you want it back? Well, sometimes a deprecated method that was never really supported in a released Java version can come back to life. With enough user demand and votes in Sun's Bug Parade, developers can make a difference and direct how the Java platform evolves. While I doubt the old AWT event model will ever come back to life -- even if everyone demanded it -- something as simple as getting an environment variable is finally supported by the Java platform. Use it with care. Apart from the deprecated getenv issue, ProcessBuilder adds a simpler manner of creating native processes and should be used to replace any old Runtime.exec() calls. Refactor away!

Back to top

Download

Name Size Download method
j-tiger09304-source.zip FTP

Information about download methods

javascript OOP

2006-01-07T16:35:00.000-08:00
http://www.javascriptkit.com/javatutors/oopjs.shtml

JavaScript and Object Oriented Programming (OOP)
Credits: This tutorial is written and contributed by Tim Scarfe. Edited by JavaScriptKit.com for content/ structure. Please see footnote for more information on author.

JavaScript is an excellent language to write object oriented web applications. It can support OOP because it supports inheritance through prototyping as well as properties and methods. Many developers cast off JS as a suitable OOP language because they are so used to the class style of C# and Java. Many people don't realize that JavaScript supports inheritance. When you write object-oriented code it instantly gives you power; you can write code that can be re-used and that is encapsulated.

What's so great about objects?
Objects work so well because they act just like real life objects- objects have properties and methods. So if we were talking about a lamp, a property of it may be its height or width, say 12cm. A method of it may be to shine (an action). And when it's shining, its brightness property would be of a greater value than when it wasn't.

JavaScript gives you the ability to make your own objects for your own applications. With your objects you can code in events that fire when you want them to, and the code is encapsulated. It can be initialized any amount of times.

Creating objects using new Object()
There are several ways to create objects in JavaScript, and all of them have their place. The simplest way is to use the new operator, specifically, new Object():

<
person = new Object()
person.name = "Tim Scarfe"
person.height = "6Ft"

person.run = function() {
this.state = "running"
this.speed = "4ms^-1"
}

//-->
We define a custom object "person," then add to it its own properties and method afterwards. In this case, the custom method merely initializes two more properties.

Creating objects using Literal Notation
Another inline way of defining an object is via literal notation. Supported in JavaScript1.2 and above, it's a more robust form of creating an object on the fly:

Literal notion can contain arrays or arbitrary JavaScript expressions or values.

While using the new operator or literal notion to create a custom object is both simple and logical, the biggest shortcoming is that the result is NOT reusable- we cannot easily initialize different versions of the created object. For example with the first demonstration above, if the person's name is not "Tim Scarfe", we would need to redefine our entire object just to accommodate this change.

turn off validation

2006-01-05T21:10:00.000-08:00
It doesn't "validate" against the dtd if you tell it not to. It does
still
parse the dtd, parse entities, load default attribute values etc.
because
that's what dtd's are for. Certain parser flags may be available for
certain
parsers to limit this somewhat, but that's beyond what jdom has any
control
over.

Here's an example of setting Xerces to not validate w/ external DTD:

...
SAXBuilder builder = new SAXBuilder();

builder.setFeature("http://apache.org/xml/features/nonvalidating/load-ex
ternal-dtd", false);
...

video capture screen capture

2006-01-03T13:14:00.000-08:00
PGUIRobot http://sourceforge.net/projects/pguirobot/

java.awt.Robot

camstudio

http://graphicssoft.about.com/od/screenrecorders/

http://www.openqa.org/selenium/documentation.action

The above is QA GUI testing tool

cisco open source tool

2005-12-26T16:53:00.000-08:00
http://cosi-nms.sourceforge.net/alpha-progs.html

java Runtime.exec problem

2005-12-24T23:13:00.000-08:00
http://www.javaworld.com/javaworld/jw-12-2000/jw-1229-traps.html

Java Traps

When Runtime.exec() won't
Navigate yourself around pitfalls related to the Runtime.exec() method

Summary
In this installment of Java Traps, Michael Daconta discusses one new pitfall and revisits another from his previous column. Originating in the java.lang package, the pitfall specifically involves problems with the Runtime.exec() method. Daconta also corrects an error from Pitfall 3 and offers a simpler solution. (2,500 words)
By Michael C. Daconta

s part of the Java language, the java.lang package is implicitly imported into every Java program. This package's pitfalls surface often, affecting most programmers. This month, I'll discuss the traps lurking in the Runtime.exec() method.

Pitfall 4: When Runtime.exec() won't
The class java.lang.Runtime features a static method called getRuntime(), which retrieves the current Java Runtime Environment. That is the only way to obtain a reference to the Runtime object. With that reference, you can run external programs by invoking the Runtime class's exec() method. Developers often call this method to launch a browser for displaying a help page in HTML.

There are four overloaded versions of the exec() command:

public Process exec(String command);

public Process exec(String [] cmdArray);

public Process exec(String command, String [] envp);

public Process exec(String [] cmdArray, String [] envp);

For each of these methods, a command -- and possibly a set of arguments -- is passed to an operating-system-specific function call. This subsequently creates an operating-system-specific process (a running program) with a reference to a Process class returned to the Java VM. The Process class is an abstract class, because a specific subclass of Process exists for each operating system.

You can pass three possible input parameters into these methods:

A single string that represents both the program to execute and any arguments to that program

An array of strings that separate the program from its arguments

An array of environment variables

Pass in the environment variables in the form name=value. If you use the version of exec() with a single string for both the program and its arguments, note that the string is parsed using white space as the delimiter via the StringTokenizer class.

Stumbling into an IllegalThreadStateException
The first pitfall relating to Runtime.exec() is the IllegalThreadStateException. The prevalent first test of an API is to code its most obvious methods. For example, to execute a process that is external to the Java VM, we use the exec() method. To see the value that the external process returns, we use the exitValue() method on the Process class. In our first example, we will attempt to execute the Java compiler (javac.exe):

Listing 4.1 BadExecJavac.java

import java.util.*;
import java.io.*;

public class BadExecJavac
{
public static void main(String args[])
{
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("javac");
int exitVal = proc.exitValue();
System.out.println("Process exitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

A run of BadExecJavac produces:

E:\classes\com\javaworld\jpitfalls\article2>java BadExecJavac
java.lang.IllegalThreadStateException: process has not exited
at java.lang.Win32Process.exitValue(Native Method)
at BadExecJavac.main(BadExecJavac.java:13)

If an external process has not yet completed, the exitValue() method will throw an IllegalThreadStateException; that's why this program failed. While the documentation states this fact, why can't this method wait until it can give a valid answer?

A more thorough look at the methods available in the Process class reveals a waitFor() method that does precisely that. In fact, waitFor() also returns the exit value, which means that you would not use exitValue() and waitFor() in conjunction with each other, but rather would choose one or the other. The only possible time you would use exitValue() instead of waitFor() would be when you don't want your program to block waiting on an external process that may never complete. Instead of using the waitFor() method, I would prefer passing a boolean parameter called waitFor into the exitValue() method to determine whether or not the current thread should wait. A boolean would be more beneficial because exitValue() is a more appropriate name for this method, and it isn't necessary for two methods to perform the same function under different conditions. Such simple condition discrimination is the domain of an input parameter.

Therefore, to avoid this trap, either catch the IllegalThreadStateException or wait for the process to complete.

Now, let's fix the problem in Listing 4.1 and wait for the process to complete. In Listing 4.2, the program again attempts to execute javac.exe and then waits for the external process to complete:

Listing 4.2 BadExecJavac2.java

import java.util.*;
import java.io.*;

public class BadExecJavac2
{
public static void main(String args[])
{
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("javac");
int exitVal = proc.waitFor();
System.out.println("Process exitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

Unfortunately, a run of BadExecJavac2 produces no output. The program hangs and never completes. Why does the javac process never complete?

Why Runtime.exec() hangs
The JDK's Javadoc documentation provides the answer to this question:

Because some native platforms only provide limited buffer size for standard input and output streams, failure to promptly write the input stream or read the output stream of the subprocess may cause the subprocess to block, and even deadlock.

Is this just a case of programmers not reading the documentation, as implied in the oft-quoted advice: read the fine manual (RTFM)? The answer is partially yes. In this case, reading the Javadoc would get you halfway there; it explains that you need to handle the streams to your external process, but it does not tell you how.

Another variable is at play here, as is evident by the large number of programmer questions and misconceptions concerning this API in the newsgroups: though Runtime.exec() and the Process APIs seem extremely simple, that simplicity is deceiving because the simple, or obvious, use of the API is prone to error. The lesson here for the API designer is to reserve simple APIs for simple operations. Operations prone to complexities and platform-specific dependencies should reflect the domain accurately. It is possible for an abstraction to be carried too far. The JConfig library provides an example of a more complete API to handle file and process operations (see Resources below for more information).

Now, let's follow the JDK documentation and handle the output of the javac process. When you run javac without any arguments, it produces a set of usage statements that describe how to run the program and the meaning of all the available program options. Knowing that this is going to the stderr stream, you can easily write a program to exhaust that stream before waiting for the process to exit. Listing 4.3 completes that task. While this approach will work, it is not a good general solution. Thus, Listing 4.3's program is named MediocreExecJavac; it provides only a mediocre solution. A better solution would empty both the standard error stream and the standard output stream. And the best solution would empty these streams simultaneously (I'll demonstrate that later).

Listing 4.3 MediocreExecJavac.java

import java.util.*;
import java.io.*;

public class MediocreExecJavac
{
public static void main(String args[])
{
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("javac");
InputStream stderr = proc.getErrorStream();
InputStreamReader isr = new InputStreamReader(stderr);
BufferedReader br = new BufferedReader(isr);
String line = null;
System.out.println("");
while ( (line = br.readLine()) != null)
System.out.println(line);
System.out.println("");
int exitVal = proc.waitFor();
System.out.println("Process exitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

A run of MediocreExecJavac generates:

E:\classes\com\javaworld\jpitfalls\article2>java MediocreExecJavac

Usage: javac

where includes:
-g Generate all debugging info
-g:none Generate no debugging info
-g:{lines,vars,source} Generate only some debugging info
-O Optimize; may hinder debugging or enlarge class files
-nowarn Generate no warnings
-verbose Output messages about what the compiler is doing
-deprecation Output source locations where deprecated APIs are used
-classpath Specify where to find user class files
-sourcepath Specify where to find input source files
-bootclasspath Override location of bootstrap class files
-extdirs Override location of installed extensions
-d Specify where to place generated class files
-encoding Specify character encoding used by source files
-target Generate class files for specific VM version

Process exitValue: 2

So, MediocreExecJavac works and produces an exit value of 2. Normally, an exit value of 0 indicates success; any nonzero value indicates an error. The meaning of these exit values depends on the particular operating system. A Win32 error with a value of 2 is a "file not found" error. That makes sense, since javac expects us to follow the program with the source code file to compile.

Thus, to circumvent the second pitfall -- hanging forever in Runtime.exec() -- if the program you launch produces output or expects input, ensure that you process the input and output streams.

Assuming a command is an executable program
Under the Windows operating system, many new programmers stumble upon Runtime.exec() when trying to use it for nonexecutable commands like dir and copy. Subsequently, they run into Runtime.exec()'s third pitfall. Listing 4.4 demonstrates exactly that:

Listing 4.4 BadExecWinDir.java

import java.util.*;
import java.io.*;

public class BadExecWinDir
{
public static void main(String args[])
{
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("dir");
InputStream stdin = proc.getInputStream();
InputStreamReader isr = new InputStreamReader(stdin);
BufferedReader br = new BufferedReader(isr);
String line = null;
System.out.println("");
while ( (line = br.readLine()) != null)
System.out.println(line);
System.out.println("");
int exitVal = proc.waitFor();
System.out.println("Process exitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

A run of BadExecWinDir produces:

E:\classes\com\javaworld\jpitfalls\article2>java BadExecWinDir
java.io.IOException: CreateProcess: dir error=2
at java.lang.Win32Process.create(Native Method)
at java.lang.Win32Process.(Unknown Source)
at java.lang.Runtime.execInternal(Native Method)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at BadExecWinDir.main(BadExecWinDir.java:12)

As stated earlier, the error value of 2 means "file not found," which, in this case, means that the executable named dir.exe could not be found. That's because the directory command is part of the Windows command interpreter and not a separate executable. To run the Windows command interpreter, execute either command.com or cmd.exe, depending on the Windows operating system you use. Listing 4.5 runs a copy of the Windows command interpreter and then executes the user-supplied command (e.g., dir).

Listing 4.5 GoodWindowsExec.java

import java.util.*;
import java.io.*;

class StreamGobbler extends Thread
{
InputStream is;
String type;

StreamGobbler(InputStream is, String type)
{
this.is = is;
this.type = type;
}

public void run()
{
try
{
InputStreamReader isr = new InputStreamReader(is);
BufferedReader br = new BufferedReader(isr);
String line=null;
while ( (line = br.readLine()) != null)
System.out.println(type + ">" + line);
} catch (IOException ioe)
{
ioe.printStackTrace();
}
}
}

public class GoodWindowsExec
{
public static void main(String args[])
{
if (args.length < 1)
{
System.out.println("USAGE: java GoodWindowsExec ");
System.exit(1);
}

try
{
String osName = System.getProperty("os.name" );
String[] cmd = new String[3];

if( osName.equals( "Windows NT" ) )
{
cmd[0] = "cmd.exe" ;
cmd[1] = "/C" ;
cmd[2] = args[0];
}
else if( osName.equals( "Windows 95" ) )
{
cmd[0] = "command.com" ;
cmd[1] = "/C" ;
cmd[2] = args[0];
}

Runtime rt = Runtime.getRuntime();
System.out.println("Execing " + cmd[0] + " " + cmd[1]
+ " " + cmd[2]);
Process proc = rt.exec(cmd);
// any error message?
StreamGobbler errorGobbler = new
StreamGobbler(proc.getErrorStream(), "ERROR");

// any output?
StreamGobbler outputGobbler = new
StreamGobbler(proc.getInputStream(), "OUTPUT");

// kick them off
errorGobbler.start();
outputGobbler.start();

// any error???
int exitVal = proc.waitFor();
System.out.println("ExitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

Running GoodWindowsExec with the dir command generates:

E:\classes\com\javaworld\jpitfalls\article2>java GoodWindowsExec "dir *.java"
Execing cmd.exe /C dir *.java
OUTPUT> Volume in drive E has no label.
OUTPUT> Volume Serial Number is 5C5F-0CC9
OUTPUT>
OUTPUT> Directory of E:\classes\com\javaworld\jpitfalls\article2
OUTPUT>
OUTPUT>10/23/00 09:01p 805 BadExecBrowser.java
OUTPUT>10/22/00 09:35a 770 BadExecBrowser1.java
OUTPUT>10/24/00 08:45p 488 BadExecJavac.java
OUTPUT>10/24/00 08:46p 519 BadExecJavac2.java
OUTPUT>10/24/00 09:13p 930 BadExecWinDir.java
OUTPUT>10/22/00 09:21a 2,282 BadURLPost.java
OUTPUT>10/22/00 09:20a 2,273 BadURLPost1.java
... (some output omitted for brevity)
OUTPUT>10/12/00 09:29p 151 SuperFrame.java
OUTPUT>10/24/00 09:23p 1,814 TestExec.java
OUTPUT>10/09/00 05:47p 23,543 TestStringReplace.java
OUTPUT>10/12/00 08:55p 228 TopLevel.java
OUTPUT> 22 File(s) 46,661 bytes
OUTPUT> 19,678,420,992 bytes free
ExitValue: 0

Running GoodWindowsExec with any associated document type will launch the application associated with that document type. For example, to launch Microsoft Word to display a Word document (i.e., one with a .doc extension), type:

>java GoodWindowsExec "yourdoc.doc"

Notice that GoodWindowsExec uses the os.name system property to determine which Windows operating system you are running -- and thus determine the appropriate command interpreter. After executing the command interpreter, handle the standard error and standard input streams with the StreamGobbler class. StreamGobbler empties any stream passed into it in a separate thread. The class uses a simple String type to denote the stream it empties when it prints the line just read to the console.

Thus, to avoid the third pitfall related to Runtime.exec(), do not assume that a command is an executable program; know whether you are executing a standalone executable or an interpreted command. At the end of this section, I will demonstrate a simple command-line tool that will help you with that analysis.

It is important to note that the method used to obtain a process's output stream is called getInputStream(). The thing to remember is that the API sees things from the perspective of the Java program and not the external process. Therefore, the external program's output is the Java program's input. And that logic carries over to the external program's input stream, which is an output stream to the Java program.

Runtime.exec() is not a command line
One final pitfall to cover with Runtime.exec() is mistakenly assuming that exec() accepts any String that your command line (or shell) accepts. Runtime.exec() is much more limited and not cross-platform. This pitfall is caused by users attempting to use the exec() method to accept a single String as a command line would. The confusion may be due to the fact that command is the parameter name for the exec() method. Thus, the programmer incorrectly associates the parameter command with anything that he or she can type on a command line, instead of associating it with a single program and its arguments. In listing 4.6 below, a user tries to execute a command and redirect its output in one call to exec():

Listing 4.6 BadWinRedirect.java

import java.util.*;
import java.io.*;

// StreamGobbler omitted for brevity

public class BadWinRedirect
{
public static void main(String args[])
{
try
{
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("java jecho 'Hello World' > test.txt");
// any error message?
StreamGobbler errorGobbler = new
StreamGobbler(proc.getErrorStream(), "ERROR");

// any output?
StreamGobbler outputGobbler = new
StreamGobbler(proc.getInputStream(), "OUTPUT");

// kick them off
errorGobbler.start();
outputGobbler.start();

// any error???
int exitVal = proc.waitFor();
System.out.println("ExitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

Running BadWinRedirect produces:

E:\classes\com\javaworld\jpitfalls\article2>java BadWinRedirect
OUTPUT>'Hello World' > test.txt
ExitValue: 0

The program BadWinRedirect attempted to redirect the output of an echo program's simple Java version into the file test.txt. However, we find that the file test.txt does not exist. The jecho program simply takes its command-line arguments and writes them to the standard output stream. (You will find the source for jecho in the source code available for download in Resources.) In Listing 4.6, the user assumed that you could redirect standard output into a file just as you could on a DOS command line. Nevertheless, you do not redirect the output through this approach. The incorrect assumption here is that the exec() method acts like a shell interpreter; it does not. Instead, exec() executes a single executable (a program or script). If you want to process the stream to either redirect it or pipe it into another program, you must do so programmatically, using the java.io package. Listing 4.7 properly redirects the standard output stream of the jecho process into a file.

Listing 4.7 GoodWinRedirect.java

import java.util.*;
import java.io.*;

class StreamGobbler extends Thread
{
InputStream is;
String type;
OutputStream os;

StreamGobbler(InputStream is, String type)
{
this(is, type, null);
}

StreamGobbler(InputStream is, String type, OutputStream redirect)
{
this.is = is;
this.type = type;
this.os = redirect;
}

public void run()
{
try
{
PrintWriter pw = null;
if (os != null)
pw = new PrintWriter(os);

InputStreamReader isr = new InputStreamReader(is);
BufferedReader br = new BufferedReader(isr);
String line=null;
while ( (line = br.readLine()) != null)
{
if (pw != null)
pw.println(line);
System.out.println(type + ">" + line);
}
if (pw != null)
pw.flush();
} catch (IOException ioe)
{
ioe.printStackTrace();
}
}
}

public class GoodWinRedirect
{
public static void main(String args[])
{
if (args.length < 1)
{
System.out.println("USAGE java GoodWinRedirect ");
System.exit(1);
}

try
{
FileOutputStream fos = new FileOutputStream(args[0]);
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec("java jecho 'Hello World'");
// any error message?
StreamGobbler errorGobbler = new
StreamGobbler(proc.getErrorStream(), "ERROR");

// any output?
StreamGobbler outputGobbler = new
StreamGobbler(proc.getInputStream(), "OUTPUT", fos);

// kick them off
errorGobbler.start();
outputGobbler.start();

// any error???
int exitVal = proc.waitFor();
System.out.println("ExitValue: " + exitVal);
fos.flush();
fos.close();
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

Running GoodWinRedirect produces:

E:\classes\com\javaworld\jpitfalls\article2>java GoodWinRedirect test.txt
OUTPUT>'Hello World'
ExitValue: 0

After running GoodWinRedirect, test.txt does exist. The solution to the pitfall was to simply control the redirection by handling the external process's standard output stream separately from the Runtime.exec() method. We create a separate OutputStream, read in the filename to which we redirect the output, open the file, and write the output that we receive from the spawned process's standard output to the file. Listing 4.7 completes that task by adding a new constructor to our StreamGobbler class. The new constructor takes three arguments: the input stream to gobble, the type String that labels the stream we are gobbling, and the output stream to which we redirect the input. This new version of StreamGobbler does not break any of the code in which it was previously used, as we have not changed the existing public API -- we only extended it.

Since the argument to Runtime.exec() is dependent on the operating system, the proper commands to use will vary from one OS to another. So, before finalizing arguments to Runtime.exec() and writing the code, quickly test the arguments. Listing 4.8 is a simple command-line utility that allows you to do just that.

Here's a useful exercise: try to modify TestExec to redirect the standard input or standard output to a file. When executing the javac compiler on Windows 95 or Windows 98, that would solve the problem of error messages scrolling off the top of the limited command-line buffer.

Listing 4.8 TestExec.java

import java.util.*;
import java.io.*;

// class StreamGobbler omitted for brevity

public class TestExec
{
public static void main(String args[])
{
if (args.length < 1)
{
System.out.println("USAGE: java TestExec \"cmd\"");
System.exit(1);
}

try
{
String cmd = args[0];
Runtime rt = Runtime.getRuntime();
Process proc = rt.exec(cmd);

// any error message?
StreamGobbler errorGobbler = new
StreamGobbler(proc.getErrorStream(), "ERR");

// any output?
StreamGobbler outputGobbler = new
StreamGobbler(proc.getInputStream(), "OUT");

// kick them off
errorGobbler.start();
outputGobbler.start();

// any error???
int exitVal = proc.waitFor();
System.out.println("ExitValue: " + exitVal);
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

Running TestExec to launch the Netscape browser and load the Java help documentation produces:

E:\classes\com\javaworld\jpitfalls\article2>java TestExec "e:\java\docs\index.html"
java.io.IOException: CreateProcess: e:\java\docs\index.html error=193
at java.lang.Win32Process.create(Native Method)
at java.lang.Win32Process.(Unknown Source)
at java.lang.Runtime.execInternal(Native Method)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at java.lang.Runtime.exec(Unknown Source)
at TestExec.main(TestExec.java:45)

Our first test failed with an error of 193. The Win32 error for value 193 is "not a valid Win32 application." This error tells us that no path to an associated application (e.g., Netscape) exists, and that the process cannot run an HTML file without an associated application.

Therefore, we try the test again, this time giving it a full path to Netscape. (Alternately, we could add Netscape to our PATH environment variable.) A second run of TestExec produces:

E:\classes\com\javaworld\jpitfalls\article2>java TestExec
"e:\program files\netscape\program\netscape.exe e:\java\docs\index.html"
ExitValue: 0

This worked! The Netscape browser launches, and it then loads the Java help documentation.

One additional improvement to TestExec would include a command-line switch to accept input from standard input. You would then use the Process.getOutputStream() method to pass the input to the spawned external program.

To sum up, follow these rules of thumb to avoid the pitfalls in Runtime.exec():

You cannot obtain an exit status from an external process until it has exited

You must immediately handle the input, output, and error streams from your spawned external process

You must use Runtime.exec() to execute programs

You cannot use Runtime.exec() like a command line

Correction to Pitfall 3
In the discussion of Pitfall 3 ("Don't mix floats and doubles when generating text or XML messages") in my last column, I incorrectly stated that the different string representation of a decimal number after casting it from a float to a double was a bug. While this is a pitfall, its cause is not a bug, but the fact that the decimal numbers in question -- 100.28 and 91.09 -- do not represent precisely in binary. I'd like to thank Thomas Okken and the others who straightened me out. If you enjoy discussing the finer points of numerical methods, you can email Thomas.

The combination of forgetting my numerical methods class, the numerous bug reports on the bug parade, and the automatic rounding of floats and doubles when printing (but not after casting a float to a double) threw me. I apologize for confusing anyone who read the article, especially to new Java programmers. I present two better solutions to the problem:

The first possible solution is to always specify the desired rounding explicitly with NumberFormat. In my case, I use the float and double to represent dollars and cents; therefore, I need only two significant digits. Listing C3.1 demonstrates how to use the NumberFormat class to specify a maximum of two fraction digits.

Listing C3.1 FormatNumbers.java

import java.text.*;

public class FormatNumbers
{
public static void main(String [] args)
{
try
{
NumberFormat fmt = NumberFormat.getInstance();
fmt.setMaximumFractionDigits(2);
float f = 100.28f;
System.out.println("As a float : " + f);
double d = f;
System.out.println("Cast to a double : " + d);
System.out.println("Using NumberFormat: " + fmt.format(d));
} catch (Throwable t)
{
t.printStackTrace();
}
}
}

When we run the FormatNumbers program, it produces:

E:\classes\com\javaworld\jpitfalls\article2>java FormatNumbers
As a float : 100.28
Cast to a double : 100.27999877929688
Using NumberFormat: 100.28

As you can see -- regardless of whether we cast the float to a double -- when we specify the number of digits we want, it properly rounds to that precision -- even if the number is infinitely repeating in binary. To circumvent this pitfall, control the formatting of your doubles and floats when converting to a String.

A second, simpler solution would be to not use a float to represent cents. Integers (number of pennies) can represent cents, with a legal range of 0 to 99. You can check the range in the mutator method.

Next time
In my next column, I'll present another pitfall from java.lang, as well as two traps hiding in the java.net and the Swing packages. If you know of any Java pitfalls that have wasted your time and caused you frustration, please email them to me so we can save others the same fate.

About the author
Michael C. Daconta is the director of Web and technology services for McDonald Bradley, where he conducts training seminars and develops advanced systems with Java, JavaScript, and XML. Over the past 15 years, Daconta has held every major development position, including chief scientist, technical director, chief developer, team leader, systems analyst, and programmer. He is a Sun-certified Java programmer and coauthor of Java Pitfalls (John Wiley & Sons, 2000), Java 2 and JavaScript for C and C++ Programmers (John Wiley & Sons, 1999), and XML Development with Java 2 (Sams Publishing, 2000). In addition, he is the author of C++ Pointers and Dynamic Memory

open source cdp netdisco

2005-12-24T18:43:00.000-08:00
NetDisco tool
http://netdisco.org/269,21,Details ► Architecture

network simulation tool

2005-12-24T18:28:00.000-08:00
http://ontwerpen1.khlim.be/projects/netsim/

Zebra
ADIOS ( Automated Download and Installation of Operating Systems)
SSF Network Simulation

reverse proxy

2005-12-24T17:46:00.000-08:00
http://www.sans.org/rr/whitepapers/webservers/302.php

A Reverse Proxy Is A Proxy By Any Other Name
By Art Stricek
Version 1.2f
January 10, 2002

primary key

2005-12-14T13:03:00.000-08:00
http://r937.com/20020620.html

Online Extra
Mike Lonigro

The Case for the Surrogate Key
A simple key to the flexible enterprise database
There is a simple, inexpensive, uniform element of database design that you are likely avoiding in favor of a complex, costly, and inconsistent one. This element is the surrogate or substitute primary key. It seems that designers avoid these independent keys like the plague. Instead, all but the most basic business entities are given keys made up of some series of attributes, borrowed keys, and sequence numbers . It was only after experiencing many problems at the hand of intelligent keys that I, too, became a believer in the flexibility and stability afforded by the substitute key.
In this article I'll illustrate why the surrogate primary key is a critically important ingredient in designing stable, flexible, and well-performing enterprise databases. I will define the issues, analyze them to arrive at a set of principles of primary key design, identify the criteria for defining a surrogate key on a table, suggest a standard for implementation, and finally, note some benefits our shop (J. B. Hunt Transport Inc.) enjoys from consistent application of a surrogate primary key.
THE ISSUES
The first issue is the function of the primary key. What exactly is the real purpose of the primary key? Because form follows function, defining the role of the primary key will settle much debate about its format, and it will help us determine some principles with which we can resolve the remaining issues.
Another issue is the distinction between the logical and physical keys. Can these keys be the same? For example, a customer identifier and date may be used to check for a duplicate order before entering it into a database. A sequence number may be added to distinguish line items one from another. But once the order and line items are entered into the database, should these data elements form the primary keys for these tables?
The meaningfulness of the primary key is another issue I'll discuss. How much information should the primary key hold? For example, a legacy system in our shop gave to each transport accident a primary key formed by combining the year with an accident sequence number and a type code. Another application assigned order numbers within ranges based on order type. Are these good choices for the primary key?
The final issue I will address is the source of the primary key. Can it be provided from outside the system or by a system user? Examples are Social Security numbers to identify people; user-generated pnemonic codes to identify customers and accounts; and catalog, part, or transaction numbers generated by external agencies. Why not use these identifiers as primary keys?
ANALYSIS
Proper primary key design recognizes that there are two unique keys to be considered. Database designers make a critical mistake when they fail to recognize the distinction between these keys. The logical unique key distinguishes entity occurrences from others to avoid duplicates before entry into the database. That is why this key is typically composed of attributes and relationships that the business can recognize as distinguishing occurrences logically from others. The primary key, however, is a physical design element that uniquely identifies rows after they are in the database. It is used in creating foreign keys in other tables in order to establish the logical relationships in the data model. In fact, it is best to consider a primary key's primary purpose to be establishing relationships in the database!
The primary key's role as a physical row identifier has important implications. First, it requires that the primary key be physically unique in the primary key table. Tables are sometimes created with primary keys that logically identify occurrences but may appear more than once in the primary key table. This repetition usually betrays a failure to define properly either the criteria for new occurrences of the entity or the real physical purpose of the table.
For example, a table may store work order types and identify them with a number or code. But the identifier may appear on more than one "inactive" row in the primary key table with perhaps one occurrence in an "active" status. In this case, the meaning of the work order type becomes unclear. Are all rows with the same key related to the original occurrence? Or are they truly different work order types that have passed their identifiers to newer occurrences? Alternatively, several rows sharing a primary key value may be distinguished by effective and end date ranges. In this case, the table is really acting as an audit of changes to the logical occurrence. But what table really represents the business entity itself?
Second, the primary key must never be null. This must be true even if any of the elements of the logical unique key are unknown. Like nonunique primary keys, null primary keys usually signal a failure to define clearly what the row represents. If we create an ORDER but fail to give it an order number until it is shipped, does the row represent the ORDER or the SHIPMENT? If we create an EMPLOYEE APPLICANT but do not assign a key until the application is received, are we equating the APPLICANT with the APPLICATION? What happens if we get a second APPLICATION from the same APPLICANT?
Third, the primary key must be absolutely stable. It must be protected in all cases from change. This does not mean protected from likely change; rather, it must be guaranteed not to be allowed to change. This third principle is always violated when an "intelligent" key is used as the primary key.
In the first example, the relationships and attributes that logically identify the order and line item are also used as the primary key (see Figure 1). One problem with these is that they can change. The order's customer may be incorrectly entered, for example. If we discover the error midway through processing the order, how do we correct it? There are two unpleasant options: We can either create a brand new order and cancel the original, or we can change the primary key value of the order. Suppose we choose the first option and create another order. Is this a true picture of business reality? That is, do we really have another order? Do we really want to reprocess the order under a new identifier?
1A If any attribute making up the primary key of the ORDER or ORDER LINE ITEM changes, all foreign key references to these tables (TABLE A, TABLE B, and TABLE C) must also be updated and committed together.

1B Here the ORDER and ORDER LINE ITEM tables have surrogate primary keys different than the unique keys. All foreign key references to them (TABLE A, TABLE B, and TABLE C) are insulated from changes to unique key attributes.

Figure 1. Eliminating the Effect of Change in Key Value.

The second option is to change the value of the order's primary key. In this case, we must also change every foreign key reference to the order within the same commit unit! Each new reference must also be included in this update. Would it not be more correct and efficient simply to change the order's customer and continue processing the order? A surrogate key independent of all the order's attributes or relationships allows us to correct the order and maintain the information already contained in the database easily.
Another problem illustrated here is that of concatenated primary keys. Because the order's primary key in our example has been migrated into the primary key of the line item, all references to the order line item must also change with a change in the order's key. The problem grows as we chain together more keys in the database. Migration of primary keys in this fashion has terrible implications for database flexibility.
These examples illustrate how primary keys must be insulated from changes in value and so should not comprise attributes, relationships, or primary keys migrated from other tables. But even if its value is truly stable, the primary key must never be the same as the logical unique key because the set of attributes and relationships that make an entity unique may itself change.
Associative entities provide a good example of this (see Figure 2). An associative entity contains attributes about a many-to-many relationship between two or more occurrences. Because the entity is defined by its relationships, we are tempted to use the foreign key columns in the primary key. For example, our company has a PART OFFERING associative entity, which stores pricing and configuration information for a PART as it is sold or offered by a VENDOR. A PART OFFERING is unique on the PART id, VENDOR id, and offering date. Why not use these columns as the primary key?
2A Here the PART OFFERING associative entity uses the logical unique key as the primary key. A change requiring PART OFFERINGs to be unique additionally on TIME requires changes to all related foreign key structures (TABLE A and TABLE B).

2B The PART OFFERING has a surrogate key different from the logical unique key. The new requirement to make PART OFFERING unique on an additional TIME attribute does not impact any foreign key structures (TABLE A and TABLE B).

Figure 2. Eliminating the Effect of Change in Key Structure.

The reason is that over time, the business may wish to capture PART OFFERINGs at a finer level of detail. We may begin to track multiple PART OFFERINGs for fuel offered by the same vendor at more than one price in a day. If we had used the unique key as the primary key, we would need to modify all programs and tables that reference unique PART OFFERINGs to include the offering time. A more stable design would give the PART OFFERING a surrogate key. The new business requirement would require only changes to the unique key index on the PART OFFERING table and any programs that insert or update its rows. The programs and other tables referencing the PART OFFERING by the surrogate key would be unaffected.
The third issue I raised involves primary keys that contain attributes unrelated to the logical unique key. This type of key appears in many forms and is subject to the same problems I addressed above. Additionally, these keys are especially inflexible to expansion of the definition or usage of data. New subtypes of orders or accidents, for example, are typically handled by assigning different ranges or formats of primary key values. As these applications increase, smaller key ranges cause rollover and archiving issues while applications are forced to come up with imaginative new identification schemes just to insert a row in the database.
Another example of this kind of key occurs when a key value implicitly represents a hierarchy among rows in a table. This type of key is inflexible to additional levels and limits the number of occurrences at any given level. For example, standard commodity codes used across the transportation industry are assigned key values whose format indicates an arbitrary level in a hierarchy of commodity classifications. A broad commodity classification is given a key of 100000; the classification level immediately beneath it has keys of the form 101000, 102000, and so on; and the next level keys of the form 101010, 101020. A better design would give each occurrence a surrogate primary key; child occurrences would have a foreign key back to the parent. In this way, classifications can have a varying and unlimited number of levels and occurrences.
Finally, primary key values must be internally assigned. The first reason is, again, due to stability. Social Security numbers may be miskeyed, unknown, or changed; business users may invent new coding schemes to identify customers; and outside agencies may reformat or reuse identifiers at their own will.
Another reason the values must be assigned internally is that we may define entities differently than the outside agencies that provide our data. For example, a vendor that sells us uniforms uses a different ITEM number to identify each different size of uniform. In our database, however, we create one ITEM with many sizes. This standard definition allows us to draw consistent information out of the database independent of vendor numbering schemes. Using the vendor's assigned ITEM number would cause us to create ITEMs based on each vendor's definition and not ours.
The best way to avoid the pitfalls indicated by these illustrations is to choose a primary key that is logically meaningless; this is the surrogate primary key. Doing this means, above all, that the primary key must be owned by the data administrator. Intelligent, problematic primary keys will be assigned when application developers or users begin to take ownership of the primary key. When this happens, the real purpose of the primary key is lost; it becomes a "good idea" number that tells a story about the row it identifies. The primary key is not a "good idea" number; its purpose is to physically identify a row to the database.
To summarize, the primary key must be:
Unique
Not null
Stable
Different than the logical unique key
Internally assigned
Logically meaningless.
THE CRITERIA
Does every table require a surrogate primary key? The answer is no. The prerequisites derive from the definition of the primary key. Because the primary key identifies a row after it is in the database, it follows that a table requires a primary key if its rows will be referenced individually by other tables after entry into the database.
There are two alternative views of this. The logical view asks: does the table participate in more than one relationship from the logical data model? For example, in a human resources database, an EMPLOYEE table will likely participate in more than one relationship; we may relate the EMPLOYEE to BENEFITs, POSITIONs, LOCATIONs, EVALUATIONs, and many other entities in our data model. For this reason, the EMPLOYEE gets a surrogate key (see Figure 3). But now suppose we need a table to store the EMPLOYEE DEPENDENTs. We must determine whether or not the DEPENDENT participates in more than one relationship from the data model. If we care to relate the DEPENDENT only to the EMPLOYEE, then the DEPENDENT table represents a repeating attribute of the EMPLOYEE entity. It does not require a surrogate key, but it may have a unique key consisting of the EMPLOYEE key and some combination of attributes of the DEPENDENT. If, however, we also wish to relate DEPENDENTs to BENEFITs, then the DEPENDENT participates in a second relationship, becomes an entity in the logical data model, and gets a surrogate key.
3A The DEPENDENT is related only to the EMPLOYEE, and has a unique key but no surrogate key.

3B The DEPENDENT has its own relationships (TABLE A and TABLE B) and gets a surrogate key.

Figure 3. The Data Model in Primary Key Assignment.

The physical view asks: Do we need to reference the rows individually for physical processing reasons? For example, we may wish to trigger certain DEPENDENTs to be processed through some application. Rather than reading all rows in the table looking for a few process flags, we may give the DEPENDENT a surrogate key and store the values of the "flagged" DEPENDENTs in a trigger table. After the DEPENDENT is processed, the row representing the DEPENDENT in the trigger table is deleted. This may be simpler than storing the series of columns that reference a single DEPENDENT.
A SUGGESTED STANDARD
Our shop has enjoyed success with the implementation of a simple primary key standard containing two critical elements. First, all our primary keys are sequentially assigned positive integers. In DB2, we use a large INTEGER column. This allows us to store more than 2.1 billion occurrences of any entity in our model. We can create an occurrence every second of every day for 68 years and still not run out of values. Certainly few business entities are created this frequently.
Second, all primary keys are assigned through an enterprise module that receives a logical table name, obtains an exclusive lock on a row containing that table's next primary key value, increments the value, and passes it back to the caller. The primary key is assigned by logical table because we sometimes split a logical table into two or more physical tables for performance. The rows that form the one logical row share their primary key value.
THE BENEFITS
The consistent format of primary keys throughout our database provides benefits in addition to flexibility. One is in the implementation of optional relationships (see Figure 4). For example, we create INVOICE ITEMs but may not relate them to an INVOICE until perhaps several days later. The INVOICE foreign key in the INVOICE ITEM table thus needs to be logically null. Physically, however, a zero or dummy INVOICE value would heavily skew the foreign key index. Instead, the null foreign key receives a value equal to the row's own primary key multiplied by negative one. This distributes the foreign key index values evenly across all rows, whether or not the foreign key relationship exists.
4 The INVOICE ITEM has an optional relationship to the INVOICE. ITEMs without a related INVOICE receive a foreign key value equal to their primary key multiplied by -1. The index over the INVOICE foreign key is evenly distributed.

Figure 4. Handling Absent Foreign Keys.

A second benefit is that "Exclusive OR" relationships can be handled with one well-indexed column (see Figure 5). An "Exclusive OR" relationship exists when an entity occurrence may relate to at most one of a number of possible occurrences. A given INVOICE ITEM, for example, may pertain to one of any number of different possible entities in our model; we may invoice SHIPMENTs, STOPs, ACTIVITIES, or others. Different primary key domains would require a foreign key for each possible relationship, all but one of which would contain a value. Instead, we use a single indexed foreign key column. A second column names the table referenced by the foreign key.
5 The INVOICE ITEM can bill a SHIPMENT, STOP, or ACTIVITY, exclusively. A single foreign key handles all relationships. A second column names the table containing the primary key value.

Figure 5. Handlign Exclusive or Foreign Keys.

Poor primary key design is perhaps the most repeated and damaging flaw in database design. We would do well to remember that a smart key is a dumb thing to do, while a dumb key is a smart thing to do.
Mike Lonigro is the senior data administrator responsible for all conceptual, logical, and physical database design at J. B. Hunt Transport Inc., the nation's largest publicly held truckload carrier. J.B. Hunt Transport runs on DB2 for OS/390 at more than 3 million transactions per day. Previously, Lonigro was a consultant with Price Waterhouse MCS in the Petroleum Special Practice Unit. You can reach him via email at lonigro@mail.jbhunt.com.

search - home - archives - contacts - site index

Copyright 1997 Miller Freeman Inc. All Rights Reserved
Redistribution without permission is prohibited.

Questions? Comments? We wo

java certificate

2005-12-07T21:54:00.000-08:00
http://www.jabacats.com/

thread dump stack trace

2005-11-21T23:05:00.000-08:00
http://www.me.umn.edu/~shivane/blogs/cafefeed/archive/2004_06_01_archive.html

linux tuning virtual memory

2005-11-01T22:35:00.000-08:00
http://www.weberdev.com/Manuals/rhl-rg-en-73/s1-proc-directories.html

http://people.redhat.com/nmurray/RHEL-2.1-VM-whitepaper.pdf