/n software Connectors for MuleSoft
Version 22.0 [Build 8376]

Zip Modules

Properties   Config Settings  

The Zip transformer implements a PKZip-compatible Zip compressor and decompressor.

Remarks

The Zip module is used for compressing and decompressing messages. The module uses the Deflate algorithm specified in RFC 1951 for compression, and produces and reads output compatible with PKZip, WinZip, etc.

Zip Compressor Module

The Zip Compress operation creates an archive based on the specified files. The Zip Compressor relies on a Map of filenames to file content as input, e.g. Map<Filename,InputStream>. The elements will be compressed into a Binary zip archive in the output payload.

Compression strength is regulated by the CompressionLevel property. You may also control encryption behavior by setting the Password and EncryptionAlgorithm properties on this module.

Archive Example

In the body of your flow, configure the File List connector to list the contents of the target directory.

Behind the File List connector, transform the output of File List so it can be correctly interpreted by the Zip Compressor. The easiest way to do this is with the Set Payload connector. Paste in the following DataWeave code to properly format the File List output so it can be used by the Compressor. output application/java --- (0 to sizeOf(payload) - 1) as Array reduce (index, acc={}) -> acc ++ { (payload[index].attributes.fileName): payload[index].payload} Finally, add the Zip Compressor. That is all that is required to begin compressing data. Behind the Zip Compressor you can write the new archive to disk with a File Write connector or perform further processing.

Zip Decompressor Module

The Zip Decompress operation extracts the inner files of the input archive. The Zip Decompressor relies on a Binary archive in the incoming message payload as input. The elements in the archive will be decompressed into a Map of filenames to decompressed content as key:value pairs in the output payload, e.g. Map<Filename,OutputStream>. The Map elements can be accessed with a For Each scope.

The Password property must be set in order to extract files which have been encrypted. You may also use the ExcludedFiles property to regulate which files are to be extracted from the archive.

Extract Example

First, create an event source such as a Scheduler endpoint to start the flow. Then in the body of your flow, drag an instance of the File Read connector into the project and configure it to read in a particular archive file.

Add an instance of the Zip Decompressor behind the File Read connector. There is no need to transform the output data of the File Read connector before passing it to the Decompressor.

Behind the Decompressor add a For Each Scope and set the collection property to payload. This will configure the For Each Scope to iterate over the output of the Decompressor. Then inside the For Each Scope, the filename and decompressed file data are available as key:value pairs.

As an example, to write the file to disk you can use a File Write connector inside the For Each Scope and MuleSoft pluck function. Set the Path property of the File Write connector to:

output application/json --- "c:/temp/mule/output/" ++ (payload pluck $$)[0]

Set the Content property of the File Write connector to:

output application/java --- ( payload pluck $ )[0]

That is all that is required to configure the File Write connector to write the inner file to disk.

Compressor Property List


The following is the full list of the properties of the compressor Module with short descriptions. Click on the links for further details.

CompressionLevelThe compression level to use.
EncryptionAlgorithmThe algorithm used to encrypt a MuleSoft when written to the archive.
FileModifiedTimeThe modified time of the compressed files.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the transformer.
PasswordA password for the zip file.
RuntimeLicenseSpecifies the component runtime license key.
TempPathA temporary directory where uncompressed and compressed data can be stored.
ZipCommentThe comment for the entire zip file.

Decompressor Property List


The following is the full list of the properties of the decompressor Module with short descriptions. Click on the links for further details.

FileMaskSpecifies which files the component should include when extracting.
LogFileThe file to write logging information to at runtime.
LogModeWhat information gets logged during component execution.
LogTypeHow information gets logged during component execution.
OtherDefines a set of configuration settings to be used by the transformer.
PasswordA password for the zip file.
RuntimeLicenseSpecifies the component runtime license key.
TempPathA temporary directory where uncompressed and compressed data can be stored.

Config Settings


The following is a list of config settings for the Module with short descriptions. Click on the links for further details.

AppendSpecifies whether to append files.
ArchiveFileThe location of the archive file on disk.
CompressionMethodUsed to set the method of compression.
ExcludedFilesA list of files to exclude.
ExtractToPath.
IncludeFilesSpecifies local files to include in the archive.
OverwriteFilesWhether or not to overwrite files.
PlainPasswordAllows you to specify a password stored in plaintext.
PreserveModifiedTimeWhether or not to preserve the original modified time on extracted files.

CompressionLevel Property (Zip Module)

The compression level to use.

Data Type

Integer

Default Value

4

Remarks

This property specifies the level of compression to be used, between 0 and 6. Higher values will cause the module to compress better; lower values will cause the module to compress faster. A value of 0 will store the file without compression.

This property is not available in the Decompressor/Decoder.

EncryptionAlgorithm Property (Zip Module)

