ArchiveAccessor V 1.0


JarFileAccessor Bean


Table Of Contents


toc

Introduction

This part of the document covers the following information:


up Audience

This document describes the JarFileAccessor Bean. It is intended for application assemblers who can use the component in a visual builder as well as in manual programming. It is assumed that they are already familiar with JavaBeans. If terms like property, event, method, introspection, or serialization are unfamiliar to them, they may refer to the JavaBeans documentation or take the JavaBeans tutorial.


up How to Use This Guide

Guide Conventions

See the Guide Conventions part from the Introduction section of the ArchiveAccessor Bean Suite User's Guide.


up Guide Organization

Introduction - introduces the user to the JarFileAccessor Bean. Provides information like intended audience, guide conventions, guide organization, and copyrights.

Bean at a Glance - gives a brief overview of the bean. Also provides information on commonly used methods, events, and properties.

Bean Description - explains the bean in detail. Provides information on dependencies, security, customization if any, etc.

Summaries - summarizes  properties, methods, and events of the bean.

Reference to Properties - links to respective properties.

Reference to Methods - links to respective methods.

Reference to Events - links to respective events.

Support Classes - provides information on support classes.

See Also - links to related topics.


up Copyrights And Trademarks

Copyright © 1998 IBM Corp.

All rights reserved.

IBM and VisualAge are trademarks of International Business Machines in the United States and/or other countries.

* Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

Copyright © 1997 The Open Group

Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both the copyright notice and this permission notice appear in supporting documentation, and that the name of ("TOG") or The Open Group not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.

THE OPEN GROUP DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL TOG BE LIABLE FOR ANY SPECIAL, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN ACTION OF CONTRACT, NEGLIGENCE, OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

The Open Group Research Institute MoaJar (unencumbered) 3/20/1997


toc

Bean at a Glance

Provides the following information:


Bean Overview

public JarFileAccessor
extends PackagedFileBucketAccessor

The JarFileAccessor class implements the bean that works with a Jar file.


up Commonly Used Methods, Events, and Properties

Key Properties

Commonly Used Methods

Commonly Used Events


toc

Bean Description

The Bean Description portion of this document provides the following information:


up Functional Overview

The JarFileAccessor Bean is a non-visual component that gives an application assembler an easy access to a Jar file.

The JarFileAccessor Bean must

Application assemblers (programmers) can perform any of the above mentioned operations by calling corresponding APIs.


up Introspection

JarFileAccessorBeanInfo provides information on properties, events, and methods.


up Customization

An application assembler can customize the following properties of the JarFileAccessor Bean:


toc

Summaries


Property Summary

Name Datatype [Constrained | Bound|Indexed]
[expert]
Description

Default
value

Access
type

automaticSave

boolean bound,
expert
indicates whether a file bucket is automatically saved or not when being closed true (w/r)

createManifest

boolean bound creates or does not create the manifest true (w/r)

defaultDirectory

String bound default directory for getting  files specified with relative names to be saved in a  packaged archive file user's current working directory (w/r)

includeManifest

boolean bound includes or does not include manifest information from the manifest file false (w/r)

archiveName

String bound archive file name "untitled.jar" (w/r)
useCompression boolean bound switch for using a Zip compression true (w/r)

up Method Summary

Instantiation JarFileAccessor()
JarFileAccessor(String)
accessing properties getDefaultDirectory()
getArchiveName()
isAutomaticSave()
isCreateManifest()
isIncludeManifest()
isUseCompression()
setAutomaticSave(boolean)
setCreateManifest(boolean)
setDefaultDirectory(String)
setIncludeManifest(boolean)
setArchiveName(String)
setUseCompression(boolean)
control add()
add(String)
clear()
clone()
close()
contents()
contentsAsEnumeration()
create()
create(String)
exists(String)
extract()
extract(String)
open(String)
remove(String)
rename(String, String)
replace(String)
save()
saveAs(String)
adding/removing listeners addPropertyChangeListener(PropertyChangeListener)
removePropertyChangeListener(PropertyChangeListener)

 


up Event Summary

As Source:

EventListener Interfaces -

                        PropertyChangeListener

EventListener Objects -

                        PropertyChangeEvent


toc

Reference to Properties

