Home

# ZipExtractor

ZipExtractor is an administrative utility plugin allowing the compression/extraction of archived files through minecraft command. This plugin is extremely useful for dealing with archives over FTP, which does not provide support for neither compression nor extraction. While many safeguards are in place, please note that there is no undo button. Overridden files cannot be recovered.

The source and destination file paths are saved inside of the config.yml. This means that only one can be set at a time. If you edit these values directly in the config.yml you must reload the plugin for the new values to take effect.

Feature List

Extraction of ZIP, RAR, and JAR, PACK, GZ, and XZ archives.
Compression of any file or directory into the ZIP format.
Compression of any JAR file to the PACK format, and any non-directory file to the GZ or XZ formats.
Queueable operations if you have many extractions/compressions to perform.
Configurable Thread Pool Executor allowing you to set a maximum queue size and maximum number of threads to run at once. Incase of an emergency the Thread Pool can be shutdown at anytime.
Option to be warned if an extraction/compression would result in files being overriden.
- If enabled, users will require an additional permission in order to proceed with the process.
- For extractions, you can view every file which would be overriden prior to proceeding with the process.
Tab completion for file paths, similar to the command line (configurable).
Pipe multiple extractions/compressions with a single command. (Ex. Extract Test.jar.pack.xz to Test.jar).
Metrics by bStats

Supported Archive Types

Archive Type	Can be Extracted	Files which can be compressed to this format
`ZIP`	✓	Any file or directory
`RAR`	✓	✗
`JAR`	✓	✗
`PACK`	✓	`JAR` files only
`GZ`	✓	Any non-directory file
`XZ`	✓	Any non-directory file

Notes on Working With Archives

If you wish to compress a file to the XZ format, you should set your destination file to have the same extensions as the source, just with .xz appended. For example. If I want to compress MyFile.jar to XZ, I could have the destination set as MyFileArchive.jar.xz.
Only JAR files can be compressed to the PACK format. When compressing, keep the .jar extension in the destination file. For example, source = MyJar.jar, destination = MyJar.jar.pack.

For most users, ZIP compressions and extractions will be most common. These other formats are primarily supported for developers and administrators.

Commands

All commands can be run using /ZipExtractor or the shorter alias /ze.

Command	Description	Required Permission
/ze help [cmd]	View the command list or more information on a specific command. To view more information on a command replace [cmd] with the name of said command.	`zipextractor.admin.use`
/ze extract	Begin an extraction process. The source file will be extracted into the destination directory.	`zipextractor.admin.extract`
/ze extract view [page]	If a process was halted because it could result in overriden files, you may use this command to view exactly which files would be overriden. The files are listed as relative paths with respect to the destination directory.	`zipextractor.admin.extract`
/ze compress	Begin a compression process. The source file/directory will be compressed to the destination path. The compression type depends on the extension of the destination. If you use `.zip`, it will be compressed to `zip` archive.	`zipextractor.admin.compress`
/ze src [--absolute]	View the currently defined source path. If you pass the `--absolute` parameter the path will be an absolute path as defined by the File System.	`zipextractor.admin.src`
/ze dest [--absolute]	View the currently defined destination path. If you pass the `--absolute` parameter the path will be an absolute path as defined by the File System.	`zipextractor.admin.dest`
/ze setsrc	Define the source file path. This can be either a relative or absolute path.	`zipextractor.admin.setsrc`
/ze setdest	Define the destination file path. This can be either a relative or absolute path.	`zipextractor.admin.setdest`
/ze status	This command will display the status of the executor service. If the service has not been terminated, the number of active and queued processes will be displayed.	`zipextractor.harmless.status`
/ze plugindir	View the absolute path of this plugin's configuration directory.	`zipextractor.admin.plugindir`
/ze terminate	This command will initiate the shutdown proccess for the plugin's execution servicer. Any queued tasks at the time of shutdown will be allowed to finish. It is recommended not to shutdown or restart the server until this has finished.	`zipextractor.admin.terminate`
/ze forceterminate	This command will forcibly shutdown the plugin's execution servicer and send a request to interrupt and terminate any queued and proccessing tasks. This type of termination is not recommended.	`zipextractor.admin.forceterminate`
/ze reload	This command will reload the configuration file. It's necessary to do this after you edit the config file directly. If you use the built-in commands it's automatically reloaded after each edit.	`zipextractor.admin.reload`
/ze version	Displays the plugin's version information and provides links to the source code and metrics page.	-

Additional Command Information

/ZipExtractor Extract

The source path must point to a supported archive file.
The destination path must point to a directory.
If the configuration option warn_on_conflics is enabled, a scan will be performed before begining the extraction process. If it's determined that one or more files would be overriden by the extraction, the process will be halted and the user will be given options. In order to view eactly which files would be overriden, the command /ze extract view [page] can be run. To proceed with the extraction anyway, run the command /ze extract --override. Note, in order to override you will need an additional permission, namely zipextractor.admin.override.extract.

