- added more javadoc comments

- minor, fixed indentation

java/org/slub/rosetta/dps/repository/plugin/storage/nfs/SLUBStoragePlugin.java

@@ -17,14 +17,31 @@ import com.exlibris.digitool.common.dnx.DnxSection;
 import com.exlibris.digitool.common.dnx.DnxSectionRecord;
 import com.exlibris.dps.repository.plugin.storage.nfs.NFSStoragePlugin;
 
+import com.exlibris.digitool.common.storage.Fixity;
+import com.exlibris.digitool.common.storage.Fixity.FixityAlgorithm;
+
 /**
  * SLUBStoragePlugin
  * writes all IEs, files and so on into the same dir under yyyy/mm/dd/IEpid/
  * 
+ * HINT: this plugin is *only* useful to store AIPs (IEs + files) in
+ *       permanent storage. Otherwise it could not detect the IE-PID and
+ *       will report an error.
+ *
+ * the fixities will only be checked if files are stored (storeEntity()), 
+ * because the Rosetta API does not give enough information about available
+ * fixities by calling retrieveEntity() to read files, because only 
+ * a string containing the path is given. 
+ *
+ * Please note, that all undocumented codelines are in most cases copied from
+ * com.exlibris.dps.repository.plugin.storage.nfs.NFSStoragePlugin and I am
+ * unable to find full documentation.
+ *
  * @author andreas.romeyke@slub-dresden.de (Andreas Romeyke)
+ * @see com.exlibris.dps.repository.plugin.storage.nfs.NFSStoragePlugin
  */
 public class SLUBStoragePlugin extends NFSStoragePlugin {
-    private static final String DIR_ROOT = "DIR_ROOT";
+  private static final String DIR_ROOT = "DIR_ROOT"; /** {@inheritDoc} */
   private static final ExLogger log = ExLogger.getExLogger(SLUBStoragePlugin.class);
 
   public SLUBStoragePlugin() {
@@ -32,7 +49,26 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     log.info("SLUBStoragePlugin instantiated");
   }
 
-    /** copied from NFS Storage Plugin, enhanced with debugging info */
+  /** retrieves a list of available checksum fixities 
+   * @param storedEntityMetaData storedEntityMetaData 
+   * @return list of available fixities
+   */
+  protected List<Fixity> getAvailableFixities(StoredEntityMetaData storedEntityMetaData) {
+    List<Fixity> fixities = storedEntityMetaData.getFixities();
+    for (Iterator<Fixity> iter = fixities.iterator(); iter.hasNext(); ) {
+      Fixity element = iter.next();
+      log.info("getAvailableFixities fixity=" + element.toString() );
+    }
+    return fixities;
+  }
+
+  /** copied from NFS Storage Plugin, enhanced with debugging info, 
+   * stores InputStream on Storage in given format and does fixity check
+   * if written sucessfully
+   * @param is InputStream
+   * @param storedEntityMetadata storedEntityMetaData
+   * @return relative path to file
+   */
   @Override
   public String storeEntity(InputStream is, StoredEntityMetaData storedEntityMetadata) throws Exception {
     log.info("SLUBStoragePlugin.storeEntity() called");
@@ -42,6 +78,10 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     log.info("SLUBStoragePlugin.storeEntity() relativeDirectoryPath="+relativeDirectoryPath);
     File destFile = getStreamDirectory(relativeDirectoryPath, fileName);
     log.info("SLUBStoragePlugin.storeEntity() destfile.getAbsolutePath()="+destFile.getAbsolutePath());
+
+    // debug
+    // List<Fixity> fixities = getAvailableFixities( storedEntityMetadata );
+
     // better move/link
     if (canHandleSourcePath(storedEntityMetadata.getCurrentFilePath())) {
       is.close(); // close input stream so that 'move' can work, we don't use it anyway
@@ -53,7 +93,9 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     }
     String storedEntityIdentifier = relativeDirectoryPath + File.separator + fileName;
     log.info("SLUBStoragePlugin.storeEntity() storedEntityIdentifier="+storedEntityIdentifier);
+    // check if stored correctly 
     if(!checkFixity(storedEntityMetadata.getFixities(), storedEntityIdentifier)) {
+      log.error("error, SLUBStoragePlugin.storeEntity() has written corrupted files (checked via checkFixity()), storedEntityIdentifier="+storedEntityIdentifier);
       deleteEntity(storedEntityIdentifier); // delete corrupt files
       return null;
     }
@@ -66,13 +108,14 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
    * we need to findout the associated dnx document (IE),
    * get the creation date of the IE/SIP
    * and get the IE PID of the associated IE.
+   * @param storedEntityMetaData StoredEntityMetaData
+   * @return calculated relative path as String
    * returns the path as string
    */
   protected String getStreamRelativePath(StoredEntityMetaData storedEntityMetaData ) throws Exception {
     log.info("SLUBStoragePlugin AAB");
     String relativeDirectoryPath = File.separator;
     // get IE PID by calling IE-DNX record and search for ""internalIdentifierType" == "PID"
-        
     DnxDocument iedoc = storedEntityMetaData.getIeDnx();
     String entitytype = storedEntityMetaData.getEntityType().name();
     DnxSection iesec = iedoc.getSectionById("internalIdentifier");
@@ -86,11 +129,11 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     for (Iterator<DnxSectionRecord> iter = records.iterator(); iter.hasNext(); ) {
       DnxSectionRecord element = iter.next();
       if (element.getKeyById("internalIdentifierType").getValue().equals("PID")) {
-        		iepid = element.getKeyById("internalIdentifierValue").getValue();
+        iepid = element.getKeyById("internalIdentifierValue").getValue(); // found IEPID
         break;
       }
     }
-        // raise Exception if iepid is null
+    // raise Exception if IEPID is null
     if (null == iepid) {
       log.error ("SLUBStoragePlugin.getStreamRelativePath iesec="+iesec.toString() );
       throw new Exception("error, could not get IEPID for storedEntityMetaData:"+storedEntityMetaData.toString() +" of type " + entitytype);
@@ -105,6 +148,7 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     Date d = sdf.parse(datestring);
     date.setTime(d);
     log.info("SLUBStoragePlugin.getStreamRelativePath creation Date read=" + datestring + " parsed=" + date.toString());
+    // now create path in format /yyyy/MM/dd/IEPID/
     relativeDirectoryPath = relativeDirectoryPath + new SimpleDateFormat("yyyy").format(d);
     relativeDirectoryPath = relativeDirectoryPath + File.separator;
     relativeDirectoryPath = relativeDirectoryPath + new SimpleDateFormat("MM").format(d);
@@ -117,7 +161,9 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     return relativeDirectoryPath;
   }
 
-    /** copied from NFS Storage Plugin, enhanced with debugging info */
+  /** copied from NFS Storage Plugin, enhanced with debugging info,
+   * this combines full file path and creates parent directories if needed  {@inheritDoc} 
+   */
   protected File getStreamDirectory(String path, String fileName) {
     File newDir = new File(parameters.get(DIR_ROOT) + File.separator + path);
     log.info("SLUBStoragePlugin.getStreamDirectory path=" + path);
@@ -128,7 +174,7 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
     return new File(newDir.getAbsolutePath() + File.separator + fileName);
   }
 
-    /** copied from NFS Storage Plugin, enhanced with debugging info */
+  /** copied from NFS Storage Plugin, enhanced with debugging info, {@inheritDoc} */
   private boolean canHandleSourcePath(String srcPath) {
     try {
       File file = new File(srcPath);
@@ -138,5 +184,4 @@ public class SLUBStoragePlugin extends NFSStoragePlugin {
       return false;
     }
   }
- 
 }