|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Netcode
public class Netcode
The NetCode bean can be used to encode or decode files or strings. UUEncode , MIME's Base64 Quoted-Printable , URL encoding formats, as well as secure hash functions such as MD5 and SHA1, are currently supported.
The encoding format
is specified by the Format
property. The binary data, or the name of the
file containing binary data, is specified by the DecodedData
property and
the encoded data or filename is specified by the EncodedData
property. The FileName
property may be used to override the default file names or to
specify a directory during uuencoding. After uudecoding, the FileName
property contains the fully specified file name of the decoded file.
Understanding Encoding/Decoding
Most of mail systems use only 7 bits to transmit messages. A binary file such as an archive or a non-plain text formatted file produced from a text processor should be first encoded in 7 bit code before email transfer.
Decoding is the inverse process: creation of the original file from the encoded data. Encoded data is often split over several files because of the size limit placed on the email message. Each message is preceded by information about this splitting, as well as the mail header. NetCode supports this case in both directions:
- During encoding setting the MaxFileSize
config setting to the maximum size of a message
body instructs NetCode to split the encoded data over several files. Multiple filenames
can be specified by using question marks "?" (See the EncodedData
property for more information).
- During decoding , the body messages can be saved in separate files named namexxx.ext
where xxx is a numeral starting at 000 and ext is ".uue", ".b16", or ".q_p" according to Format
. These multiple filenames should be given to EncodedData
.
Field Summary | |
---|---|
static int |
fmtBase64
|
static int |
fmtHex
|
static int |
fmtHMAC
|
static int |
fmtHTML
|
static int |
fmtJIS
|
static int |
fmtMD5Hash
|
static int |
fmtQP
|
static int |
fmtSHA1Hash
|
static int |
fmtURL
|
static int |
fmtUTF7
|
static int |
fmtUTF8
|
static int |
fmtUUEncode
|
static int |
fmtYEncode
|
Constructor Summary | |
---|---|
Netcode()
Creates an instance of Netcode Bean. |
|
Netcode(java.lang.String runtimeLicense)
Creates an instance of Netcode Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addNetcodeEventListener(NetcodeEventListener l)
|
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a configuration setting. |
void |
decode()
Decode string. |
void |
encode()
Encode the data. |
byte[] |
getDecodedData()
The decoded data. |
java.lang.String |
getDecodedFile()
The filename of the decoded data. |
byte[] |
getEncodedData()
The encoded data. |
java.lang.String |
getEncodedFile()
Filename of the encoded data. |
int |
getFileCnt()
Shows the number of encoded files the bean has read from or written into. |
java.lang.String |
getFileName()
The destination filename for the encoded data. |
int |
getFormat()
The type of encoding to be used. |
java.lang.String |
getMode()
The UNIX-style filemode when uuencoding / uudecoding. |
int |
getProgressStep()
Controls the granularity at which the Progress event is fired. |
boolean |
isOverwrite()
Controls whether created file(s) should overwrite already existing file(s). |
void |
removeNetcodeEventListener(NetcodeEventListener l)
|
void |
resetData()
Resets the values of all data and stream properties. |
void |
setDecodedData(byte[] decodedData)
The decoded data. |
void |
setDecodedFile(java.lang.String decodedFile)
The filename of the decoded data. |
void |
setEncodedData(byte[] encodedData)
The encoded data. |
void |
setEncodedFile(java.lang.String encodedFile)
Filename of the encoded data. |
void |
setFileName(java.lang.String fileName)
The destination filename for the encoded data. |
void |
setFormat(int format)
The type of encoding to be used. |
void |
setInputStream(java.io.InputStream inputStream)
The input stream of data. |
void |
setMode(java.lang.String mode)
The UNIX-style filemode when uuencoding / uudecoding. |
void |
setOutputStream(java.io.OutputStream outputStream)
The output stream of data. |
void |
setOverwrite(boolean overwrite)
Controls whether created file(s) should overwrite already existing file(s). |
void |
setProgressStep(int progressStep)
Controls the granularity at which the Progress event is fired. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
public static final int fmtUUEncode
public static final int fmtBase64
public static final int fmtQP
public static final int fmtURL
public static final int fmtJIS
public static final int fmtYEncode
public static final int fmtMD5Hash
public static final int fmtSHA1Hash
public static final int fmtHex
public static final int fmtHTML
public static final int fmtHMAC
public static final int fmtUTF8
public static final int fmtUTF7
Constructor Detail |
---|
public Netcode()
public Netcode(java.lang.String runtimeLicense)
Method Detail |
---|
public byte[] getDecodedData()
This property contains the decoded data. When uuencoding, the value of FileName
is the filename that will
be written in EncodedData
. If FileName
is empty, an error will
be returned.
public void setDecodedData(byte[] decodedData) throws IPWorksException
This property contains the decoded data. When uuencoding, the value of FileName
is the filename that will
be written in EncodedData
. If FileName
is empty, an error will
be returned.
IPWorksException
public java.lang.String getDecodedFile()
This property contains the filename of the decoded data. When uuencoding, the value of FileName
is the filename that will
be written in EncodedData
. If FileName
is empty, the value of
the DecodedFile
property is taken, if a valid file has been specified.
It is recommended that EncodedData
contains the full path and FileName
contains only the file name so that no problems occur while
uudecoding in a foreign system.
When decoding, the bean tries to generate the name for the created
file in the following order: DecodedFile
, FileName
, or when the
format is UUEncode, the specified filename in the uuencoded data itself.
If DecodedFile
or FileName
end with a backslash "\\" they are
interpreted as directories and the bean tries to create the given
filename in this directory. If this is the case, FileName
shows the
name of the file that was created.
public void setDecodedFile(java.lang.String decodedFile) throws IPWorksException
This property contains the filename of the decoded data. When uuencoding, the value of FileName
is the filename that will
be written in EncodedData
. If FileName
is empty, the value of
the DecodedFile
property is taken, if a valid file has been specified.
It is recommended that EncodedData
contains the full path and FileName
contains only the file name so that no problems occur while
uudecoding in a foreign system.
When decoding, the bean tries to generate the name for the created
file in the following order: DecodedFile
, FileName
, or when the
format is UUEncode, the specified filename in the uuencoded data itself.
If DecodedFile
or FileName
end with a backslash "\\" they are
interpreted as directories and the bean tries to create the given
filename in this directory. If this is the case, FileName
shows the
name of the file that was created.
IPWorksException
public byte[] getEncodedData()
This property contains the data that has either been encoded or is set to be decoded.
public void setEncodedData(byte[] encodedData) throws IPWorksException
This property contains the data that has either been encoded or is set to be decoded.
IPWorksException
public java.lang.String getEncodedFile()
This property contains the filename of the encoded data. If the encoded data is spread over several files, the filenames
are passed to EncodedFile
in the form name? .
Question marks "?" are expanded to numerals starting with 0.
The filenames should exist as path\\file000.ext and passed to EncodedFile
in the form name??? .
Question marks "?" are expanded to numerals starting with
000 (the number of zeros "0" equals that of question
marks "?").
The bean appends the extension ".uue",
".b16", or ".q_p"
depending on Format
immediately after the generated numbers. FileCnt
contains the number of encoded files.
See also the Format
property, and the MaxFileSize
config setting when working with multiple files.
public void setEncodedFile(java.lang.String encodedFile) throws IPWorksException
This property contains the filename of the encoded data. If the encoded data is spread over several files, the filenames
are passed to EncodedFile
in the form name? .
Question marks "?" are expanded to numerals starting with 0.
The filenames should exist as path\\file000.ext and passed to EncodedFile
in the form name??? .
Question marks "?" are expanded to numerals starting with
000 (the number of zeros "0" equals that of question
marks "?").
The bean appends the extension ".uue",
".b16", or ".q_p"
depending on Format
immediately after the generated numbers. FileCnt
contains the number of encoded files.
See also the Format
property, and the MaxFileSize
config setting when working with multiple files.
IPWorksException
public int getFileCnt()
This property shows the number of encoded files the bean has read from or written into. If the user specifies one or more questions marks "?" in EncodedFile
they will be expanded from 000 to FileCnt
- 1 (the number of question
marks "?" specifies the number of figures).
Please refer to EncodedFile
for filename conventions.
public java.lang.String getFileName()
This property contains the destination filename for the encoded data. When uuencoding, this property contains the filename that is specified in the uuencoded data.
When decoding, if the value of the property is not empty, it shows the bean where to write the decoded data. It can be either the filename or the directory where the file should be written. If a directory, it should end with a backslash "\\".
After a decode operation, this property contains the filename for the created file. If the file couldn't be created because of an illegal filename, examining this property might give a hint about the reason of the failure.
This property must be set to "" (empty string) after each decode operation since it contains the full specification of the file.
An error occurs if a uuencoding operation is initiated with an
empty FileName
.
If you want to first check the uuencoded filename before creating it on disk, you may assign an illegal directory name to this property (always use a closing backslash "\\" to denote it as directory), then trap the error and check the filename appended to this property.
public void setFileName(java.lang.String fileName) throws IPWorksException
This property contains the destination filename for the encoded data. When uuencoding, this property contains the filename that is specified in the uuencoded data.
When decoding, if the value of the property is not empty, it shows the bean where to write the decoded data. It can be either the filename or the directory where the file should be written. If a directory, it should end with a backslash "\\".
After a decode operation, this property contains the filename for the created file. If the file couldn't be created because of an illegal filename, examining this property might give a hint about the reason of the failure.
This property must be set to "" (empty string) after each decode operation since it contains the full specification of the file.
An error occurs if a uuencoding operation is initiated with an
empty FileName
.
If you want to first check the uuencoded filename before creating it on disk, you may assign an illegal directory name to this property (always use a closing backslash "\\" to denote it as directory), then trap the error and check the filename appended to this property.
IPWorksException
public int getFormat()
This property contains the type of encoding to be used. The following are the possible values for this property, and the corresponding descriptions:
HMACKey
. To set the hash algorithm to use
to create the MAC, use HMACAlgorithm
.
public void setFormat(int format) throws IPWorksException
This property contains the type of encoding to be used. The following are the possible values for this property, and the corresponding descriptions:
HMACKey
. To set the hash algorithm to use
to create the MAC, use HMACAlgorithm
.
IPWorksException
public java.lang.String getMode()
This property contains the UNIX-style filemode when uuencoding / uudecoding. The filemode is usually an octal number such as 755 or 600 which gives the protections of that file. If the file to uudecode is correctly read then this property contains the protection string given in the uuencoded data.
Given for compatibility with other systems.
Used only when Format
is fmtUUE.
public void setMode(java.lang.String mode) throws IPWorksException
This property contains the UNIX-style filemode when uuencoding / uudecoding. The filemode is usually an octal number such as 755 or 600 which gives the protections of that file. If the file to uudecode is correctly read then this property contains the protection string given in the uuencoded data.
Given for compatibility with other systems.
Used only when Format
is fmtUUE.
IPWorksException
public boolean isOverwrite()
This property controls whether created file(s) should overwrite already existing file(s). Note that more than one file may be created during uuencoding.
public void setOverwrite(boolean overwrite) throws IPWorksException
This property controls whether created file(s) should overwrite already existing file(s). Note that more than one file may be created during uuencoding.
IPWorksException
public int getProgressStep()
Progress
event is fired. Values 0-100.
This property controls the granularity at which the Progress
event is fired. Values 0-100. If this property is not 0, the Progress
event will be fired
when 0%, n* ProgressStep
and 100% of input
data is read.
If this property is 0, the Progress
event is disabled.
public void setProgressStep(int progressStep) throws IPWorksException
Progress
event is fired. Values 0-100.
This property controls the granularity at which the Progress
event is fired. Values 0-100. If this property is not 0, the Progress
event will be fired
when 0%, n* ProgressStep
and 100% of input
data is read.
If this property is 0, the Progress
event is disabled.
IPWorksException
public java.lang.String config(java.lang.String configurationString) throws IPWorksException
Config
is a generic method available in every bean.
It is used to set and retrieve configuration settings
for the
bean.
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.
The bean accepts one or more of the following configuration settings .
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
Base64LineBreak
config to false will cause these line breaks to be omitted from the Base64 encoded content. The default value is true.HMACAlgorithm
is used to tell the bean which hashing algorithm to use to generate the Hash-based Message Authentication Code (HMAC). HMACAlgorithm can be either "SHA1" (Secure Hash Algorithm 1) or "MD5" (Message Digest 5). You may truncate the hash output by specifying the desired number of bits. For instance "SHA1-96" and "MD5-96" are acceptable.Format
fmtHMAC , it may be necessary to supply the bean with a key to use when generating the Hash-based Message Authentication Code (HMAC). This key is incorporated into the hashing process to add entropy to the resulting hash code, making the plaintext harder to guess and increasing the message security. You may also set this to a hex value. For instance 0xAAAAAA is acceptable.MaxFileSize
makes the bean split the encoded data
into several files. FileCnt
will contain the number of files created. Please refer
to EncodedFile
for filename conventions.The default value for this setting is 0 (no limit).
IMPORTANT: if a non-zero value is assigned to MaxFileSize
then a multiple filename should also
be assigned to EncodedFile
(end with question marks "?") so that the bean can expand
the filenames.
Please refer to the Error Messages section for a complete list of possible errors.
Format
is set to fmtUTF7 , UseModifiedUTF7
is used to tell the bean whether or not to use a modified version of UTF-7 for IMAP mailbox naming. The default value is false.
IPWorksException
public void decode() throws IPWorksException
This method decodes according to the Format
type. The bean will decode the data in the
input stream if SetInputStream
has been set to a valid stream. If this stream
is null, the bean will then try to read the data from the file set by the EncodedFile
property. If no valid file has been specified, the bean will
use the EncodedData
property.
The resulting decoded data is written to the output stream if one has been set. If
not, the component will attempt to write the decoded data to the DecodedFile
.
If no file was specified, the decoded data may be retrieved through the DecodedData
property.
When UUDecoding the created filename will by default be the one specified in the
uuencoded data. The FileName
property will contain this value. DecodedFile
or, if DecodedFile
is empty, FileName
can be used to override this value.
When YDecoding, the source path and filename is specified in EncodedFile
and
the destination path and filename in DecodedFile
. If the encoded data indicates
the name of the original file before decoding, this value will be stored in the FileName
property. To decode a multi-part message, all parts must be concatenated
in order in the source file.
IPWorksException
public void encode() throws IPWorksException
This method encodes the data according to the Format
type. The bean will encode the data in the
input stream if SetInputStream
has been set to a valid stream. If this stream
is null, the bean will then try to read the data from the file set by the DecodedFile
property. If no valid file has been specified, the bean will
use the DecodedData
property.
The resulting encoded data is written to the output stream if one has been set. If
not, the component will attempt to write the encoded data to the EncodedFile
.
If no file was specified, the encoded data may be retrieved through the EncodedData
property.
The data is considered binary while uuencoding and Base64 Format
s, and Text during
QuotedPrintable ones.
When uuencoding or yencoding the filename encoded into the data is taken from the FileName
property.
The current version of NetCode creates no message headers. If a MIME standard encoding is used such as Base64 Encoding or Quoted Printable Encoding the user should fill the header values appropriately.
If EncodedFile
and MaxFileSize
is set and the encoded data takes
more space than MaxFileSize
, the data is split over several files.
In this case, the user can specify more than one filename by passing them to EncodedFile
in the form name? . The filenames should exist as path\\file0.ext , path\\file1.ext ... Question marks "?" are
expanded to numerals starting with 0.
NetCode appends the extension ".uue", ".b16", or ".q_p" (depending
on the value of Format
) to the filename.
IPWorksException
public void resetData() throws IPWorksException
This method resets the values of all data and stream properties. It is an easy
way to reset the bean's properties before another call to Encode
or Decode
. The input and output streams and the data and file properties
will all be reset.
IPWorksException
public void setInputStream(java.io.InputStream inputStream) throws IPWorksException
Use this method to set the input stream of data for the component to
read from. If Encode
or Decode
is called, and this is
not null, the data will be read from this stream when the
specified action occurs. You may reset this by calling ResetData
.
IPWorksException
public void setOutputStream(java.io.OutputStream outputStream) throws IPWorksException
Use this method to set the output stream of data for the component to
write. If Encode
or Decode
is called, and this is
not null, the data will be written to this stream when the
specified action occurs. You may reset this by calling ResetData
.
IPWorksException
public void addNetcodeEventListener(NetcodeEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeNetcodeEventListener(NetcodeEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |