tryllian.are.security
Class DNAComposer

java.lang.Object
  tryllian.are.security.DNAComposer

public class DNAComposer

extends java.lang.Object

The DNAComposer class can be used to programmatically create and update DNA files.

Creating a new DNA file requires the following properties to be set:

• agent descriptor
• keystore
• alias
• password

Updating a new DNA file requires the following properties to be set:

• keystore
• alias
• password

Using an illegal value when setting one of these properties will always result in an (unchecked) NullPointerException or IllegalArgumentException.

If something goes wrong in the process of creating the DNA file, a (checked) DNAComposerException is thrown, usually wrapping an exception with a more specific cause.

Once a DNAComposer has been created, the object can be used to create more than one file; properties will be remembered between calls, making it possible to use the same keystore for multiple DNA files without having to set it each time.

For more information on creating and updating DNA files, please refer to the ARE specification.

Field Summary

static int	COMPRESS If this flag is set in the option mask, the DNA file will be compressed.
static int	NOVERIFY If this flag is set, the resulting DNA-file is not verified.
static int	OVERWRITE If this flag is set in the option mask and creating the DNA file would overwrite an existing file, the overwrite will take place.
static int	VERBOSE Deprecated. logging/verbosity/debugging is now controlled through Log4J

Constructor Summary

DNAComposer()
Creates a new DNAComposer object.

Method Summary

java.io.File	createDNAFile(java.io.File out, java.io.File jarPath) Creates the DNA file.
java.io.File	createDNAFile(java.io.File out, java.io.File[] jarfiles) Creates the DNA file.
java.io.File	createDNAFile(java.io.File out, java.net.URL[] jarFiles) Creates the DNA file.
void	setAlias(java.lang.String alias) Sets the alias that will be used to retrieve the private key from the keystore.
void	setDescriptor(java.io.File descriptor) Sets the Descriptor file.
void	setDescriptor(java.net.URL descriptor) Sets the Descriptor file.
void	setKeyStore(java.io.File keyStore) Sets the keystore that contains the private key.
void	setKeyStore(java.net.URL keyStore) Sets the keystore that contains the private key.
void	setOptions(int options) Sets the options with which the DNA file will be created.
void	setPassword(char[] password) Sets the password that is used to unlock the keystore to retrieve the alias.
java.io.File	updateDNAFile(java.io.File out, java.io.File original, java.io.File[] newJarFiles) Updates the DNA file.
java.io.File	updateDNAFile(java.io.File out, java.net.URL original, java.net.URL[] newJarFiles) Updates the DNA file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPRESS

public static final int COMPRESS

If this flag is set in the option mask, the DNA file will be compressed.

See Also:

Constant Field Values

OVERWRITE

public static final int OVERWRITE

If this flag is set in the option mask and creating the DNA file would overwrite an existing file, the overwrite will take place. Otherwise, an exception will be thrown.

See Also:

Constant Field Values

VERBOSE

public static final int VERBOSE

Deprecated. logging/verbosity/debugging is now controlled through Log4J

If this flag is set debugging output will be written to the default habitat log file.

See Also:

Constant Field Values

NOVERIFY

public static final int NOVERIFY

If this flag is set, the resulting DNA-file is not verified. It is strongly recommend you do not use this flag!

See Also:

Constant Field Values

Constructor Detail

DNAComposer

public DNAComposer()

Creates a new DNAComposer object.

Method Detail

setDescriptor

public void setDescriptor(java.net.URL descriptor)
                   throws DNAComposerException,
                          java.lang.NullPointerException

Sets the Descriptor file. A descriptor file is a description in XML format of the components that make up an agent.

Parameters:

descriptor - A URL that points to the file that contains the agent description, should not be null.

Throws:

java.lang.NullPointerException - if the descriptor passed was null after all

DNAComposerException - if the descriptor URL is invalid

setDescriptor

public void setDescriptor(java.io.File descriptor)
                   throws DNAComposerException,
                          java.lang.NullPointerException