archiveName [bound] - archive file name
To customize the bean to set this property, one should utilize either system-independent file separator ('/') or double back slash.
If an archive name is not defined, it is saved with default name "untitled.jar". If an archive name is defined as "blank" or "empty", then it is saved with name " .jar". Such a name from the viewpoint of the system is quite all right.
Type: String
Default value: "untitled.jar"
Get: getArchiveName()
Set: setArchiveName(String)
 
automaticSave [bound, expert] - indicates whether a file bucket is automatically saved or not when being closed
Type: boolean
Default value: true
Get :isAutomaticSave()
Set: setAutomaticSave(boolean)
 
createManifest [bound] - creates or does not create the manifest
Type: boolean
Default value: true
Get: isCreateManifest()
Set: setCreateManifest(boolean)
 
defaultDirectory [bound] - default directory for getting files specified with relative names to be saved in a packaged archive file. This directory is also used for extracting files specified with relative names to put them into the directory. To customize the bean to set this property, one should utilize either system-independent file separator ('/') or double back slash.
Type: String
Default value: user's current working directory
Get: getDefaultDirectory()
Set: setDefaultDirectory(String)
 
includeManifest [bound] - switch to include manifest information from the manifest file
Type: boolean
Default value: false
Get: isIncludeManifest()
Set: setIncludeManifest(boolean)
 
useCompression [bound] - switch to use a Zip compression
Type: boolean
Default value: true
Get: isUseCompression()
Set: setUseCompression(boolean)  

toc

Reference to Methods

add
public void add() throws JarFileAccessorException
Adds files to a Jar file. Files to be added are located in a default directory. All files are stored in a Jar file on relative paths. If added files exist already in an archive,  they are replaced. When the automaticSave property is set to true, the archive is saved on the disk.
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- default directory is not set,
- default directory does not exist,
- I/O error occurs.
Overrides:
add in class PackagedFileBucketAccessor
 
add
public void add(String aName) throws JarFileAccessorException
Adds a named file or contents of a directory to a Jar file. A file to be added is specified by its name. If a directory name is specified as a parameter of this method, all the files of this directory (including subdirectories) are added to the Jar file. The file (or files) is stored in the Jar file on a relative path (or paths). A parameter, specifying a file or directory to add, should unambiguously determine a file or directory place on the disk. If an incomplete file or directory name is given,  i.e. its name contains a relative path, searching for the file starts from the Default Directory. Otherwise, a complete file or directory name should be set, i.e. it should contain an absolute path. If an added file (or files) already exists in an archive, it is replaced.  When the automaticSave property is set to true, the archive is saved on the disk.
Parameters:
aName - file name to be added to a Jar file
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- file name or directory is null or empty,
- I/O error occurs.
Overrides:
add in class FileBucketAccessor
 
clear
public void clear() throws JarFileAccessorException
Removes all files from a Jar file and all file entries from the manifest file. If the createManifest property is set on, the empty manifest file would not be removed from the jar archive. When the automaticSave property is set to true, the archive is saved on the disk.
Throws: JarFileAccessorException
May be thrown when a Jar file is not opened
Overrides:
clear in class FileBucketAccessor
 
clone
public synchronized Object clone()
Clones a Jar file object.
Overrides:
clone in class Object
 
close
public void close() throws JarFileAccessorException
Closes a Jar file.
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- Jar file name is not set,
- writing to a Jar file,
- processing contents of a Jar file.
Overrides:
close in class FileBucketAccessor
 
contents
public String[] contents() throws JarFileAccessorException
Gets files list of a Jar file.
Returns:
  array of file names
Throws: JarFileAccessorException
May be thrown when a Jar file is not opened.
Overrides:
contents in class FileBucketAccessor
 
contentsAsEnumeration
public Enumeration contentsAsEnumeration() throws JarFileAccessorException
Gets files list of a Jar file as enumeration.
Returns:
enumeration of file names
Throws: JarFileAccessorException
May be thrown when a Jar file is not opened
Overrides:
contentsAsEnumeration in class FileBucketAccessor
 
create
public void create() throws JarFileAccessorException
Creates a new Jar file from files that are located in a default directory. All files are stored in the Jar file on relative pathes. When the automaticSave property is set to true, the archive is saved on the disk.
Throws: JarFileAccessorException
May be thrown when
- current  archive is not closed,
- archive name is not set,
- writing to an archive,
- processing contents of an archive;
- I/O error occurs.
Overrides:
create in class FileBucketAccessor
 