Example Usage:

I have a rar file I want to extract. The path to the rar file is C:\MyServer\MyWorld.rar. I want to extract the contents into C:\MyServer\MyWorld.

/ze setsrc MyWorld.rar

/ze setdest MyWorld

/ze extract

You set the source file to the rar you wish to extract. You set the destination to a folder called MyWorld. The contents of the rar will be extracted into this folder.

Piped Extractions

You can extract multiple formats in one command by piping the operation. To pipe, add one of the following flags.

--until <type> - will extract until it reaches <type> or a format it cannot handle.

--all - will extract until it reaches a format it cannot handle.

Example Source: dir/Test.jar.pack.xz

Destination: dir/output

/ze extract will extract Test.jar.pack into dir/output.

/ze extract --until jar will extract Test.jar into dir/output.

/ze extract --all will extract Test.jar's contents into dir/output.

Note: If the piped operation contains a format which cannot be scanned ahead of time, the destination directory must be empty. If it is not, the operation will be cancelled, even if --override is passed. An example of this is the ZIP format. We cannot scan for conflicts without first having the source file in the ZIP format. The scan involed checking each ZIP entry, which we do not have access to until the file is in ZIP format. This is the same for JAR and RAR.

/ZipExtractor Compress

The source path must point to a file or directory.
The destination path must point to a supported archive type. The archived file will be created once the compression is complete. If the destination path does not point to a supported archive type, the operation will be cancelled.
If the configuration option warn_on_conflics is enabled, the plugin will check to see if the destination file already exists. If it does, the process will be halted. In order to view the currently set destination file, you can check /ze dest [--absolute]. To proceed with the compression anyway, run the command /ze compress --override. Note, in order to override you will need an additional permission, namely zipextractor.admin.override.compress.
Multiple compressions can be piped together in a single command. If your source points to Test.jar and your destination points to Test.jar.pack.xz, the command will first compress to pack and then to xz.

Example Usage:

I want to zip a world folder so that I can download it over FTP. The path to the world is C:\MyServer\AwesomeWorld. I > want it to be zipped to C:\MyServer\AwesomeWorld.zip.

/ze setsrc AwesomeWorld

/ze setdest AwesomeWorld.zip

/ze compress

You set the source folder to the location of your world. You then set the destination file. Since you ended the path in .zip, the plugin will compress the directory to a zip archive.

/ZipExtractor src and /ZipExtractor dest

These commands will return the source/destination paths exactly as they are defined in the configuration file. If you have defined a relative path and would like to see the absolute path it resolves to, run the command with the --absolute argument.

Example:

Defined path: plugins/ZipExtractor/MyArchive.zip

Output from..

/ZipExtractor src: plugins/ZipExtractor/MyArchive.zip

/ZipExtractor src --absolute (Windows): C:\Users\Name\MyServer\plugins\ZipExtractor\MyArchive.zip

/ZipExtractor setsrc and /ZipExtractor setdest

These commands can accept both relative and absolute paths. The relative path starts at your server directory. Therefore if you define a path as plugins it will resolve to C:\An\Example\Path\To\MyServer\plugins.

You can use tab completion to complete path arguments. (Screenshot Below)

Notes on Tab Completion

Console vs In-Game

Tab completions work perfectly if the path you are tabbing does not include spaces. If the path does include a space, you will need to break the tabbing operation (by adding an extra character) and then resume it (remove the character and tab again).

On Bukkit, spaces are not a problem in the console.

On Sponge, spaces are escaped in the console. You need to remove the escape characters.

Ex. You are trying to get to ./plugins/MyPlugin/target.zip. There is another folder called My Folder in the plugins directory. You take the following steps.

Type /ze setsrc ./pl and then hit tab.

The value /ze setsrc ./plugins/ is autofilled.

Continue; /ze setsrc ./plugins/My and hit tab.

The value /ze setsrc ./plugins/My Folder is autofilled.

If you continue to hit tab in an attempt to have it switch to MyPlugin, the autocompletion will fail. This will confuse minecraft, because a space means that we are now in another argument. It will only update whatever is after the space. For example, the value /ze setsrc ./plugins/My ./plugins/MyPlugins would be autofilled. This is clearly not correct.

You would need to manually change it to /ze setsrc ./plugins/MyP and then hit tab to get the desired result.

Note If your target file was at ./plugins/My Folder/target.zip, you could simply type a / and hit tab. This would work.

Sponge

Additionally on Sponge, a space is added after you finish a single tab completion. Simply remove the space and tab again to keep going.

Disabling

Tab completion can be disabled with the configuration value general_settings.tab_complete_files.

Permissions

On sponge, wildcard permissions do not exist. Omit the .* to get the same functionality.

