FileManager
Date: 2019-10-22

org.jmol.viewer

## Class FileManager

- java.lang.Object
- - org.jmol.viewer.FileManager

- All Implemented Interfaces:
    javajs.api.BytePoster

      public class FileManager
      extends java.lang.Object
      implements javajs.api.BytePoster

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private java.net.URL` | `appletDocumentBaseURL`
    `private java.lang.String` | `appletProxy`
    `private java.util.Map<java.lang.String,java.lang.Object>` | `cache`
    `private static java.lang.String` | `DELPHI_BINARY_MAGIC_NUMBER`
    `private java.lang.String` | `fileName`
    `private java.lang.String` | `fullPathName`
    `static java.lang.String` | `JPEG_CONTINUE_STRING`
    `(package private) JmolUtil` | `jzu`
    `private java.lang.String` | `lastFullPathName`
    `private java.lang.String` | `lastNameAsGiven`
    `private java.lang.String` | `nameAsGiven`
    `private java.lang.String` | `pathForAllFiles`
    `static java.lang.String` | `PMESH_BINARY_MAGIC_NUMBER`
    `java.util.Map<java.lang.String,java.lang.Object>` | `pngjCache`
    `private static java.lang.String[]` | `scriptFilePrefixes`
    `static java.lang.String` | `SIMULATION_PROTOCOL`
    `java.util.Map<java.lang.String,byte[]>` | `spardirCache`
    `private SpartanUtil` | `spartanDoc`
    `Viewer` | `vwr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FileManager(Viewer vwr)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static java.lang.String` | `addDirectory(java.lang.String defaultDirectory, java.lang.String name)`
    `(package private) void` | `cacheClear()`
    `int` | `cacheFileByNameAdd(java.lang.String fileName, boolean isAdd)`
    `java.lang.Object` | `cacheGet(java.lang.String key, boolean bytesOnly)`
    `java.util.Map<java.lang.String,java.lang.Integer>` | `cacheList()`
    `(package private) void` | `cachePut(java.lang.String key, java.lang.Object data)`
    `private boolean` | `checkSecurity(java.lang.String f)`
    `(package private) void` | `clear()`
    `(package private) java.lang.Object` | `createAtomSeCollectionFromArrayData(javajs.util.Lst<java.lang.Object> arrayData, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `(package private) java.lang.Object` | `createAtomSeCollectionFromStrings(java.lang.String[] arrayModels, javajs.util.SB loadScript, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `(package private) java.lang.Object` | `createAtomSetCollectionFromDOM(java.lang.Object DOMNode, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `(package private) java.lang.Object` | `createAtomSetCollectionFromFile(java.lang.String name, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `(package private) java.lang.Object` | `createAtomSetCollectionFromFiles(java.lang.String[] fileNames, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `(package private) java.lang.Object` | `createAtomSetCollectionFromReader(java.lang.String fullPathName, java.lang.String name, java.lang.Object reader, java.util.Map<java.lang.String,java.lang.Object> htParams)` not used in Jmol project -- will close reader
    `(package private) java.lang.Object` | `createAtomSetCollectionFromString(java.lang.String strModel, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `static java.lang.String` | `determineSurfaceFileType(java.io.BufferedReader bufferedReader)`
    `static java.lang.String` | `determineSurfaceTypeIs(java.io.InputStream is)`
    `static java.lang.String` | `fixDOSName(java.lang.String fileName)` Switch \ for / only for DOS names such as C:\temp\t.xyz, not names like http://cactus.nci.nih.gov/chemical/structure/CC/C=C\CC
    `private static java.lang.String` | `fixPath(java.lang.String path)`
    `(package private) java.lang.String` | `getAppletDocumentBase()`
    `(package private) java.io.BufferedInputStream` | `getBufferedInputStream(java.lang.String fullPathName)`
    `java.lang.Object` | `getBufferedInputStreamOrErrorMessageFromName(java.lang.String name, java.lang.String fullName, boolean showMsg, boolean checkOnly, byte[] outputBytes, boolean allowReader, boolean allowCached)`
    `static java.io.BufferedReader` | `getBufferedReaderForResource(Viewer vwr, java.lang.Object resourceClass, java.lang.String classPath, java.lang.String resourceName)`
    `java.lang.Object` | `getBufferedReaderOrErrorMessageFromName(java.lang.String name, java.lang.String[] fullPathNameReturn, boolean isBinary, boolean doSpecialLoad)`
    `private byte[]` | `getCachedPngjBytes(java.lang.String pathName)`
    `java.lang.String` | `getCanonicalName(java.lang.String pathName)`
    `private java.lang.String[]` | `getClassifiedName(java.lang.String name, boolean isFullLoad)` [0] and [2] may return same as [1] in the case of a local unsigned applet.
    `(package private) java.lang.String` | `getDefaultDirectory(java.lang.String name)`
    `java.lang.String` | `getEmbeddedFileState(java.lang.String fileName, boolean allowCached, java.lang.String sptName)`
    `static java.lang.String` | `getEmbeddedScript(java.lang.String script)`
    `java.lang.Object` | `getFileAsBytes(java.lang.String name, javajs.util.OC out)`
    `java.util.Map<java.lang.String,java.lang.Object>` | `getFileAsMap(java.lang.String name, java.lang.String type)`
    `boolean` | `getFileDataAsString(java.lang.String[] data, int nBytesMax, boolean doSpecialLoad, boolean allowBinary, boolean checkProtected)`
    `java.lang.String[]` | `getFileInfo()`
    `java.lang.String` | `getFileName()`
    `java.lang.String` | `getFilePath(java.lang.String name, boolean addUrlPrefix, boolean asShortName)`
    `static void` | `getFileReferences(java.lang.String script, javajs.util.Lst<java.lang.String> fileList)`
    `java.lang.String` | `getFullPathName(boolean orPrevious)`
    `(package private) java.lang.Object` | `getFullPathNameOrError(java.lang.String filename, boolean getStream, java.lang.String[] ret)` just check for a file as being readable.
    `JmolUtil` | `getJzu()`
    `static GenericFileInterface` | `getLocalDirectory(Viewer vwr, boolean forDialog)`
    `static java.lang.String` | `getLocalPathForWritingFile(Viewer vwr, java.lang.String file)`
    `static java.lang.String` | `getManifestScriptPath(java.lang.String manifest)` check a JmolManifest for a reference to a script file (.spt)
    `java.lang.String` | `getPathForAllFiles()`
    `private byte[]` | `getPngjOrDroppedBytes(java.lang.String fullName, java.lang.String name)`
    `java.lang.Object` | `getUnzippedReaderOrStreamFromName(java.lang.String name, java.lang.Object bytesOrStream, boolean allowZipStream, boolean forceInputStream, boolean isTypeCheckOnly, boolean doSpecialLoad, java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `java.lang.String[]` | `getZipDirectory(java.lang.String fileName, boolean addManifest, boolean allowCached)`
    `static boolean` | `isScriptType(java.lang.String fname)`
    `static boolean` | `isSurfaceType(java.lang.String fname)`
    `boolean` | `loadImage(java.lang.Object nameOrBytes, java.lang.String echoName, boolean forceSync)` Load an image
    `(package private) static javajs.util.DataReader` | `newDataReader(Viewer vwr, java.lang.Object data)`
    `private JmolFilesReaderInterface` | `newFilesReader(java.lang.String[] fullPathNames, java.lang.String[] namesAsGiven, java.lang.String[] fileTypes, javajs.util.DataReader[] readers, java.util.Map<java.lang.String,java.lang.Object> htParams, boolean isAppend)`
    `java.lang.String` | `postByteArray(java.lang.String fileName, byte[] bytes)`
    `void` | `recachePngjBytes(java.lang.String fileName, byte[] bytes)`
    `(package private) void` | `setAppletContext(java.lang.String documentBase)`
    `(package private) void` | `setAppletProxy(java.lang.String appletProxy)`
    `void` | `setFileInfo(java.lang.String[] fileInfo)` Set fullPathName, fileName, and nameAsGiven
    `private void` | `setLoadState(java.util.Map<java.lang.String,java.lang.Object> htParams)`
    `static void` | `setLocalPath(Viewer vwr, java.lang.String path, boolean forDialog)` called by getImageFileNameFromDialog called by getOpenFileNameFromDialog called by getSaveFileNameFromDialog called by classifyName for any full file load called from the CD command currentLocalPath is set in all cases and is used specifically for dialogs as a first try defaultDirectoryLocal is set only when not from a dialog and is used only in getLocalPathForWritingFile or from an open/save dialog.
    `(package private) java.lang.String` | `setPathForAllFiles(java.lang.String value)`
    `static java.lang.String` | `setScriptFileReferences(java.lang.String script, java.lang.String localPath, java.lang.String remotePath, java.lang.String scriptPath)`
    `private static java.lang.String` | `setScriptFileRefs(java.lang.String script, java.lang.String dataPath, boolean isLocal)` Sets all local file references in a script file to point to files within dataPath.
    `SpartanUtil` | `spartanUtil()` An isolated class to retrieve Spartan file data from compound documents, zip files, and directories
    `static java.lang.String` | `stripPath(java.lang.String name)`
    `private java.lang.String` | `urlEncode(java.lang.String name)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### SIMULATION_PROTOCOL

          public static java.lang.String SIMULATION_PROTOCOL

    - #### vwr

          public Viewer vwr

    - #### spartanDoc

          private SpartanUtil spartanDoc

    - #### jzu

          JmolUtil jzu

    - #### pathForAllFiles

          private java.lang.String pathForAllFiles

    - #### nameAsGiven

          private java.lang.String nameAsGiven

    - #### fullPathName

          private java.lang.String fullPathName

    - #### lastFullPathName

          private java.lang.String lastFullPathName

    - #### lastNameAsGiven

          private java.lang.String lastNameAsGiven

    - #### fileName

          private java.lang.String fileName

    - #### appletDocumentBaseURL

          private java.net.URL appletDocumentBaseURL

    - #### appletProxy

          private java.lang.String appletProxy

    - #### DELPHI_BINARY_MAGIC_NUMBER

          private static final java.lang.String DELPHI_BINARY_MAGIC_NUMBER

      See Also:
        Constant Field Values

    - #### PMESH_BINARY_MAGIC_NUMBER

          public static final java.lang.String PMESH_BINARY_MAGIC_NUMBER

      See Also:
        Constant Field Values

    - #### JPEG_CONTINUE_STRING

          public static final java.lang.String JPEG_CONTINUE_STRING

      See Also:
        Constant Field Values

    - #### scriptFilePrefixes

          private static java.lang.String[] scriptFilePrefixes

    - #### cache

          private java.util.Map<java.lang.String,java.lang.Object> cache

    - #### pngjCache

          public java.util.Map<java.lang.String,java.lang.Object> pngjCache

    - #### spardirCache

          public java.util.Map<java.lang.String,byte[]> spardirCache

  - ### Constructor Detail

    - #### FileManager

          FileManager(Viewer vwr)

  - ### Method Detail

    - #### spartanUtil

          public SpartanUtil spartanUtil()

      An isolated class to retrieve Spartan file data from compound documents, zip files, and directories
      Returns:
        a SpartanUtil

    - #### getJzu

          public JmolUtil getJzu()

    - #### clear

          void clear()

    - #### setLoadState

          private void setLoadState(java.util.Map<java.lang.String,java.lang.Object> htParams)

    - #### getPathForAllFiles

          public java.lang.String getPathForAllFiles()

    - #### setPathForAllFiles

          java.lang.String setPathForAllFiles(java.lang.String value)

    - #### setFileInfo

          public void setFileInfo(java.lang.String[] fileInfo)

      Set fullPathName, fileName, and nameAsGiven
      Parameters:
        `fileInfo` - if null, replace fullPathName and nameAsGiven with last version of such

    - #### getFileInfo

          public java.lang.String[] getFileInfo()

    - #### getFullPathName

          public java.lang.String getFullPathName(boolean orPrevious)

    - #### getFileName

          public java.lang.String getFileName()

    - #### getAppletDocumentBase

          java.lang.String getAppletDocumentBase()

    - #### setAppletContext

          void setAppletContext(java.lang.String documentBase)

    - #### setAppletProxy

          void setAppletProxy(java.lang.String appletProxy)

    - #### createAtomSetCollectionFromFile

          java.lang.Object createAtomSetCollectionFromFile(java.lang.String name,
                                                           java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                           boolean isAppend)

    - #### createAtomSetCollectionFromFiles

          java.lang.Object createAtomSetCollectionFromFiles(java.lang.String[] fileNames,
                                                            java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                            boolean isAppend)

    - #### createAtomSetCollectionFromString

          java.lang.Object createAtomSetCollectionFromString(java.lang.String strModel,
                                                             java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                             boolean isAppend)

    - #### createAtomSeCollectionFromStrings

          java.lang.Object createAtomSeCollectionFromStrings(java.lang.String[] arrayModels,
                                                             javajs.util.SB loadScript,
                                                             java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                             boolean isAppend)

    - #### createAtomSeCollectionFromArrayData

          java.lang.Object createAtomSeCollectionFromArrayData(javajs.util.Lst<java.lang.Object> arrayData,
                                                               java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                               boolean isAppend)

    - #### newDataReader

          static javajs.util.DataReader newDataReader(Viewer vwr,
                                                      java.lang.Object data)

    - #### newFilesReader

          private JmolFilesReaderInterface newFilesReader(java.lang.String[] fullPathNames,
                                                          java.lang.String[] namesAsGiven,
                                                          java.lang.String[] fileTypes,
                                                          javajs.util.DataReader[] readers,
                                                          java.util.Map<java.lang.String,java.lang.Object> htParams,
                                                          boolean isAppend)

    - #### createAtomSetCollectionFromDOM

          java.lang.Object createAtomSetCollectionFromDOM(java.lang.Object DOMNode,
                                                          java.util.Map<java.lang.String,java.lang.Object> htParams)

    - #### createAtomSetCollectionFromReader

          java.lang.Object createAtomSetCollectionFromReader(java.lang.String fullPathName,
                                                             java.lang.String name,
                                                             java.lang.Object reader,
                                                             java.util.Map<java.lang.String,java.lang.Object> htParams)

      not used in Jmol project -- will close reader
      Parameters:
        `fullPathName` -
        `name` -
        `reader` - could be a Reader, or a BufferedInputStream or byte[]
        `htParams` -
      Returns:
        fileData

    - #### getBufferedInputStream

          java.io.BufferedInputStream getBufferedInputStream(java.lang.String fullPathName)

    - #### getBufferedInputStreamOrErrorMessageFromName

          public java.lang.Object getBufferedInputStreamOrErrorMessageFromName(java.lang.String name,
                                                                               java.lang.String fullName,
                                                                               boolean showMsg,
                                                                               boolean checkOnly,
                                                                               byte[] outputBytes,
                                                                               boolean allowReader,
                                                                               boolean allowCached)

    - #### getBufferedReaderForResource

          public static java.io.BufferedReader getBufferedReaderForResource(Viewer vwr,
                                                                            java.lang.Object resourceClass,
                                                                            java.lang.String classPath,
                                                                            java.lang.String resourceName)
                                                                     throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### urlEncode

          private java.lang.String urlEncode(java.lang.String name)

    - #### getEmbeddedFileState

          public java.lang.String getEmbeddedFileState(java.lang.String fileName,
                                                       boolean allowCached,
                                                       java.lang.String sptName)

    - #### getFullPathNameOrError

          java.lang.Object getFullPathNameOrError(java.lang.String filename,
                                                  boolean getStream,
                                                  java.lang.String[] ret)

      just check for a file as being readable. Do not go into a zip file
      Parameters:
        `filename` -
        `getStream` -
        `ret` -
      Returns:
        String[2] where [0] is fullpathname and [1] is error message or null

    - #### getBufferedReaderOrErrorMessageFromName

          public java.lang.Object getBufferedReaderOrErrorMessageFromName(java.lang.String name,
                                                                          java.lang.String[] fullPathNameReturn,
                                                                          boolean isBinary,
                                                                          boolean doSpecialLoad)

    - #### getUnzippedReaderOrStreamFromName

          public java.lang.Object getUnzippedReaderOrStreamFromName(java.lang.String name,
                                                                    java.lang.Object bytesOrStream,
                                                                    boolean allowZipStream,
                                                                    boolean forceInputStream,
                                                                    boolean isTypeCheckOnly,
                                                                    boolean doSpecialLoad,
                                                                    java.util.Map<java.lang.String,java.lang.Object> htParams)

      Parameters:
        `name` -
        `bytesOrStream` - cached bytes or a BufferedInputStream
        `allowZipStream` - if the file is a zip file, allow a return that is a ZipInputStream
        `forceInputStream` - always return a raw BufferedInputStream, not a BufferedReader, and do not process PNGJ files
        `isTypeCheckOnly` - when possibly reading a spartan file for content (doSpecialLoad == true), just return the compound document's file list
        `doSpecialLoad` - check for a Spartan file
        `htParams` -
      Returns:
        String if error or String[] if a type check or BufferedReader or BufferedInputStream

    - #### getZipDirectory

          public java.lang.String[] getZipDirectory(java.lang.String fileName,
                                                    boolean addManifest,
                                                    boolean allowCached)

      Parameters:
        `fileName` -
        `addManifest` -
        `allowCached` -
      Returns:
        [] if not a zip file;

    - #### getFileAsBytes

          public java.lang.Object getFileAsBytes(java.lang.String name,
                                                 javajs.util.OC out)

    - #### getFileAsMap

          public java.util.Map<java.lang.String,java.lang.Object> getFileAsMap(java.lang.String name,
                                                                               java.lang.String type)

    - #### getFileDataAsString

          public boolean getFileDataAsString(java.lang.String[] data,
                                             int nBytesMax,
                                             boolean doSpecialLoad,
                                             boolean allowBinary,
                                             boolean checkProtected)

      Parameters:
        `data` - [0] initially path name, but returned as full path name; [1]file contents (directory listing for a ZIP/JAR file) or error string
        `nBytesMax` - or -1
        `doSpecialLoad` -
        `allowBinary` -
        `checkProtected` - TODO
      Returns:
        true if successful; false on error

    - #### checkSecurity

          private boolean checkSecurity(java.lang.String f)

    - #### loadImage

          public boolean loadImage(java.lang.Object nameOrBytes,
                                   java.lang.String echoName,
                                   boolean forceSync)

      Load an image
      Parameters:
        `nameOrBytes` -
        `echoName` -
        `forceSync` - TODO
      Returns:
        true if asynchronous

    - #### getClassifiedName

          private java.lang.String[] getClassifiedName(java.lang.String name,
                                                       boolean isFullLoad)

      [0] and [2] may return same as [1] in the case of a local unsigned applet.
      Parameters:
        `name` -
        `isFullLoad` - false only when just checking path
      Returns:
        [0] full path name, [1] file name without path, [2] full URL

    - #### addDirectory

          private static java.lang.String addDirectory(java.lang.String defaultDirectory,
                                                       java.lang.String name)

    - #### getDefaultDirectory

          java.lang.String getDefaultDirectory(java.lang.String name)

    - #### fixPath

          private static java.lang.String fixPath(java.lang.String path)

    - #### getFilePath

          public java.lang.String getFilePath(java.lang.String name,
                                              boolean addUrlPrefix,
                                              boolean asShortName)

    - #### getLocalDirectory

          public static GenericFileInterface getLocalDirectory(Viewer vwr,
                                                               boolean forDialog)

    - #### setLocalPath

          public static void setLocalPath(Viewer vwr,
                                          java.lang.String path,
                                          boolean forDialog)

      called by getImageFileNameFromDialog called by getOpenFileNameFromDialog called by getSaveFileNameFromDialog called by classifyName for any full file load called from the CD command currentLocalPath is set in all cases and is used specifically for dialogs as a first try defaultDirectoryLocal is set only when not from a dialog and is used only in getLocalPathForWritingFile or from an open/save dialog. In this way, saving a file from a dialog doesn't change the "CD" directory. Neither of these is saved in the state, but
      Parameters:
        `vwr` -
        `path` -
        `forDialog` -

    - #### getLocalPathForWritingFile

          public static java.lang.String getLocalPathForWritingFile(Viewer vwr,
                                                                    java.lang.String file)

    - #### fixDOSName

          public static java.lang.String fixDOSName(java.lang.String fileName)

      Switch \ for / only for DOS names such as C:\temp\t.xyz, not names like http://cactus.nci.nih.gov/chemical/structure/CC/C=C\CC
      Parameters:
        `fileName` -
      Returns:
        fixed name

    - #### stripPath

          public static java.lang.String stripPath(java.lang.String name)

    - #### determineSurfaceTypeIs

          public static java.lang.String determineSurfaceTypeIs(java.io.InputStream is)

    - #### isScriptType

          public static boolean isScriptType(java.lang.String fname)

    - #### isSurfaceType

          public static boolean isSurfaceType(java.lang.String fname)

    - #### determineSurfaceFileType

          public static java.lang.String determineSurfaceFileType(java.io.BufferedReader bufferedReader)

    - #### getManifestScriptPath

          public static java.lang.String getManifestScriptPath(java.lang.String manifest)

      check a JmolManifest for a reference to a script file (.spt)
      Parameters:
        `manifest` -
      Returns:
        null, "", or a directory entry in the ZIP file

    - #### getEmbeddedScript

          public static java.lang.String getEmbeddedScript(java.lang.String script)

    - #### getFileReferences

          public static void getFileReferences(java.lang.String script,
                                               javajs.util.Lst<java.lang.String> fileList)

    - #### setScriptFileReferences

          public static java.lang.String setScriptFileReferences(java.lang.String script,
                                                                 java.lang.String localPath,
                                                                 java.lang.String remotePath,
                                                                 java.lang.String scriptPath)

    - #### setScriptFileRefs

          private static java.lang.String setScriptFileRefs(java.lang.String script,
                                                            java.lang.String dataPath,
                                                            boolean isLocal)

      Sets all local file references in a script file to point to files within dataPath. If a file reference contains dataPath, then the file reference is left with that RELATIVE path. Otherwise, it is changed to a relative file name within that dataPath. Only file references starting with "file://" are changed.
      Parameters:
        `script` -
        `dataPath` -
        `isLocal` -
      Returns:
        revised script

    - #### cachePut

          void cachePut(java.lang.String key,
                        java.lang.Object data)

    - #### cacheGet

          public java.lang.Object cacheGet(java.lang.String key,
                                           boolean bytesOnly)

    - #### cacheClear

          void cacheClear()

    - #### cacheFileByNameAdd

          public int cacheFileByNameAdd(java.lang.String fileName,
                                        boolean isAdd)

    - #### cacheList

          public java.util.Map<java.lang.String,java.lang.Integer> cacheList()

    - #### getCanonicalName

          public java.lang.String getCanonicalName(java.lang.String pathName)

    - #### recachePngjBytes

          public void recachePngjBytes(java.lang.String fileName,
                                       byte[] bytes)

    - #### getPngjOrDroppedBytes

          private byte[] getPngjOrDroppedBytes(java.lang.String fullName,
                                               java.lang.String name)

    - #### getCachedPngjBytes

          private byte[] getCachedPngjBytes(java.lang.String pathName)

    - #### postByteArray

          public java.lang.String postByteArray(java.lang.String fileName,
                                                byte[] bytes)

      Specified by:
        `postByteArray` in interface `javajs.api.BytePoster`