Sets the Descriptor file. A descriptor file is a description in XML format of the components that make up an agent. See the spec.

Parameters:

descriptor - A file object that points to the file that contains the agent description, cannot be null

Throws:

DNAComposerException - if the descriptor name cannot be converted to a valid URL

java.lang.NullPointerException - if the descriptor passed is null

setKeyStore

public void setKeyStore(java.net.URL keyStore)
                 throws java.lang.NullPointerException

Sets the keystore that contains the private key.

Parameters:

keyStore - A URL object that points to the keystore, cannot be null.

Throws:

java.lang.NullPointerException - if the keystore passed is null

setKeyStore

public void setKeyStore(java.io.File keyStore)
                 throws java.lang.NullPointerException

Sets the keystore that contains the private key.

Parameters:

keyStore - A File that points to the keystore, cannot be null.

Throws:

java.lang.NullPointerException - if the keystore passed is null

setAlias

public void setAlias(java.lang.String alias)
              throws java.lang.NullPointerException

Sets the alias that will be used to retrieve the private key from the keystore.

Parameters:

alias - the alias of the private key entry in the keystore, cannot be null.

Throws:

java.lang.NullPointerException - if the alias passed is null

setPassword

public void setPassword(char[] password)
                 throws java.lang.NullPointerException

Sets the password that is used to unlock the keystore to retrieve the alias.

Parameters:

password - the password that unlocks the private key

Throws:

java.lang.NullPointerException - if the password passed is null

setOptions

public void setOptions(int options)

Sets the options with which the DNA file will be created. This method replaces all previously set options.

Parameters:

options - An integer that contains the options or-ed together. The value 0 resets all options to their default value "off".

createDNAFile

public java.io.File createDNAFile(java.io.File out,
                                  java.io.File jarPath)
                           throws DNAComposerException

Creates the DNA file.

Parameters:

out - The name for the new DNA file, cannot be null.

jarPath - The directory where the DNAComposer will look for the jarfiles that will be stored in the DNA file; can be null if there are no 'file's specified in the agent descriptor.

Returns:

the DNA File that has been created.

Throws:

DNAComposerException - on any failure. The DNAComposerExceptoin will usually wrap a more specific exception, that can be approached using the DNAComposerException.getCause() method. This wrapped exception might be one of the following:
IOException, in the following cases:

• The out file cannot be written
• The directory designated by jarPath does not exist
• Not all files named in the descriptor can be found or read in the jarPath directory
• The file pointing to the agent descriptor does not exist or does not contain a valid agent descriptor
• The keystore cannot be read

SecurityException if one of the following is true:

• The alias does not exist in the keystore
• The password is not correct
• The alias does not point to a private key
• Signing failed

IllegalStateException if one of the following is true:

• The keystore has not been set
• The alias has not been set
• The password has not been set
• The descriptor has not been set

createDNAFile

public java.io.File createDNAFile(java.io.File out,
                                  java.io.File[] jarfiles)
                           throws DNAComposerException

Creates the DNA file.

Parameters:

out - The name for the new DNA file, cannot be null.

jarfiles - The list of all jarfiles that are stored in the DNA file. This list must match the names specified in the agent descriptor. Can be null (if there are no file objects), but cannot contain null objects.

Returns:

the DNA File that has been created.

Throws:

DNAComposerException - on failure. The DNAComposerExceptoin will usually wrap a more specific exception, that can be approached using the DNAComposerException.getCause() method. This wrapped exception might be one of the following:
IOException if one of the following is true:

• The out file cannot be written
• Not all files named in the descriptor can be found in the jarfiles array.
• Not all files in the jarfiles array are named in the agent descriptor.
• The file pointing to the agent descriptor does not exist or does not contain a valid agent descriptor
• The keystore cannot be read

SecurityException if one of the following is true:

• The alias does not exist in the keystore
• The password is not correct
• The alias does not point to a private key
• Signing failed

IllegalStateException if one of the following is true:

• The keystore has not been set
• The alias has not been set
• The password has not been set
• The descriptor has not been set