Permission	Description	Default
`zipextractor.*`	Full access to ZipExtractor.	OP
`zipextractor.admin.*`	Access to administrator commands.	OP
`zipextractor.admin.use`	Allows usage of /ZipExtractor	OP
`zipextractor.admin.extract`	Allows usage of /ZipExtractor extract	OP
`zipextractor.admin.compress`	Allows usage of /ZipExtractor compress	OP
`zipextractor.admin.override.extract`	If `warn_on_conflicts` is enabled, allows usage of /ZipExtractor extract --override	OP
`zipextractor.admin.override.compress`	If `warn_on_conflicts` is enabled, allows usage of /ZipExtractor compress --override	OP
`zipextractor.admin.src`	Allows usage of /ZipExtractor src	OP
`zipextractor.admin.dest`	Allows usage of /ZipExtractor dest	OP
`zipextractor.admin.setsrc`	Allows usage of /ZipExtractor setsrc	OP
`zipextractor.admin.setdest`	Allows usage of /ZipExtractor setdest	OP
`zipextractor.admin.plugindir`	Allows usage of /ZipExtractor plugindir	OP
`zipextractor.admin.terminate`	Allows usage of /ZipExtractor terminate	OP
`zipextractor.admin.forceterminate`	Allows usage of /ZipExtractor forceterminate	OP
`zipextractor.admin.reload`	Allows usage of /ZipExtractor reload	OP
`zipextractor.harmless.*`	Access to harmless commands.	OP
`zipextractor.harmless.status`	Allow usage of /ZipExtractor status	OP
`zipextractor.harmless.notify`	User will be notified if the plugin broadcasts a message.	OP

Permission Tree

zipextractor.*

zipextractor.admin.*

zipextractor.admin.use

zipextractor.admin.extract

zipextractor.admin.compress

zipextractor.admin.override.extract

zipextractor.admin.override.compress

zipextractor.admin.src

zipextractor.admin.dest

zipextractor.admin.setsrc

zipextractor.admin.setdest

zipextractor.admin.plugindir

zipextractor.admin.terminate

zipextractor.admin.forceterminate

zipextractor.admin.reload

zipextractor.harmless.*

zipextractor.harmless.status

zipextractor.harmless.notify

Configuration File

#-----------------------------------------------
#            Zip Extractor Config
#-----------------------------------------------

#DO NOT CHANGE THIS VALUE.
#CHANGING IT COULD RESULT IN DATA LOSS.
ConfigVersion: 1.0

#---------------[File Settings]-----------------
# Use '/' for a file separator as shown below.
# If your Operating System uses a different
# character for the file seperator, that will
# automatically be detected by the plugin and
# will be converted on the fly. The '/' is for
# for ease of storage.
#
# Both relative and absolute file paths are supported.
file_settings:

  # Specify the file path of your soruce folder/file.
  source_directory: "plugins/ZipExtractor/MyArchive.zip"
  
  # Specify the file path of the destination folder/file.
  destination_directory: "C:/MyServer/MyOutputFolder"

#--------------[General Settings]---------------
general_settings:
  
  # Specify whether or not the plugin should
  # log each file inside the archive to the
  # console during task execution.
  log_files: true
  
  # Specify whether or not the plugin should
  # warn users when operations will result
  # in files being overrided. There is NO
  # undo button, so keeping this option on
  # is HIGHLY recommended.
  #
  # When this is enabled, the files will be
  # scanned beforehand. If any files have
  # conflicts, the operation will be halted
  # and the user will be warned with further
  # information, including how to ignore the
  # warning and proceed anyway.
  warn_on_conflicts: true
  
  # Specify whether or not users can use tab
  # completion to specify paths to the setsrc
  # and setdest commands.
  tab_complete_files: true
  
  # Specify whether or not the plugin should wait
  # for outstanding tasks to be completed before 
  # the server shuts down. If false, any outstanding
  # tasks will be interrupted and terminated.
  #
  # It's generally a good idea to not shut down the
  # server while tasks are running or queued.
  wait_on_shutdown: true
  
  # Specify the maximum number of tasks to be queued
  # at a time. This number must be an integer greater
  # than zero. If this condition is not met, the limit
  # will be set to an absurdley large number (2147483647)
  # that will likely never be reached unless something
  # shady is taking place on your server.
  #
  # **Changing this value while the server is running is
  # not possibile, and it will require a restart to take
  # effect.
  max_queue_size: 3
  
  # Specify the maximum number of threads to be pooled in
  # the plugin's executor service. This number must be an
  # integer greater than zero, or else it will default to
  # 1. IF YOU DO NOT KNOW WHAT THIS MEANS THEN YOU SHOULD
  # NOT CHANGE THIS VALUE, AS POTENTIAL HARM COULD COME TO
  # YOUR SERVER (this is on the bottom for a reason).
  #
  # For your own safety the core pool size is hard set at 1.
  # If you're an advanced user and you want this value to be
  # configurable, contact the author or manager of this plugin.
  #
  # The recommended value for this is 1 unless you are
  # willing to put your server through some serious work when
  # queues get large. Updating this value to a smaller number
  # than the previous one while the server is running will
  # terminate excess threads once they become idle.
  maximum_thread_pool: 1