The algorithm used to encrypt a MuleSoft when written to the archive.

Data Type

Enumeration

Possible Values

Default (0)
AESWeak (1)
AESStrong (2)
AESMaximum (3)

Default Value

0

Remarks

The algorithm used to encrypt each file written to the archive.

Note that the Password property must be set in order for the module to encrypt files. By default the module will use standard zip encryption if Password is set, and will not encrypt data otherwise.

The module supports the use of AES, the Advanced Encryption Standard, as well as standard Zip encryption. The default encryption algorithm is the algorithm introduced in version 2.0 of the Zip specification, and is compatible with virtually all other zip utilities. However, this algorithm is considered weak and should not be used to protect sensitive data.

AES is a U.S. government standard cleared to protect even the most sensitive data. The file format used to create AES-encrypted files is designed to be compatible with WinZip 9.0. AES-encrypted files created by the module may or may not be compatible with other Zip utilities.

The module supports the use of AES with key lengths of 128, 192, or 256 bits. Note that even with the weakest (128-bit) keys, AES is much more secure than standard Zip encryption.

If you use strong or maximum AES encryption, the module will generate a unique salt value and cryptographic key for each file encrypted. If you use weak encryption the connector will use the same salt for each file in the archive. If you are encrypting a large number of files, this will have a substantial effect on performance.

If using AES encryption it is important to choose a good Password. For 128-bit keys it is recommended that your password be 32 characters long, and for 256-bit keys, 64 characters.

Important: Note that AES encryption only encrypts the contents of encrypted files within the Zip archive; it does not prevent an attacker from reading the names of files in the archive, or from adding or deleting files to or from the archive. To prevent this consider first storing your files in an unencrypted zip file, and then storing this zipped file in another, AES-encrypted zip file.

Property values:

eaDefault0
eaAESWeak1
eaAESStrong2
etAESMaximum3

This property is not available in the Decompressor/Decoder.

FileMask Property (Zip Module)

Specifies which files the component should include when extracting.

Data Type

String

Default Value

"*"

Remarks

FileMask may be used to specify which files will be extracted from the zip archive during decompression. All other files will be discarded.

The value should be a pipe ("|") -delimited sequence of one or more filenames. The filenames should be specified with paths if necessary.

Filenames may include the wildcards '?', '*', and '< .. >'. '?' will match any single character, and '*' will match an arbitrary sequence of characters. '< .. >' may be used to match any of the characters inside, or a range, such as '<a-z>'.

During extraction, FileMask may be set to one or more filenames or directory names. Files may be specified with or without a path, and with or without wildcards.

The ExcludedFiles property may be used to limit the files to be extracted.

This property is not available in the Compressor/Encoder.

FileModifiedTime Property (Zip Module)

The modified time of the compressed files.

Data Type

String

Default Value

""

Remarks

This property optionally specifies the modified time of the compressed file. The format may be any LocalDateTime format.

This property is not available in the Decompressor/Decoder.

LogFile Property (Zip Module)

The file to write logging information to at runtime.

Data Type

String

Default Value

""

Remarks

To write logging information to a file instead of using the connector's logging API, set this property to a valid file on disk and set the LogType property to "File".

LogMode Property (Zip Module)

What information gets logged during component execution.

Data Type

Enumeration

Possible Values

Verbose (0)
Info (1)
Warning (2)
Error (3)
Fatal (4)

Default Value

3

Remarks

This property controls what information the connector logs. The possible values have the following affect on the connector's behavior:

VerboseThe connector will report all information regarding the transport.
InfoThe connector will report all major operations, as well as all warnings and errors.
WarningThe connector will report any conditions that could result in unpredictable behavior as well as errors.
ErrorThe connector will report all errors that prevent normal operations from completing.
FatalThe connector will report only serious errors that cause the connector to completely stop functioning.

LogType Property (Zip Module)

How information gets logged during component execution.

Data Type

Enumeration

Possible Values

None (0)
Console (1)
File (2)

Default Value

1

Remarks

This property controls where the connector will log the information. The possible values have the following affect on the connector's behavior:

NoneThe connector will not report any logging information.
ConsoleThe connector will report all logging information to the console.
FileThe connector will report all logging information to a file. The desired file must be specified in the LogFile when this type has been selected.

Other Property (Zip Module)

Defines a set of configuration settings to be used by the transformer.

Data Type

String

Default Value

""

Remarks

The module accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the module, access to these internal properties is provided through the Other property.

The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line. For example: configname1=value1 configname2=value2

Password Property (Zip Module)

A password for the zip file.

Data Type

Password

Default Value

""

Remarks

This property specifies the case-sensitive password used to encrypt or decrypt the archive file. If set to an empty string, no password is used.

RuntimeLicense Property (Zip Module)

Specifies the component runtime license key.

Data Type

String

Default Value