updateDNAFile

public java.io.File updateDNAFile(java.io.File out,
                                  java.io.File original,
                                  java.io.File[] newJarFiles)
                           throws DNAComposerException

Updates the DNA file.

Parameters:

out - The name of the new DNA file, cannot be null.

original - The name of the DNA file that will be updated, cannot be null.

newJarFiles - An array of File objects pointing to the new jarfiles for the updated DNA file. If there are no new files (for example, only the certificate used for signing has been changed), this array can be null. The array cannot contain null objects.

Returns:

A File object that points to the created DNA file.

Throws:

DNAComposerException - on failure The DNAComposerExceptoin will usually wrap a more specific exception, that can be approached using the DNAComposerException.getCause() method. This wrapped exception might be one of the following:
IOException if one of the following is true:

• The out file cannot be written
• The original file cannot be read
• Not all files named in the descriptor can be found in the original or the newJarFiles array
• Not all files specified in the newJarFiles array are named in the descriptor.
• If a new agent descriptor has been set, the file pointing to the agent descriptor does not exist or does not contain a valid agent descriptor
• The keystore cannot be read

SecurityException if one of the following is true:

• The alias does not exist in the keystore
• The password is not correct
• The alias does not point to a private key
• Signing failed

IllegalStateException if one of the following is true:

• The keystore has not been set
• The alias has not been set
• The password has not been set

createDNAFile

public java.io.File createDNAFile(java.io.File out,
                                  java.net.URL[] jarFiles)
                           throws DNAComposerException

Creates the DNA file.

Parameters:

out - The name for the new DNA file, cannot be null.

jarFiles - The list of all jarfiles that are stored in the DNA file. This list must match the names specified in the agent descriptor. Can be null (if there are no file objects), but cannot contain null objects.

Returns:

the DNA File that has been created.

Throws:

DNAComposerException - on failure The DNAComposerExceptoin will usually wrap a more specific exception, that can be approached using the DNAComposerException.getCause() method. This wrapped exception might be one of the following:
IOException if one of the following is true:

• The out file cannot be written
• Not all files named in the descriptor can be found in the jarfiles array.
• Not all files in the jarfiles array are named in the agent descriptor.
• The file pointing to the agent descriptor does not exist or does not contain a valid agent descriptor
• The keystore cannot be read

SecurityException if one of the following is true:

• The alias does not exist in the keystore
• The password is not correct
• The alias does not point to a private key
• Signing failed

IllegalStateException if one of the following is true:

• The keystore has not been set
• The alias has not been set
• The password has not been set
• The descriptor has not been set

updateDNAFile

public java.io.File updateDNAFile(java.io.File out,
                                  java.net.URL original,
                                  java.net.URL[] newJarFiles)
                           throws DNAComposerException

Updates the DNA file.

Parameters:

out - The name of the new DNA file, cannot be null.

original - The name of the DNA file that will be updated, cannot be null.

newJarFiles - An array of URLs pointing to the new jarfiles for the updated DNA file. If there are no new files (for example, only the certificate used for signing has been changed), this array can be null. The array cannot contain null objects.

Returns:

A File object that points to the created DNA file.

Throws:

DNAComposerException - on failure The DNAComposerExceptoin will usually wrap a more specific exception, that can be approached using the DNAComposerException.getCause() method. This wrapped exception might be one of the following:
IOException if one of the following is true:

• The out file cannot be written
• The original file cannot be read
• Not all files named in the descriptor can be found in the original or the newJarFiles array
• Not all files specified in the newJarFiles array are named in the descriptor.
• If a new agent descriptor has been set, the file pointing to the agent descriptor does not exist or does not contain a valid agent descriptor
• The keystore cannot be read

SecurityException if one of the following is true:

• The alias does not exist in the keystore
• The password is not correct
• The alias does not point to a private key
• Signing failed

IllegalStateException if one of the following is true:

• The keystore has not been set
• The alias has not been set
• The password has not been set