create
public abstract void create(String aFileName) throws JarFileAccessorException
Creates a new Jar file from an existed one. All files are stored in the Jar file on relative paths. When the automaticSave property is set to true, the archive is saved on disk.
Parameters:
aFileName - existing Jar file name
Throws: JarFileAccessorException
May be thrown when
- archive name is not set,
- reading from an archive,
- writing to an archive,
- processing contents of an archive.
Overrides:
create in class FileBucketAccessor
 
exists
public abstract boolean exists(String aFileName) throws JarFileAccessorException
Checks if a specified file name is present in a Jar file.
Parameters:
aFileName - file name to be checked in a Jar file
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- file name is null or empty.
Overrides:
exists in class FileBucketAccessor
 
extract
public void extract() throws JarFileAccessorException
Extracts all files from a Jar file. The method extracts all files from a Jar file and saves them on the disk in a default directory.
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- default directory is not set,
- default directory does not exist
- writing to the disk.
Overrides:
extract in class PackagedFileBucketAccessor
 
extract
public void extract(String aFileName) throws JarFileAccessorException
Extracts a named file from a Jar file. The method extracts one file from a Jar file and saves it on the disk in a default directory.
Parameters:
aFileName - file name to be extracted from a Jar file
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- default directory is not set,
- file name is null or empty,
- specified file does not exist in an archive yet,
- writing to the disk.
Overrides:
extract in class PackagedFileBucketAccessor
 
getArchiveName
public String getArchiveName()
Gets a file bucket name.
 
JarFileAccessor
public JarFileAccessor()
Creates an instance of the class.
 
JarFileAccessor
public JarFileAccessor(String aFileName) throws JarFileAccessorException
Creates an instance of the class with contents of a Jar file. The Jar file must exist.
Parameters:
aFileName - existing Jar file name
Throws: JarFileAccessorException
May be thrown when
- Jar file name is null or does not exist,
- reading from a Jar file,
- processing contents of a Jar file.
 
isCreateManifest
public boolean isCreateManifest()
Returns a switch for creating the manifest. If a returned value is equal to true, the manifest file is created automatically in an archive. If it is equal to false, the manifest file is not created automatically.
Returns:
switch for creating the manifest
 
isIncludeManifest
public boolean isIncludeManifest()
Returns a switch of included manifest information from the manifest file.  If a returned value is equal to true, the manifest file to be placed in an archive should be searched for in a defaultDirectory on the disk. The file should be named manifest.mf and placed in a directory named META-INF. The META-INF directory, in its turn, should exist in a directory specified as defaultDirectory. If the parameter is equal to false, the manifest file will not be searched for on the disk. To create a correct Jar file, the createManifest property equal to true should be used. The default includeManifest property is equal to false.
Returns:
true if the manifest is created from the manifest file; otherwise, false
 
isUseCompression
public boolean isUseCompression()
Returns a switch for using a Zip compression. If a returned value is equal to true, the compression is used; if it is equal to false, it is not used.
Returns:
switch for using a Zip compression
 
open
public void open(String aFileName) throws JarFileAccessorException
Opens a new Jar file. The file must exist. A parameter specifying a file to open should unambiguously determine a file place on the disk.  If an incomplete file name is given, i.e. the file name contains a relative path, we start searching  for the file from a current system directory. Otherwise, a complete file name should be set, i.e. it should contain an absolute path.
Parameters:
aFileName - existing Jar file name
Throws: JarFileAccessorException
May be thrown when
- Jar file name is null or empty,
- reading from a Jar file,
- processing contents of a Jar file,
- opening a new Jar file, but a current file is not saved,
- Jar file does not exist.
Overrides:
open in class FileBucketAccessor
 
setArchiveName
public void setArchiveName(String aName) throws IllegalArgumentException
Sets a Jar file name. Fires the PropertyChange event if the Jar file name is actually changing.
Parameters:
aName - Jar file name
Throws: IllegalArgumentException
May be thrown when a name is null.
Overrides:
setArchiveName in class FileBucketAccessor
 
setCreateManifest
public void setCreateManifest(boolean aSwitch)
Turns on/off creation of the manifest. Fires the PropertyChange event if an aSwitch property value of the manifest creation is actually changing. If a parameter  is equal to true, the manifest file is created automatically in an archive. If the parameter is equal to false, the manifest file is not created automatically. A default parameter is equal to true.
Parameters:
aSwitch -  switch to create the manifest
 
