LMS-2789 Javadoc added, minor version number increased for GeneralInformationService

SVN: 24850

openbis/source/java/ch/systemsx/cisd/openbis/generic/server/api/v1/GeneralInformationService.java

@@ -203,7 +203,7 @@ public class GeneralInformationService extends AbstractServer<IGeneralInformatio
 
     public int getMinorVersion()
     {
-        return 16;
+        return 17;
     }
 
     private Map<String, List<RoleAssignmentPE>> getRoleAssignmentsPerSpace()

openbis_api/source/java/ch/systemsx/cisd/openbis/generic/shared/api/v1/IGeneralInformationService.java

@@ -102,11 +102,28 @@ public interface IGeneralInformationService extends IRpcService
     public List<Sample> searchForSamples(String sessionToken, SearchCriteria searchCriteria);
 
     /**
-     * Return all samples that match the search criteria. Available since minor version 16.
+     * Return all samples that match the search criteria. Available since minor version 17.
+     * <p>
+     * The fetch options set is interpreted by the following rules.
+     * <ul>
+     * <li>If it does not contain {@link SampleFetchOption#PROPERTIES} only the basic attributes are
+     * returned for all samples including possible ancestors and descendants.
+     * <li>{@link SampleFetchOption#CHILDREN} will be ignored if
+     * {@link SampleFetchOption#DESCENDANTS} is in the set.
+     * <li>{@link SampleFetchOption#PARENTS} will be ignored if {@link SampleFetchOption#ANCESTORS}
+     * is in the set.
+     * <li>It is possible to combine {@link SampleFetchOption#CHILDREN}/
+     * {@link SampleFetchOption#DESCENDANTS} with {@link SampleFetchOption#PARENTS}/
+     * {@link SampleFetchOption#ANCESTORS}.
+     * </ul>
+     * The samples of the returned list also contain appropriated fetch options sets which tells
+     * whether one can expect properties, children, or parents. Note, that only the top-level
+     * samples can have both children or samples. For descendants and ancestors navigation is
+     * possible only in one direction.
      * 
      * @param searchCriteria The sample metadata values to be matched against.
      * @param fetchOptions Options that control which parts of the samples are fetched.
-     * @since 1.16
+     * @since 1.17
      */
     public List<Sample> searchForSamples(String sessionToken, SearchCriteria searchCriteria,
             EnumSet<SampleFetchOption> fetchOptions);

openbis_api/source/java/ch/systemsx/cisd/openbis/generic/shared/api/v1/dto/SampleFetchOption.java

@@ -16,13 +16,42 @@
 
 package ch.systemsx.cisd.openbis.generic.shared.api.v1.dto;
 
+import ch.systemsx.cisd.openbis.generic.shared.api.v1.IGeneralInformationService;
 import ch.systemsx.cisd.openbis.generic.shared.basic.dto.FetchOption;
 
 /**
- * @author pkupczyk
+ * Fetch options for
+ * {@link IGeneralInformationService#searchForSamples(String, SearchCriteria, java.util.EnumSet)}.
+ * The {@link Sample} objects return by the search method also contain a fetch option (
+ * {@link Sample#getRetrievedFetchOptions()}) which tells which attributes are filled and which not.
+ * 
+ * @author Franz-Josef Elmer
  */
 public enum SampleFetchOption implements FetchOption
 {
-
-    BASIC, PROPERTIES, PARENTS, CHILDREN, ANCESTORS, DESCENDANTS
+    /**
+     * Samples will only basic attributes (id, code, type, space code, experiment identifier,
+     * registrator, registration date, modification date) but no properties.
+     */
+    BASIC,
+    /**
+     * Samples contain basic attributes and all properties.
+     */
+    PROPERTIES,
+    /**
+     * Samples contain also their parent samples.
+     */
+    PARENTS,
+    /**
+     * Samples contain also their children samples.
+     */
+    CHILDREN, 
+    /**
+     * Ask for all ancestors.
+     */
+    ANCESTORS,
+    /**
+     * Ask for all descendants.
+     */
+    DESCENDANTS
 }