Interface::Archive - A placeholder-class to handle generating archive-sets from dataset data.
use Interface::Archive;
# instantiate
my $i=Interface::Archive->new(location=>"/path/whatever",script=>"https://somedomain/script.pl");This class is used in the same way as the Interface-class. See documentation there for more information about the use of this class. None of the implemented methods in this class is meant to be called by the user.
Class to handle the generation and management of archiving-sets of AURORA datasets. This class is just a placeholder and is not meant to be instantiated.
The class has three methods: doRender(), startArchiving() and doUnrender(). The doRender()-method is documented in the Interface.pm-class. The doRender()-class in this module sets up everything needed to generate archives of a AURORA dataset, and logs the process by writing pipe-messages to the parent process.
The doRender()-class in this module calls the method startArchiving() to start the actual archiving process. This method is meant to be overridden by inheriting classes to adapt it to the archive type in question.
The archive-sets that are created are placed in the area denoted by the "location"-option to the new()-method. The MIME result generated upon a successful rendering uses the "script"-option specified to the new()-method to tell it which script to invoke in order to fetch the generated archive.
In the location-area where the archive-files are placed, the file names are as follows:
archive_DATASETID_SHA256SUM_COOKIE.FORMAT.lock
archive_DATASETID_SHA256SUM_COOKIE.FORMATThe .lock-ending is used while the archive is being generated. Upon successful completion it is moved to the filename without the ".lock" ending.
DATASETID is the AURORA dataset id. The SHA256SUM is the SHA256-sum of all the input paths to the doRender()-method (see the documentation for the render()-method in the Interface-class for more details), sorted alphabetically and separated with \000-characters. This is to allow a unique signature for the selected archived folders in a dataset, so that the filename can be found by searching for that signature. It also allows for unique signature of an archive-set dependent upon which folders were selected for archiving.
COOKIE is a random 64-byte string containing only a-zA-Z0-9. This is the unique signature used to fetch the filename via the download script mentioned above.
FORMAT is the archive set file ending, such as "tar.gz", "zip" etc. It is to be set by the inheriting class. It defaults to "unknown".
Upon a successful render of an archive-set, the renderResult()-method (see the documentation for the Interface-class) will return the MIME formatted URL to the set. This MIME-response uses the script-setting mentioned above, so that the returned URL is a combination of a location and name, appended with the COOKIE-string mentioned above for identification:
https://domain/script.whatever?cookie=COOKIEThe doUnrender()-method removes any archive-set that might have been generated. It is called by the Unrender()-method (see documentation of the Interface-class).
Instantiates class.
Inherits from Interface-class.
Sets the need for location- and script options. Sets the MIME-type and format. The format is meant to be overridden by inheriting child. It default to "unknown". See Description-paragraph for more information.
It takes the following additional parameters (see Interface-class documentation for other parameters):
location Sets the path where the archives will be generated. Required.
script Sets the URL to the script where one can download the generated archive by specifying the cookie. Required.
redirect Sets the statement to redirect STDERR to STDOUT. Optional and defaults to 2>&1.
echo Sets location of the echo-binary. Optional and defaults to /bin/echo.
The method returns the instantiated class.
The actual rendering process. Inherited from Interface (see Interface-class for more information on its use and purpose). It is called by the render()-method.
The method sets up the rendering process before calling the method startArchiving() and then monitors the archiving feeding information back to the parent process. The startArchiving()-method is meant to be overridden by inheriting classes.
It first attempts to check if there already exists a archive-file that matches the signature of the SHA256SUM and format (see Description-paragraph). It also checks if there is already a rendering going on by checking for the ".lock"-extension on the files. If a rendering is already running by another process it will start looping waiting for it to finish. If it finishes by removing the ".lock"-extension and the final archive file emerges, it will return a SUCCESS-level message to the parent and send the MIME-message. In will in other words behave as if it was rendering the file itself, although it is just hanging back and waiting for the other process to finish.
If not archive exists already, it will setup the process to start archiving itself. After setting it up, opening the dataset data, it calls the startArchiving()-method and have it start the archiving command or process itself. It will then read and wait for messages from that process and feeding this back to the parent-process (see the doRender()-method documentation in the Interface-class for more information).
This method is not meant to be called by the user.
Starts the archiving command or process itself. Returns a pipe read-handler to be able to monitor the process.
This method basically starts and runs the archiving command or process that does the actual work. It is expected to return a read-handler in $self->{aread} so that the calling method (doRender()) can monitor its progress.
It takes these parameters in the following order: DATASETID,USERID,PATHS,SOURCE,DESTINATION,ENDMARKER.
See the doRender()-method in the documentation of the Interface-class for more information on the DATASETID,USERID and PATHS paremeters.
The SOURCE parameter is where the dataset data is located (the root of it). The DESTINATION parameter gives the location and filename where the archive set is to be generated/stored. ENDMARKER is a random string that is written at the end of the archiving process to make it possible for the doRender()-method to easy know when it ended.
The method returns no data.
This method is not to be called by the user, but by the doRender()-method. The method is meant to be overridden by the inheriting class to start that specific type of archiving.
Does the actual unrendering of an archived dataset.
It first checks to see if the given rendering exists or not or if it is still rendering. It does this by checking for the archived dataset file.
If it is still rendering, it returns with a error-message stating that, if it cant find it it also returns with a error message saying that.
It the archived dataset exists, it removes the file and then reports back.
This method is general for the Archive-class family and shouldn't be needed to be overridden.
See the doUnrender()-method in the Interface-class for more documentation.