""

Remarks

You can use the RuntimeLicense property to set the runtime key for the connector license.

TempPath Property (Zip Module)

A temporary directory where uncompressed and compressed data can be stored.

Data Type

String

Default Value

""

Remarks

This property indicates a temporary directory where the module can store any data before the module processes it. If TempPath is empty, the module will receive all data to memory. If set, the module will generate and write all inbound data to a temporary file in the specified directory.

Once the file is submitted, the module will handle closing the file stream and deleting the temporary file. However, if the module is shut down during a transfer some temporary files may be left in the directory. To ensure optimal performance, server administrators should check the directory regularly and remove old or extraneous files. Note: by default, this property is empty and the module will use memory streams to store all inbound data before submitting it. It is recommended that you use a temporary directory when downloading large batches or batches containing large files to alleviate potential increased memory requirements.

ZipComment Property (Zip Module)

The comment for the entire zip file.

Data Type

String

Default Value

""

Remarks

Specifies a global comment for the zip file. Set this property to include a comment in each zipped file the module creates.

This property is not available in the Decompressor/Decoder.

Config Settings (Zip Module)

The connector 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 connector, access to these internal properties is provided through the Other property.

Zip Config Settings

Append:   Specifies whether to append files.

If set to True the connector will append files to the archive specified by ArchiveFile. ArchiveFile must be set to the location of an archive on disk. If the file does not exist it will be automatically created. The default value is False.

Note: TempPath is not applicable when this is set to True.

ArchiveFile:   The location of the archive file on disk.

This setting specifies the location of an archive file on disk. This is only applicable when Append is set to True.

CompressionMethod:   Used to set the method of compression.

This is used to specify different compression methods. By default the connector uses the Deflate compression method (a value of 0). Supported values are:

Value Method
0 Deflate (default)
1 PPMd
2 bzip2

ExcludedFiles:   A list of files to exclude.

This property specifies files that should be excluded when compressing or extracting a file. When either compression or extraction occurs, each file will be compared to ExcludedFiles, and each file that matches will be excluded.

This property may be set to one or more file names. These file names may be specified with or without a path, and with or without wildcards. If a path is specified, files in the indicated extraction directory will be excluded. If no path is specified but wildcards are, matching files in all directories will be excluded. If a single file name without a path is specified, it must correspond exactly to the appropriate value of a valid file name.

Directories should end with a slash ("/" or "\", as appropriate.) If a directory is specified, all files and subdirectories in the specified directory will be excluded during extraction.

A pipe character ("|") should be used to separate multiple file or directory names.

If the property is set to the empty string, no files will be excluded.

ExtractToPath:   .

A base path to decompress to. Setting this property to a nonempty string will cause all decompressed files to be written to the specified path. If pathnames are given in the values of decompressed names, they will be regarded as relative to ExtractToPath.

If the specified directory does not exist, it will be created when extraction is done.

ExtractToPath should always be specified in the format native to the host operating system, and with a trailing slash or backslash. If the path is specified otherwise, it will be immediately converted and stored in the converted format. For example, "/temp" would be immediately converted to "\temp\" on a Windows system.

IncludeFiles:   Specifies local files to include in the archive.

When specified the connector will include the specified files on disk in the archive and the content of the Mule message will not be included.

The value should be a pipe ("|") -delimited sequence of one or more filenames. The filenames should be specified with paths if necessary, so that the files may be found on the local file system.

Filenames may include the wildcards '?', '*', and '< .. >'. '?' will match any single character, and '*' will match an arbitrary sequence of characters. '< .. >' may be used to match any of the characters inside, or a range, such as '<a-z>'.

If wildcards are specified, the file system will be scanned and all files matching the specified mask will be added to the list of files to compress.

OverwriteFiles:   Whether or not to overwrite files.

If this setting is set to true, existing files will be overwritten when decompressing. When extracting, each file specified by the FileMask will be checked for existence. If a file exists, the files will be overwritten if OverwriteFiles is set to true.

PlainPassword:   Allows you to specify a password stored in plaintext.

By default the Password value will be encrypted with a machine specific key. This secures the password, however the pipeline must be compiled and deployed on the same machine so the same key can be used to decrypt the value. In certain cases you may wish to store the password value in plaintext so decryption is not required at runtime. This setting would be used to specify this like so:

PlainPassword=yourpassword In this case you would not specify any value for Password.

PreserveModifiedTime:   Whether or not to preserve the original modified time on extracted files.

Specifies whether or not the modified time of the extracted files use the current time or the original time of the file in the archive.

When set to True (default) the extracted files will have the same modified time as the original file.

When set to False the modified time on the extracted files will be set to the current time.

Copyright (c) 2022 /n software inc. - All rights reserved.
/n software Connectors for MuleSoft - Version 22.0 [Build 8376]