DefaultUWSBackupManager

java.lang.Object
- uws.service.backup.DefaultUWSBackupManager

All Implemented Interfaces:

UWSBackupManager
```
public class DefaultUWSBackupManager
extends java.lang.Object
implements UWSBackupManager
```
Default implementation of the interface UWSBackupManager.

With this class, a UWS can be saved and restored easily thanks to saveAll() and restoreAll(). It is saved in JSON and in one or several files in function of the backup mode:
- by user: one file for each user. The file contains all the information about the user and all the jobs he owns.
- in one file: one file to describe all users and all the jobs.
The backup frequency can also be changed and may have 2 special values:
- AT_USER_ACTION (=0): only the jobs of the user which has just created, destroyed, executed or stopped a job are saved. This frequency is possible only if the backup mode is by user.
- MANUAL (=-1): you must call yourself the function saveAll() to save the UWS.
Another positive value will be considered as the frequency (in milliseconds) of the automatic backup (= saveAll()).
Version:

4.4 (08/2018)

Author:

Grégory Mantelet (CDS;ARI)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`protected static class`	`DefaultUWSBackupManager.JSONArrayReader` Lets reading a JSON array from a `JSONTokener` (that's to directly from a file) as an iterator which returns all items which MUST BE `JSONObject`s.
`protected static class`	`DefaultUWSBackupManager.JSONObjectReader` Lets reading a JSON object from a `JSONTokener` (that's to say directly from a file), as an iterator which returns all the keys.
`protected static class`	`DefaultUWSBackupManager.SingleInputIterator` An iterator of input streams with ONLY ONE input stream.

Field Summary

Fields
Modifier and Type	Field and Description
`static long`	`AT_USER_ACTION` Special frequency to mean that this manager wait a user action (create, update, start, abort, destruction) to save the jobs of this user.
`protected long`	`backupFreq` Backup frequency (in milliseconds).
`protected boolean`	`byUser` Backup mode: one file by user or one file for all jobs and users.
`static long`	`DEFAULT_FREQUENCY` Default backup frequency.
`protected boolean`	`enabled` Tells whether the backup (and particularly the automatic one) of the associated UWS is enabled or not.
`protected java.util.Date`	`lastBackup` Date of the last backup.
`protected java.util.Date`	`lastRestoration` Date of the last restoration.
`static long`	`MANUAL` Special frequency to mean that this manager will NOT save automatically the UWS.
`protected java.util.Timer`	`timAutoBackup` Timer which saves the backup each backupFreq milliseconds.
`protected UWS`	`uws` The UWS to restore/save.

Constructor Summary

Constructors
Constructor and Description
`DefaultUWSBackupManager(UWS uws)` Builds a backup manager in the mode "auto": one file for all users and all jobs, and the backup is done all minutes (see `DEFAULT_FREQUENCY`.
`DefaultUWSBackupManager(UWS uws, boolean byUser)` Builds a backup manager in the given mode: "by user" (one file for each user and the backup is done at each user action) or not (one file for all users and all jobs and the backup is done all minutes (see `DEFAULT_FREQUENCY`)).
`DefaultUWSBackupManager(UWS uws, boolean byUser, long frequency)` Builds a backup manager in the given mode and with the given frequency.
`DefaultUWSBackupManager(UWS uws, long frequency)` Builds a backup manager in the mode "auto" or "manual": one file for all users and all jobs, and the backup is done at the given frequency.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected byte[]`	`fromBase64(java.lang.String base64Str)` Decode the given Base-64 string into a bytes array.
`long`	`getBackupFreq()` Gets the backup frequency.
`protected ErrorSummary`	`getError(org.json.JSONObject obj)` Builds the error summary corresponding to the given JSON object.
`protected org.json.JSONObject`	`getJSONJob(UWSJob job, java.lang.String jlName)` Serializes the given job into a JSON object.
`protected java.lang.Object`	`getJSONJobInfo(JobInfo jobInfo)` Serialize the given `JobInfo` so that being able later to restore this exact object as provided.
`protected org.json.JSONObject`	`getJSONUser(JobOwner user)` Serializes the given user into a JSON object.
`java.util.Date`	`getLastBackup()` Gets the date of the last backup.
`java.util.Date`	`getLastRestoration()` Gets the date of the last restoration
`UWSLog`	`getLogger()` Gets the logger of its UWS, or the default one if it is unknown.
`protected java.util.Map<java.lang.String,java.lang.Object>`	`getParameters(org.json.JSONObject obj)` Builds the list of parameters corresponding to the given JSON object.
`protected Result`	`getResult(org.json.JSONObject obj)` Builds the result corresponding to the given JSON object.
`protected java.util.List<Result>`	`getResults(org.json.JSONArray array)` Builds the list of results corresponding to the given JSON array.
`protected UploadFile`	`getUploadFile(org.json.JSONObject obj)` Build the upload file corresponding to the given JSON object.
`protected org.json.JSONObject`	`getUploadJson(UploadFile upl)` Get the JSON representation of the given `UploadFile`.
`protected JobOwner`	`getUser(org.json.JSONObject json)` Builds the instance of `JobOwner` corresponding to the given JSON object.
`boolean`	`isEnabled()` Tells whether this backup manager is enabled or not.
`int[]`	`restoreAll()` Restore all jobs list and all information about the jobs owners.
`protected boolean`	`restoreJob(org.json.JSONObject json, java.util.Map<java.lang.String,JobOwner> users)` Builds the job corresponding to the given JSON object and then restore it in the UWS.
`protected JobInfo`	`restoreJobInfo(java.lang.Object jsonValue)` Restore the JobInfo referenced or represented by the given JSON value.
`protected void`	`restoreOtherJobParams(org.json.JSONObject json, UWSJob job)` Restores other job parameters, either from the given JSON object or from the parameters map of the given job.
`int[]`	`saveAll()` Save all jobs lists and all information about the jobs owners.
`int[]`	`saveOwner(JobOwner user)` Save ONLY the jobs of the given user and all information about this user.
`protected int[]`	`saveOwner(JobOwner user, boolean fromSaveAll)`
`void`	`setBackupFreq(long freq)` Sets the backup frequency.
`void`	`setEnabled(boolean enabled)` Enables/Disables the backup of the associated UWS.
`protected java.lang.String`	`toBase64(byte[] bytes)` Encode the given bytes into a Base-64 string.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - AT_USER_ACTION
```
public static final long AT_USER_ACTION
```
    Special frequency to mean that this manager wait a user action (create, update, start, abort, destruction) to save the jobs of this user.
    
    See Also:
    
    Constant Field Values
  - MANUAL
```
public static final long MANUAL
```
    Special frequency to mean that this manager will NOT save automatically the UWS. The function saveAll() MUST be explicitly called.
    
    See Also:
    
    Constant Field Values
  - DEFAULT_FREQUENCY
```
public static final long DEFAULT_FREQUENCY
```
    Default backup frequency. 60000ms = 60s = 1min
    
    See Also:
    
    Constant Field Values
  - lastRestoration
```
protected java.util.Date lastRestoration
```
    Date of the last restoration.
  - lastBackup
```
protected java.util.Date lastBackup
```
    Date of the last backup.
  - uws
```
protected final UWS uws
```
    The UWS to restore/save.
  - enabled
```
protected boolean enabled
```
    Tells whether the backup (and particularly the automatic one) of the associated UWS is enabled or not.
  - byUser
```
protected final boolean byUser
```
    Backup mode: one file by user or one file for all jobs and users.
  - backupFreq
```
protected long backupFreq
```
    Backup frequency (in milliseconds).
  - timAutoBackup
```
protected java.util.Timer timAutoBackup
```
    Timer which saves the backup each backupFreq milliseconds.
- Constructor Detail
  - DefaultUWSBackupManager
```
public DefaultUWSBackupManager(UWS uws)
```
    Builds a backup manager in the mode "auto": one file for all users and all jobs, and the backup is done all minutes (see DEFAULT_FREQUENCY.
    
    Parameters:
    
    uws - The UWS to save/restore.
    
    See Also:
    
    DefaultUWSBackupManager(UWS, long)
  - DefaultUWSBackupManager
```
public DefaultUWSBackupManager(UWS uws,
                               long frequency)
```
    Builds a backup manager in the mode "auto" or "manual": one file for all users and all jobs, and the backup is done at the given frequency.
    
    If the given frequency is 0 or negative (see MANUAL), the backup will not be done automatically. You must manually save the UWS thanks to the function saveAll().
    
    If the given frequency is positive, the backup will be done automatically at the given frequency.
    
    Parameters:
    
    uws - The UWS to save/restore.
    
    frequency - The backup frequency (in ms ; MUST BE positive and different from 0. If negative or 0, the frequency will be automatically set to DEFAULT_FREQUENCY).
  - DefaultUWSBackupManager
```
public DefaultUWSBackupManager(UWS uws,
                               boolean byUser)
                        throws UWSException
```
    Builds a backup manager in the given mode: "by user" (one file for each user and the backup is done at each user action) or not (one file for all users and all jobs and the backup is done all minutes (see DEFAULT_FREQUENCY)).
    
    Parameters:
    
    uws - The UWS to save/restore.
    
    byUser - Backup mode.
    
    Throws:
    
    UWSException - If the user identification is disabled (that's to say, if the given UWS has no UserIdentifier) while the parameter byUser is true.
    
    See Also:
    
    DefaultUWSBackupManager(UWS, boolean, long)
  - DefaultUWSBackupManager
```
public DefaultUWSBackupManager(UWS uws,
                               boolean byUser,
                               long frequency)
                        throws UWSException
```
    Builds a backup manager in the given mode and with the given frequency.
    
    Parameters:
    
    uws - The UWS to save/restore.
    
    byUser - Backup mode (true means one file for each user and false, one file for all users and jobs).
    
    frequency - Backup frequency (AT_USER_ACTION, MANUAL, DEFAULT_FREQUENCY, or a positive value).
    
    Throws:
    
    UWSException - If the user identification is disabled (that's to say, if the given UWS has no UserIdentifier) while the parameter byUser is true.
- Method Detail
  - isEnabled
```
public final boolean isEnabled()
```
    Tells whether this backup manager is enabled or not.
    
    Returns:
    
    true if the backup is enabled, false otherwise.
  - setEnabled
```
public final void setEnabled(boolean enabled)
```
    Description copied from interface: UWSBackupManager
    
    Enables/Disables the backup of the associated UWS.
    
    Specified by:
    
    setEnabled in interface UWSBackupManager
    
    Parameters:
    
    enabled - true to enable the backup, false otherwise.
  - getBackupFreq
```
public final long getBackupFreq()
```
    Gets the backup frequency.
    
    Returns:
    
    The backup frequency (in milliseconds).
  - setBackupFreq
```
public final void setBackupFreq(long freq)
```
    Sets the backup frequency.
    
    note 1: A negative frequency will be interpreted as "manual".. that's to say you will have to call yourself the saveAll() method to save the UWS.
    
    note 2: Nothing will be done if the given frequency is AT_USER_ACTION although the current backup mode is "by user".
    
    Parameters:
    
    freq - The new backup frequency (in milliseconds) (AT_USER_ACTION, MANUAL, DEFAULT_FREQUENCY or any other positive value).
  - getLastRestoration
```
public final java.util.Date getLastRestoration()
```
    Gets the date of the last restoration
    
    Returns:
    
    The date of the last restoration (MAY BE NULL).
  - getLastBackup
```
public final java.util.Date getLastBackup()
```
    Gets the date of the last backup.
    
    Returns:
    
    The date of the last backup (MAY BE NULL).
  - getLogger
```
public UWSLog getLogger()
```
    Gets the logger of its UWS, or the default one if it is unknown.
    
    Returns:
    
    A logger.
    
    See Also:
    
    UWS.getLogger(), UWSToolBox.getDefaultLogger()
  - saveAll
```
public int[] saveAll()
```
    Description copied from interface: UWSBackupManager
    
    Save all jobs lists and all information about the jobs owners.
    
    Specified by:
    
    saveAll in interface UWSBackupManager
    
    Returns:
    
    An array with the following information: number of saved jobs, number of all jobs, number of saved users and number of all users. null or an empty array is returned if there is a grave error while saving the whole UWS or the backup is disabled.
  - saveOwner
```
public int[] saveOwner(JobOwner user)
```
    Description copied from interface: UWSBackupManager
    
    Save ONLY the jobs of the given user and all information about this user.
    
    Specified by:
    
    saveOwner in interface UWSBackupManager
    
    Returns:
    
    An array with the following information: number of saved jobs, number of all jobs. null or an empty array is returned if there is a grave error while saving the whole UWS or the backup is disabled.
  - saveOwner
```
protected int[] saveOwner(JobOwner user,
                          boolean fromSaveAll)
```
  - getJSONUser
```
protected org.json.JSONObject getJSONUser(JobOwner user)
                                   throws org.json.JSONException
```
    Serializes the given user into a JSON object.
```
 {
        "id": "...",
        "pseudo": "...",
        ...
 }
 
```
    note: the last suspension points mean that other user data may be added into this JSON object. These other user data to save MUST BE given by JobOwner.getDataToSave().
    Parameters:
    
    user - The user to save.
    
    Returns:
    
    Its JSON representation.
    
    Throws:
    
    org.json.JSONException - If there is an error while building the JSON object.
  - getJSONJob
```
protected org.json.JSONObject getJSONJob(UWSJob job,
                                         java.lang.String jlName)
                                  throws UWSException,
                                         org.json.JSONException
```
    Serializes the given job into a JSON object.
    
    note: the structure of the returned JSON object is decided by Json4Uws.getJson(UWSJob). Only one attribute is added: "jobListName".
    
    Parameters:
    
    job - The job to save.
    
    jlName - Name of the jobs list containing the given job.
    
    Returns:
    
    The JSON representation of the given job.
    
    Throws:
    
    UWSException - If there is an error while getting job parameters and serializing them.
    
    org.json.JSONException - If there is an error while building the JSON object.
  - getJSONJobInfo
```
protected java.lang.Object getJSONJobInfo(JobInfo jobInfo)
                                   throws UWSException,
                                          org.json.JSONException
```
    Serialize the given JobInfo so that being able later to restore this exact object as provided.
    By default, this function use the Java Class serialization (see Serializable) and save the corresponding bytes into a Base-64 string.
    
    Parameters:
    
    jobInfo - The jobInfo to backup.
    
    Returns:
    
    The string to use in order to restore the given jobInfo (e.g. a Base-64 serialization of the Java Object, a URL, ...).
    
    Throws:
    
    UWSException - If any error occurs while representing the given JobInfo.
    
    org.json.JSONException - If any error occurs while manipulating a JSON object or array.
    
    Since:
    
    4.2
  - restoreJobInfo
```
protected JobInfo restoreJobInfo(java.lang.Object jsonValue)
                          throws UWSException,
                                 org.json.JSONException
```
    Restore the JobInfo referenced or represented by the given JSON value.
    By default, this function considers that the given value is a Base-64 string encoding the Java Class serialization (see Serializable) of the JobInfo to restore.
    
    Parameters:
    
    jsonValue - The reference or backup representation of the JobInfo to restore.
    
    Returns:
    
    The restored JobInfo.
    
    Throws:
    
    UWSException - If any error occurs while restoring the JobInfo.
    
    org.json.JSONException - If any error occurs while manipulating a JSON object or array.
    
    Since:
    
    4.2
  - toBase64
```
protected final java.lang.String toBase64(byte[] bytes)
```
    Encode the given bytes into a Base-64 string.
    
    Parameters:
    
    bytes - Bytes to encode.
    
    Returns:
    
    Base-64 encoded string.
    
    Since:
    
    4.4
    
    See Also:
    
    fromBase64(String)
  - fromBase64
```
protected final byte[] fromBase64(java.lang.String base64Str)
```
    Decode the given Base-64 string into a bytes array.
    
    Parameters:
    
    base64Str - Base-64 string to decode.
    
    Returns:
    
    Decoded bytes.
    
    Since:
    
    4.4
    
    See Also:
    
    toBase64(byte[])
  - getUploadJson
```
protected org.json.JSONObject getUploadJson(UploadFile upl)
                                     throws org.json.JSONException
```
    Get the JSON representation of the given UploadFile.
    
    Parameters:
    
    upl - The uploaded file to serialize in JSON.
    
    Returns:
    
    Its JSON representation.
    
    Throws:
    
    org.json.JSONException - If there is an error while building the JSON object.
    
    Since:
    
    4.1
  - restoreAll
```
public int[] restoreAll()
```
    Description copied from interface: UWSBackupManager
    
    Restore all jobs list and all information about the jobs owners.
    
    Specified by:
    
    restoreAll in interface UWSBackupManager
    
    Returns:
    
    An array with the following information: number of restored jobs, number of all jobs, number of restored users and number of all users. null or an empty array is returned if there is a grave error while saving the whole UWS.
  - getUser
```
protected JobOwner getUser(org.json.JSONObject json)
                    throws UWSException
```
    Builds the instance of JobOwner corresponding to the given JSON object.
    
    Parameters:
    
    json - JSON representation of the user to build.
    
    Returns:
    
    The corresponding instance of JobOwner or null if the given object is empty.
    
    Throws:
    
    UWSException - If the "id" parameter is missing (a user MUST have an id ; warning: the case sensitivity is enabled only for this attribute).
    
    See Also:
    
    JobOwner.restoreData(Map)
  - restoreJob
```
protected boolean restoreJob(org.json.JSONObject json,
                             java.util.Map<java.lang.String,JobOwner> users)
                      throws UWSException
```
    Builds the job corresponding to the given JSON object and then restore it in the UWS.
    
    Parameters:
    
    json - The JSON representation of the job to restore.
    
    users - The list of all fetched users.
    
    Returns:
    
    true if the corresponding job has been successfully restored, false otherwise.
    
    Throws:
    
    UWSException - If the job ID or the job list name is missing, or if the job list name is incorrect, or if there is an error with "parameters", "error" and "results".
  - restoreOtherJobParams
```
protected void restoreOtherJobParams(org.json.JSONObject json,
                                     UWSJob job)
                              throws UWSException
```
    Restores other job parameters, either from the given JSON object or from the parameters map of the given job. The job is supposed to be updated after the call of this function.
    
    note: By default, this function does nothing ! It is called by restoreJob(JSONObject, Map) just after the default restoration from the given JSON and just before to add the job in its dedicated jobs list.
    
    Parameters:
    
    json - JSON backup of the given job.
    
    job - Default restoration of the job.
    
    Throws:
    
    UWSException - If there is an error while restoring other job parameters.
    
    See Also:
    
    restoreJob(JSONObject, Map)
  - getParameters
```
protected java.util.Map<java.lang.String,java.lang.Object> getParameters(org.json.JSONObject obj)
```
    Builds the list of parameters corresponding to the given JSON object.
    
    Parameters:
    
    obj - The JSON representation of a parameters list.
    
    Returns:
    
    The corresponding list of parameters or null if the given object is empty.
  - getUploadFile
```
protected UploadFile getUploadFile(org.json.JSONObject obj)
```
    Build the upload file corresponding to the given JSON object.
    
    Parameters:
    
    obj - The JSON representation of the UploadFile to get.
    
    Returns:
    
    The corresponding UploadFile.
    
    Since:
    
    4.1
  - getResults
```
protected java.util.List<Result> getResults(org.json.JSONArray array)
                                     throws UWSException
```
    Builds the list of results corresponding to the given JSON array.
    
    Parameters:
    
    array - The JSON representation of the results to restore.
    
    Returns:
    
    The corresponding list of results or null if the array is empty.
    
    Throws:
    
    UWSException - If there is an error while restoring one of the result.
    
    See Also:
    
    getResult(JSONObject)
  - getResult
```
protected Result getResult(org.json.JSONObject obj)
                    throws org.json.JSONException,
                           UWSException
```
    Builds the result corresponding to the given JSON object.
    
    Parameters:
    
    obj - The JSON representation of the result to restore.
    
    Returns:
    
    The corresponding result or null if the given object is empty.
    
    Throws:
    
    org.json.JSONException - If there is an error while reading the JSON.
    
    UWSException
  - getError
```
protected ErrorSummary getError(org.json.JSONObject obj)
                         throws UWSException
```
    Builds the error summary corresponding to the given JSON object.
    
    Parameters:
    
    obj - The JSON representation of the error summary to restore.
    
    Returns:
    
    The corresponding error summary or null if the given object is empty.
    
    Throws:
    
    UWSException

Class DefaultUWSBackupManager

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

AT_USER_ACTION

MANUAL

DEFAULT_FREQUENCY

lastRestoration

lastBackup

uws

enabled

byUser

backupFreq

timAutoBackup

Constructor Detail

DefaultUWSBackupManager

DefaultUWSBackupManager

DefaultUWSBackupManager

DefaultUWSBackupManager

Method Detail

isEnabled

setEnabled

getBackupFreq

setBackupFreq

getLastRestoration

getLastBackup

getLogger

saveAll

saveOwner

saveOwner

getJSONUser

getJSONJob

getJSONJobInfo

restoreJobInfo

toBase64

fromBase64

getUploadJson

restoreAll

getUser

restoreJob

restoreOtherJobParams

getParameters

getUploadFile

getResults

getResult

getError