refs #200: Create accouting-lib library

https://support.d4science.org/issues/200
Updating Javadoc

git-svn-id: https://svn.d4science.research-infrastructures.eu/gcube/trunk/accounting/accounting-lib@115556 82a268e6-3cf1-43bd-a215-b396298e98cf

src/main/java/org/gcube/accounting/datamodel/BasicUsageRecord.java

@@ -45,28 +45,43 @@ public abstract class BasicUsageRecord implements UsageRecord, Serializable {
 	private static Logger logger = LoggerFactory.getLogger(BasicUsageRecord.class);
 	
 	/**
-	 * An unique identifier for the UsageRecord
+	 * KEY for : The unique identifier for the UsageRecord.
+	 * The ID is automatically Created. Set the ID only if you really know what
+	 * you are going to do.
 	 */
 	@RequiredField @NotEmpty
-	public static final String ID = "id";
+	protected static final String ID = "id";
 	/**
-	 * The user (or the Consumer Identity, that in the S2S communication is 
+	 * KEY for : The user (or the Consumer Identity, that in the S2S 
-	 * another service) actually consuming the resource 
+	 * communication is another service).
 	 */
 	@RequiredField @NotEmpty
 	public static final String CONSUMER_ID = "consumerId";
 	/**
-	 * When the UR was created 
+	 * KEY for : The instant when the UR was created. The value will be recorded
+	 * in UTC milliseconds from the epoch.
 	 */
 	@RequiredField @ValidLong
 	public static final String CREATION_TIME = "creationTime";
 	
+	/**
+	 * Internal USE ONLY.
+	 * KEY for : The Class Name of the represented {#Usage Record}
+	 */
 	@RequiredField @NotEmpty
 	protected static final String USAGE_RECORD_TYPE = "usageRecordType";
+	
+	/**
+	 * KEY for : The accounting scope
+	 */
 	@RequiredField @NotEmpty
 	public static final String SCOPE = "scope";
 	
-	
+	/**
+	 * KEY for : The Operation Result of the accounted operation.
+	 * The value is expressed as 
+	 * {@link #org.gcube.accounting.datamodel.UsageRecord.OperationResult}
+	 */
 	@RequiredField @ValidOperationResult
 	public static final String OPERATION_RESULT = "operationResult";
 
@@ -78,13 +93,28 @@ public abstract class BasicUsageRecord implements UsageRecord, Serializable {
 	protected Set<String> requiredFields;
 	protected Set<String> computedFields;
 	
+	/**
+	 * KEY for : Used in aggregated record. Represent the left end of the time
+	 * interval covered by this {#Usage Record}
+	 * The value will be recorded in UTC milliseconds from the epoch.
+	 */
 	@AggregatedField @ValidLong
 	protected static final String START_TIME = "startTime";
+	/**
+	 * KEY for : Used in aggregated record. Represent the right end of the time
+	 * interval covered by this {#Usage Record}
+	 * The value will be recorded in UTC milliseconds from the epoch.
+	 */
 	@AggregatedField @ValidLong
 	protected static final String END_TIME = "endTime";
+	/**
+	 * Internal USE ONLY.
+	 * KEY for : Indicate that the record is an aggregation
+	 */
 	@AggregatedField @NotEmptyIfNotNull
 	protected static final String AGGREGATED = "aggregated";
 	
+	
 	protected Set<String> aggregatedFields;
 
 	

src/main/java/org/gcube/accounting/datamodel/UsageRecord.java

@@ -19,6 +19,8 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	public String getId();
 
 	/**
+	 * The ID is automatically Created by the implementation Class. 
+	 * Set the ID only if you really know what you are going to do.
 	 * Set the unique id for this {#UsageRecord}
 	 * @param id {#UsageRecord} Unique ID
 	 * @throws InvalidValueException
@@ -26,26 +28,30 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	public void setId(String id) throws InvalidValueException;
 	
 	/**
-	 * Return the identity of the entity that consumed the resource
+	 * Return the user (or the Consumer Identity, that in the S2S 
+	 * communication is another service)
 	 * @return Consumer ID
 	 */
 	public String getConsumerId();
 
 	/**
-	 * Set the identity of the entity that consumed the resource
+	 * Set the user (or the Consumer Identity, that in the S2S 
+	 * communication is another service)
 	 * @param consumerId Consumer ID
 	 * @throws InvalidValueException
 	 */
 	public void setConsumerId(String consumerId) throws InvalidValueException;
 	
 	/**
-	 * Return the creation time for this {#UsageRecord}
+	 * Return the instant when this {#UsageRecord} was created.
 	 * @return the creation time for this {#UsageRecord}
 	 */
 	public Calendar getCreationTime();
 
 	/**
-	 * Set the creation time for this {#UsageRecord}
+	 * The CreationTime is automatically created by the implementation Class. 
+	 * Set the CreationTime only if you really know what you are going to do.
+	 * Set the instant when this {#UsageRecord} was created.
 	 * @param creationTime creation time
 	 * @throws InvalidValueException
 	 */
@@ -53,8 +59,8 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	
 	
 	/**
-	 * Return the accounting scope of the {#UsageRecord} 
+	 * Return the scope of this {#UsageRecord} 
-	 * @return The Accounting scope of the {#UsageRecord} 
+	 * @return The scope of this {#UsageRecord} 
 	 */
 	public String getScope();
 	
@@ -65,21 +71,6 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	 */
 	public void setScope(String scope) throws InvalidValueException;
 	
-	/* *
-	 * Return the id of the usage record aggregating this, null if this record
-	 * has not been aggregated by any record.
-	 * @return Aggregated Id The ID of the aggregation Record
-	 * /
-	public String getAggregatedUsageRecordId();
-
-	/* *
-	 * Set the id of the usage record aggregating this
-	 * @param aggregatedId The ID of the aggregation Record
-	 * @throws InvalidValueException
-	 * /
-	public void setAggregatedUsageRecordId(String aggregatedId)  throws InvalidValueException;
-	*/
-	
 	/**
 	 * Return all resource-specific properties. The returned Map is a copy of
 	 * the internal representation. Any modification to the returned Map MUST
@@ -92,7 +83,6 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	 * Set all resource-specific properties, replacing existing ones
 	 */
 	public void setResourceProperties(Map<String, Serializable> resourceSpecificProperties) throws InvalidValueException;
-	
 
 	/**
 	 * Return the value of the given resource property.
@@ -111,7 +101,7 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	public void setResourceProperty(String key, Serializable value) throws InvalidValueException;
 	
 	/**
-	 * @return the Operation Result related to the accounted Usage Record
+	 * @return the Operation Result of the accounted operation.
 	 */
 	public OperationResult getOperationResult();
 	
@@ -124,7 +114,9 @@ public interface UsageRecord extends Comparable<UsageRecord>{
 	
 	
 	/**
-	 * Validate the Resource Record
+	 * Validate the Resource Record.
+	 * The validation check if all the Required Field are set and has valid 
+	 * value.
 	 * @throws InvalidValueException
 	 */
 	public void validate() throws InvalidValueException;