| 50 | | ^(Describe your design here.)^ |
| | 50 | * BinData hierarchy: |
| | 51 | * Move all the BinData related classes to the package : {{{org.sophie2.base.commons.util.bindata}}} |
| | 52 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/BinData.java BinData] : Make BinData abstract class that will have a number of child classes. BinData has the following methods: |
| | 53 | * {{{public abstract int getSize()}}} -> Gets the size (in bytes) of this bin data. |
| | 54 | * {{{public abstract byte[] getBytes() throws BinSourceNotFoundException}}} -> Gets all the bytes of the BinData and if that is not possible throws the checked exception BinSourceNotFoundException. |
| | 55 | * {{{public BinData getSub(int begin, int end)}}} -> Gets BinData that holds access to a given range in the byte array source, of the BinData. By default it returns new SubBinData for the range. |
| | 56 | * {{{public byte[] getBytes(int begin, int end) throws BinSourceNotFoundException}}} -> Gets the bytes of the bin data from the 'begin' position to the 'end' position. The default implementation will allocate an array of bytes with the wanted size to be used by the implementations and will assert that the passed parameters are accurate. If the bytes can not by retrieved from the source the checked BinSourceNotFoundException is thrown. |
| | 57 | * {{{public static void transport(InputStream from, OutputStream to) throws IOException}}} -> A helper method for transporting bytes from one stream to another, its implementation is from the old BinData (now RawBinData). |
| | 58 | * Other helper methods should be put here if they are not used only by the old BinData (now RawBinData). |
| | 59 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/RawBinData.java RawBinData] : Represents embedded BinData, it's source byte array is in the memory. That is the old BinData. |
| | 60 | * It's immutable kind is changed to {{{@Immutable(kind = "raw-bin-data")}}} |
| | 61 | * The implementations of the BinData abstract methods are as they were before this task. The others use the default implementations to allocate byte aaray only, the checked BinSourceNotFoundException is not thrown anywhere, because the source is in the memory. |
| | 62 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/SubBinData.java SubBinData] : Used to work with parts of the byte array source of the BinData implementations. |
| | 63 | * It's constructor is private and factory methods are with package visibility, only BinData implementations can instantiate it. |
| | 64 | * It keeps as source the BinData that it subs... |
| | 65 | * Getting bytes from it just calls the {{{public byte[] getBytes(int begin, int end)}}} method of its source BinData with it's range. |
| | 66 | * Its {{{public BinData getSub(int begin, int end)}}} method calls the default implementation with given offset. |
| | 67 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/FileBinData.java FileBinData] : Used as linked to a local file (relative or absolute to a resource) BinData. |
| | 68 | * When bytes are demanded from it, it opens RandomFileAccess to its source file and seeks and reads from it. |
| | 69 | * The {{{public abstract int getSize()}}} method returns the size of the file in bytes. |
| | 70 | * When its source file is not found the checked exception BinSourceNotFoundException is thrown. The coders that use that BinData should handle the exception. |
| | 71 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/RemoteBinData.java RemoteBinData] (optional for that revision) : Communicates with a remote file source through the Facade. |
| | 72 | * It's methods use the Facade to retrieve their byte arrays and data. |
| | 73 | * On the server side there is RawBinData or FileBinData that provides the bytes or data demanded. |
| | 74 | * When the server is down, or the file on the server can not be retrieved the checked BinSourceNotFoundException is thrown. |
| | 75 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/main/java/org/sophie2/base/commons/util/bindata/BinSourceNotFoundException.java BinSourceNotFoundException] -> Thrown from the BinData implementations when their source could not be found. For example the FileBinData file source, or the RemoteBinData remote file source... |
| | 76 | * Some ideas for future revisions: |
| | 77 | * May be UploadBinData is needed for uploading big binary data. |
| | 78 | * May be StreamingBinData can be used as alternative to the RemoteBinData, it will not use the Facade but remote streaming service. |
| | 79 | * Media persistence: |
| | 80 | * Alter the current persist method of the {{{MediaResourceR4#KEY_DATA}}} key. |
| | 81 | * It should work with BinData, not only RawBinData |
| | 82 | * The logic if the BinData is RawBinData stays as it is. |
| | 83 | * With the src attribute, save and dataType to the storage. |
| | 84 | * [browser:branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.model.book/src/main/java/org/sophie2/base/model/book/persist/BinDataPersistType.java BinDataPersistType] is enumeration that defines what is the type of the BinData to be Types: |
| | 85 | * EMBEDDED -> used for RawBinData |
| | 86 | * LINKED_ABSOLUTE -> used for FileBinData with source file that has absolute path. |
| | 87 | * LINKED_RELATIVE -> used for FIleBinData with source, that has relative to the main resource file path. |
| | 88 | * REMOTE (optional) -> used for RemoteBinData. |
| | 89 | * The helper method {{{public static BinDataPersistType getPersistType(BinData data)}}} is used to get the dataType from a BinData instance. |
| | 90 | * The SubBinData should be used only for operating over parts of other BinDatas, so it should be not persistable. |
| | 91 | * An EnumPersister is registered for that enumeration. |
| | 92 | * When saving if type of the data is LINKED_ABSOLUTE, LINKED_RELATIVE or REMOTE as 'src' attribute just set the path to the file. |
| | 93 | * If the type is remote add child/attribute 'server account' and save the account to its server. (optional) |
| | 94 | * When loading: |
| | 95 | * if the type is not null (for old books) or EMBEDDED work with the logic as it is now. |
| | 96 | * If the type is LINKED_ABSOLUTE create a FileBinData with File for the path in the 'src' attribute. |
| | 97 | * If the type is LINKED_RELATIVE, get the path to the resource file it is relative from the PersistenceOptions. It is store when loading in the constant PersistenceUtil.LOCATION. That make FileBinData with file the File for the path stored in the 'src'attribute and parent the path to the resource file. |
| | 98 | * If it's remote make RemoteBinData with the path to the file stored in the 'src' attribute and Account the stored account (optional). |
| | 99 | * User inteface: |
| | 100 | * As in the analysis when importing media resources ask the user or link or embed the media. |
| | 101 | * The FileDialog's JFileChooser should be modified to have combo box with options how to import the binary data. |
| | 102 | * If modifying the FileDialog is impossible or hard and time taking for now use dialog with combo-box (radio buttons). |
| | 103 | * In the both cases the choices are: |
| | 104 | * Embed -> makes a RawBinData for the resource (as how it is now) |
| | 105 | * Link -> makes a FileBinData to a file with an absolute path on the file system. |
| | 106 | * Link and copy to _files (only for stored books) -> copies the file in a folder '_files' in the same folder as the stored book. Creates a FileBinData to a relative File in that folder, the File is relative to the book file (./_files/myMedia.dat for example). |
| | 107 | * For the server resources for now the bin data will be always RawBinData, saving a book on server will loose the big resources for now (BinSourceNotFoundException will be handled when these resources are used)... Uploading large data is not for this revision. |
| | 108 | * Other notes: |
| | 109 | * The media logics and resources work with BinData. |
| | 110 | * The Image resource and logics work with RawBinData (for now). |
| | 111 | * The new FileBinData works only for the media (for now). |
| | 112 | * Test |
| | 113 | * [browser:/branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/test/java/org/sophie2/base/commons/util/bindata/FileBinDataTest.java FileBinDataTest] |
| | 114 | * [browser:/branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/test/java/org/sophie2/base/commons/util/bindata/SubBinDataTest.java SubBinDataTest] |
| | 115 | * [browser:/branches/private/meddle/nfr_large_resources/modules/org.sophie2.base.commons/src/test/java/org/sophie2/base/commons/util/bindata/RemoteBinDataTest.java RemoteBinDataTest] (optional) |
| | 116 | * [browser:/branches/private/meddle/nfr_large_resources/modules/org.sophie2.main.func.media/src/test/java/org/sophie2/main/func/media/model/resources/MediaPersistenceTest.java MediaPersistenceTest] |
| | 117 | * Branch in the track browser: |
| | 118 | * [browser:/branches/private/meddle/nfr_large_resources] |
