sophie-package -- Package file format

[deyan]

• Package file format should be named "Sophie Package" and the extension should be .pack.s2
• A Sophie package should contain the book itself and the locally linked resources.
• The Sophie package should be a zip.
• In the 'Export Book As' menu there will be a new 'Sophie Package...' sub menu which will export the current book to a pack.s2 format.
• There must be entry in the file menu "Open Sophie Package".
• When package is opened its contents should be extracted in the temp directory and the book should be opened, then when the user choose to save it, a dialog for choosing location should appear as if the book is new.
• Optional - a progress bar should show that Sophie is packing/unpacking.

[dido]

• In future tasks we may reconsider "Open Sophie Package" button inside file menu, and simplify it with just one "open" button.
• Warning massage should appear if there is not enough disk space in the default temp directory. Note that the massage appear before the Sophie starts the extraction. It will be best, if in this case the user could specify where the extraction should happen. However in this case it doesn't make much sense to ask the user where the book should be saved. It will be nice to open the save dialog with populated data (file name for example) and located in the extraction folder.
• The progress bar that indicates the packing/unpacking also may be obsolete, instead of this we could use "Sophie working" label and make it more consistent. However overall for the application it will be nice to have progress bar and just a label, and use the progress bar only in case we could monitor the time needed for certain operation.
• User should be aware that there might be resources that are linked and not included inside the package. Example:
  • In case I have linked resources from removable hard drive
  • then remove the hard drive
  • then export as Sophie Package
  • What should happen is that dialog appear with warning massage that not all resources are available. It will be best if this includes a list of unavailable resources, also if something is linked from remote location same notification should appear. Options for the user are to continue or to locate the missing resources. There should be visible difference between local and remote resources in this case.
• There are few issues that have to be checked before using zip file format. Downloading Sophie Package with Safari on mac should not rename the file (it have the nasty habit of doing this by adding ".zip" extension)

[dido]

One more thing I forgot, Please set the importance of this task.

[meddle]

• Exporting to package format:
  • Use the current Export logic - an ResourceExportManager.
  • The new manager will need a ResourceLocator to open accesses to files so the logic for initializing and using locators will be taken out of the SophieFormatExportManager to a new abstract class LocatorInitializableExportManager.
  • A new class SophiePackageExportManager will be introduced in the org.sophie2.main.func.resources module. It will be located in the org.sophie2.main.func.resources.exports package and registered in the module as an extension. The package format will be something commont for all the resources in Sophie 2.
    • Its export method will use a SophieFormatExportManager for saving resource to their own files, then packing them.
      • First the resource for packaging will be saved in Sophie 2 Format in the temporary directory.
      • A helper will be created to the saved resource.
      • Then the helper will be passed to the ResourceArchivesUtil#compressResource(ResourceH, File) method. Here the file is the one passed to the ResourceExportManager#export(ResourceAccess, File) method. This will create the package.
      • The files in the temporary folder will be cleaned.
    • The ResourceExportManager#getExportFormat() will return 'Sophie 2.0 package'.
    • ResourceExportManager#getFileName(ResourceAccess) will use file extension '*.pack.s2'.
    • The manager will be work for all the resources in sophie 2.
    • An additional feature that this will add will be that in the resources pallete the new format will be available for all resources.
  • A new AppMenuItem will be added - ExportToPackageItem. It's parent will be the ExportSubMenu. It's title is taken from the analysis, it ha tooltip 'Exports current book to package file' and shortcut 'S'.
  • ResourceExportLogic will have a new handler : ON_EXPORT_PACKAGE_ITEM_CLICKED. It's source will be a ExportToPackageItem. The hadler will use the registered SophiePackageExportManager. To export the current book to a file chosen from a FileDialog.
    • May be in future it will be able to export the current document window's resource?