setIncludeManifest
public void setIncludeManifest(boolean aSwitch)
Includes or does not include manifest information of the manifest file from the disk. If a parameter is equal to true, the manifest file to be placed in an archive should be searched for in a defaultDirectory on the disk. The file should be named manifest.mf and placed in a directory named META-INF. The META-INF directory, in its turn, should exist in a directory specified as defaultDirectory.  If the parameter is equal to false, the file manifest will not be searched for on the disk. In this case,  to create a correct Jar file, the ñreateManifest property  equal to true should be used.
The default includeManifest property is equal to false.
Fires the PropertyChange event if an aSwitch property value of included information from the manifest file is actually changing.
Parameters:
aSwitch - switch to create the manifest
 
setUseCompression
public void setUseCompression(boolean aSwitch)
Turns on/off the use of a Zip compression. Fires the PropertyChange event if an aSwitch property value of the Zip compression is actually changing. If an argument is equal to true, the compression algorithm is used while saving an archive on the disk. If aSwitch is equal to false, an archive can be saved without the compression algorithm.
Parameters:
aSwitch -  switch for using a Zip compression
 
rename
public void rename(String anOldName
                   String aNewName)throws JarFileAccessorException
Renames a file in a Jar file. A file to be renamed is specified by its name. When the automaticSave property is set to true, an archive will be saved on the disk.
Parameters:
anOldName - file name to be renamed in a Jar file
aNewName - new name of a file
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- specified  file does not exist in an archive,
- any of the two arguments is null or empty.
Overrides:
rename in class FileBucketAccessor
 
remove
public void remove(String aFileName) throws JarFileAccessorException
Removes a named file and its manifest entry from a Jar file. A file to be removed is specified by its name. When the automaticSave property is set to true, an archive will be saved on the disk.
Parameters:
aFileName - file name to be removed from a Jar file
Throws: JarFileAccessorException
May be thrown when
- file name is null or empty,
- specified file does not exist in an archive,
- Jar file is not opened.
Overrides:
remove in class FileBucketAccessor
 
replace
public void replace(String aFileName) throws JarFileAccessorException
Replaces a named file in an archive by another one with the same name.
For example, there is a file with name com/ibm/filestore/JarFile.java in an archive. To replace it in a default directory, there should be a file with the same name and signed to relative path com/ibm/filestore.
When the automaticSave property is set to true, the archive will be saved on the disk.
Parameters:
aFileName - file name to be replaced in a Jar file
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- file name is null or empty,
- specified  file does not exist in an archive,
- specified  file does not exist on the disk,
- reading a Jar file.
Overrides:
replace in class FileBucketAccessor
 
save
public void save() throws JarFileAccessorException
Saves a Jar file on the disk. The Jar file name must be set.
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- Jar file name is not set,
- writing to a Jar file,
- processing contents of a Jar file.
Overrides:
save in class FileBucketAccessor
 
saveAs
public void saveAs(String aFileName) throws JarFileAccessorException
Saves a Jar file on the disk under another name. A parameter specifying an archive name to save should unambiguously determine an archive place on the disk. If an incomplete archive name is given,  i.e. the name contains a relative path, the archive should be saved in a current system directory. Otherwise, a complete archive name should be set, i.e. it should contain an absolute path.
Parameters:
aFileName - Jar file name
Throws: JarFileAccessorException
May be thrown when
- Jar file is not opened,
- Jar file name is not set
- writing to a Jar file,
- processing contents of a Jar file.
Overrides:
saveAs in class FileBucketAccessor

toc

Reference to Events

The JarFileAccessor Bean fires the PropertyChange event if one of the bound properties is actually changing. Listeners get registered for post-notifications of bound properties with addPropertyChangeListener().

As Source :

EventListener Interfaces -

                      PropertyChangeListener

EventObject -

                      PropertyChangeEvent


toc

Support Classes

  1. Base64
  2. FilenameFilter
  3. Folder
  4. FolderBucket
  5. JarBucket
  6. JarFile
  7. Manifest
  8. ManifestSection
  9. Matching
  10. Reads
  11. ZipBucket
  12. ZipFile
  13. FileBucketAccessor
  14. PackagedFileBucketAccessor
  15. FileBucketAccessorException
  16. JarFileAccessorException

toc

See Also

Go back to

previous

ArchiveAccessor Bean Suite Documentation Index

Last Modified : 08/28/98