• Open package format:
  • Will use the current Import logic and there will be new ResourceImportManager.
    • First of all the import managers will have two new methods (unfortunately)
      • public boolean canOpenResource() -> Returns true if the manager can open the resource for edit/view. The Import manager of the images will return true here in the future. By default false.
      • public boolean openResource(AppMainWindow window, File resFile) -> Opens resource for view/edit with the help of a main window. Returns true if the resource's view is opened successfully and false, otherwise. False by default.
    • I know that these methods are new additional thing and have suggestion. The import providers may have ResourceImportManagers and ResourceViewManagers and can be constructed by them. The interface for the view managers can have these two methods and for example close/can close in the future... There will be default implementation of this interface that for now for the open methods returns false. The current constructor of the provider can stay and set the viewManager of the provider to be the default one. This is only an idea for you to think of. The bad think is that I have too much work and many ideas :)
  • A new SophiePackageImportManager will be introduced that extends SophieFormatImportManager.
    • It's import role will be 'Sophie 2.0 Package import'.
    • It will overide getResourceData and will extract the resource file (and relative dirs) first and then will pass the extracted file to the super method, setting the resource data options of the package to it.
    • It will be able to open resources.
    • Opening the resource will mean extracting it (and its relative dir) to the tmp directory and opening the extracted resource.

• A little refactoring:
  • The managers using locators are getting more and more because of that a new ResourceLocatorManager interface will be introduced.
  • It will have the two methods:
    • boolean isInitialized() -> Checks if the locator of the manager is initialized.
    • void initLocator(ResourceLocator resourceLocator) -> Initializes the locator of the manager.
  • It will be implemented by the mentioned above LocatorInitializableExportManager and by the current SophieFormatImportManager.
  • For the import/export logics will be easy to check the managers if they implement the new interface and to initialize them.

• ResourceOpenLogic : Logic for handling opening of resources.
  • ON_OPEN_ITEM_CLICKED handler : Will handle events with source the OpenItem.
  • Helper method public static List<ResourceImportProvider> getOpenableProviders() -> Returns the ResourceImportProviders which managers are able to open resources for edit/view. It is used by the new SophiePackageImportManager when it the extracted resource.
  • Helper method [public static FileFilter computeFileFilter(List<ResourceImportProvider> providers)] -> Appends filters, the new FileInfos will be created here, the ResourceChooserLogic uses it now.
  • Helper method public static boolean openResource(List<ResourceImportProvider> providers, File resFile, AppMainWindow mainWindow). Opens resource with already filtered providers and main window. Used from the new SophiePackageImportManager when opening already exported resource.
  • Opening algorithm:
    • Get the providers that can open resource using getOpenableProviders
      • If there is no such the event is not handled.
    • Compute a file filter with the help of the providers using the computeFileFilter method.
    • Let the user choose file to open, raising the FileDialog.
    • If the file is null -> cancel, return true.
    • If the file does not exist show error message.
    • Try to open the file using the openResource method.

• Delete the old handler for opening a book in the FileMenuLogic.
• BookImportManager will be able to open resources and will use the old logic for opening books.

• Problems:
  • There is problem with the DND on PWA, I'll try to fix it or will forbid dropping packages over the PWA.
  • Fixed strange problem with droping resources in saved book. Bad parent resource was passed.
• Test:
  • SophiePackageExportManagerTest -> Used it to test exporting packages, but importing was basically openning... too visual thing... I will try to generalize the test to be for import and export packages for the implementation to be useful in the future.

• Source code branches/private/meddle/package_format/modules.
• Give some ideas, the task is tested by todor and I will request more testing for the implementation but uploading is the task with greatest priority.

[pap]

• canOpenResource has nice JavaDoc and is generally clear in the context of ResourceImportManager but when I read the name I expected there would be some argument that would be the resource in question. So do you have an idea about a better name? "canOpenInDocument".
• This reflects also openResource.
• I think it is better not to make the new interface as I am not sure we will really need it (ResourceViewManager).

[meddle]

• Fixed some JavaDoc.
• Gave the implementation to Deyan, Todor and Dido to test it, they found some bugs and I fixed them.
• The test for importing/exporting packages is better and fully tests the packaging.

[pap]

• Commited in [8858].
• Changed skin id, but what about it in the skin module - it wasn't changed there.
• Actually you don't need to call super.fillDependencies(); in ModuleTestBase extenders - SophiePackageFormatTest.
• It is better to put I/O streams closings in try finally blocks.

[meddle]

Closing all the tickets before M Y1