JBoss.orgCommunity Documentation

Chapter 33. HTTPBackupAgent and backup client

33.1. Introduction
33.2. HTTPBackupAgent
33.2.1. HTTPBackupAgent methods
33.2.2. HTTPBackupAgent Configuration
33.3. Backup Client
33.4. Backup Client Usage
33.4.1. Building application
33.4.2. Running application
33.4.3. Getting information about backup service
33.4.4. Starting full backup
33.4.5. Starting full and incremental backup on a single workspace
33.4.6. Getting information about the current backups (in progress)
33.4.7. Getting information about the current backup by 'backup_id'
33.4.8. Stopping backup by "backup_id"
33.4.9. Getting information about the completed (ready to restore) backups
33.4.10. Restoring to workspace
33.4.11. Getting information about the current restore
33.5. Full example about creating backup and restoring it for workspace 'backup'
33.5.1. Creating backup
33.5.2. Getting information about current backups
33.5.3. Stopping backup by id
33.5.4. Deleting the workspace "backup" and close opened sessions on this workspace
33.5.5. Restoring the workspace "backup"
33.5.6. Getting information about restore for workspace /repository/backup

Warning

For this service, you should configure the org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister in order to save the changes of the repository configuration. See the eXo JCR Configuration article at chapter '2 Portal and Standalone configuration' .

33.1. Introduction

The service org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent is REST-based front-end to service org.exoplatform.services.jcr.ext.backup.BackupManager. HTTPBackupAgent is representation BackupManager to creation backup, restore, getting status of current or completed backup/restore, etc.

The backup client is http client for HTTPBackupAgent.

33.2. HTTPBackupAgent

The HTTPBackupAgent is based on REST (see details about the REST Framework).

HTTPBackupAgent is using POST and GET methods for request.

The HTTPBackupAgent allows :

  • Start backup

  • Stop backup

  • Restore from backup

  • Delete the workspace

  • Get information about backup service (BackupManager)

  • Get information about current backup / restores / completed backups

/rest/jcr-backup/start/{repo}/{ws}

Start backup on specific workspace

URL: http://host:port/rest/jcr-backup/start/{repo}/{ws}

Formats: json.

Method: POST

Parameters:

The BackupConfigBean:

header :
"Content-Type" = "application/json; charset=UTF-8"

body:
<JSON to BackupConfigBean>

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.BackupConfigBean :

{"incrementalRepetitionNumber":<Integer>,"incrementalBackupJobConfig":<JSON to BackupJobConfig>,
"backupType":<Integer>,"fullBackupJobConfig":<JSON to BackupJobConfig>,
"incrementalJobPeriod":<Long>,"backupDir":"<String>"}

Where :

backupType                  - the type of backup:
                                  0 - full backup only;
                                  1 - full and incremental backup.
backupDir                   - the path to backup folder;
incrementalJobPeriod        - the incremental job period;
incrementalRepetitionNumber - the incremental repetition number;
fullBackupJobConfig         - the configuration to full backup, JSON to BackupJobConfig;
incrementalJobPeriod        - the configuration to incremental backup, JSON to BackupJobConfig.

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.response.BackupJobConfig :

{"parameters":[<JSON to Pair>, ..., <JSON to pair> ],"backupJob":"<String>"}

Where:

backupJob  - the FQN (fully qualified name) to BackupJob class;
parameters - the list of JSON of Pair.

The JSON bean of org.exoplatform.services.jcr.ext.backup.server.bean.response.Pair :

{"name":"<String>","value":"<String>"}

Where:

name  - the name of parameter;
value - the value of parameter.

Returns:

/rest/jcr-backup/stop/{id}

Stop backup with identifier {id}.

URL: http://host:port/rest/jcr-backup/stop/{id}

Formats: plain text

Method: GET

Parameters:

Returns:

/rest/jcr-backup/info

Information about the backup service.

URL: http://host:port/rest/jcr-backup/info

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}

Delete the workspace from repository /{repo}/{ws}. With this service, you can delete any workspaces regardless of whether the workspace is a backup or has been copied to a backup.

URL: http://host:port/rest/jcr-backup/drop-workspace/{repo}/{ws}/{force-session-close}

Formats: plain text

Method: GET

Parameters:

Returns:

/rest/jcr-backup/info/backup

Information about the current and completed backups

URL: http://host:port/rest/jcr-backup/info/backup

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/info/backup/current Information about the current backups

URL: http://host:port/rest/jcr-backup/info/backup/current

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/info/backup/completed Information about the completed backups.

URL: http://host:port/rest/jcr-backup/info/backup/completed

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/info/backup/{repo}/{ws} Information about the current and completed backups for specific workspace.

URL: http://host:port/rest/jcr-backup/info/backup/{repo}/{ws}

Formats: json

Method: GET

Parameters:

Returns:

/rest/jcr-backup/info/backup/{id} Detailed information about a current or completed backup with identifier '{id}'.

URL: http://host:port/rest/jcr-backup/info/backup/{id}

Formats: json

Method: GET

Parameters:

Returns:

/rest/jcr-backup/info/restore/{repo}/{ws} The information about the last restore on a specific workspace /{repo}/{ws}.

URL: http://host:port/rest/jcr-backup/info/restore/{repo}/{ws}

Formats: json

Method: GET

Parameters:

Returns:

/rest/jcr-backup/info/restores

The information about the last restores.

URL: http://host:port/rest/jcr-backup/info/restores

Formats: json

Method: GET

Parameters: no

Returns:

/rest/jcr-backup/restore/{repo}/{id}

Restore the workspace from specific backup.

URL: http://host:port/rest/jcr-backup/restore/{repo}/{id}

Formats: json.

Method: POST

Parameters:

The RestoreBean:

header :
"Content-Type" = "application/json; charset=UTF-8"

body:
<JSON to WorkspaceEntry>

The example of JSON bean to org.exoplatform.services.jcr.config.WorkspaceEntry :

{ "accessManager" : null,
  "autoInitPermissions" : null,
  "autoInitializedRootNt" : null,
  "cache" : { "parameters" : [ { "name" : "max-size",
            "value" : "10k"
          },
          { "name" : "live-time",
            "value" : "1h"
          }
        ],
      "type" : "org.exoplatform.services.jcr.impl.dataflow.persistent.LinkedWorkspaceStorageCacheImpl"
    },
  "container" : { "parameters" : [ { "name" : "source-name",
            "value" : "jdbcjcr"
          },
          { "name" : "dialect",
            "value" : "hsqldb"
          },
          { "name" : "multi-db",
            "value" : "false"
          },
          { "name" : "update-storage",
            "value" : "false"
          },
          { "name" : "max-buffer-size",
            "value" : "200k"
          },
          { "name" : "swap-directory",
            "value" : "../temp/swap/production"
          }
        ],
      "type" : "org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer",
      "valueStorages" : [ { "filters" : [ { "ancestorPath" : null,
                  "minValueSize" : 0,
                  "propertyName" : null,
                  "propertyType" : "Binary"
                } ],
            "id" : "system",
            "parameters" : [ { "name" : "path",
                  "value" : "../temp/values/production"
                } ],
            "type" : "org.exoplatform.services.jcr.impl.storage.value.fs.TreeFileValueStorage"
          } ]
    },
  "initializer" : { "parameters" : [ { "name" : "root-nodetype",
            "value" : "nt:unstructured"
          } ],
      "type" : "org.exoplatform.services.jcr.impl.core.ScratchWorkspaceInitializer"
    },
  "lockManager" : { "persister" : { "parameters" : [ { "name" : "path",
                "value" : "../temp/lock/system"
              } ],
          "type" : "org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister"
        },
      "timeout" : 15728640
    },
  "name" : "production",
  "queryHandler" : { "analyzer" : {  },
      "autoRepair" : true,
      "bufferSize" : 10,
      "cacheSize" : 1000,
      "documentOrder" : true,
      "errorLogSize" : 50,
      "excerptProviderClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt",
      "excludedNodeIdentifers" : null,
      "extractorBackLogSize" : 100,
      "extractorPoolSize" : 0,
      "extractorTimeout" : 100,
      "indexDir" : "../temp/jcrlucenedb/production",
      "indexingConfigurationClass" : "org.exoplatform.services.jcr.impl.core.query.lucene.IndexingConfigurationImpl",
      "indexingConfigurationPath" : null,
      "maxFieldLength" : 10000,
      "maxMergeDocs" : 2147483647,
      "mergeFactor" : 10,
      "minMergeDocs" : 100,
      "parameters" : [ { "name" : "index-dir",
            "value" : "../temp/jcrlucenedb/production"
          } ],
      "queryClass" : "org.exoplatform.services.jcr.impl.core.query.QueryImpl",
      "queryHandler" : null,
      "resultFetchSize" : 2147483647,
      "rootNodeIdentifer" : "00exo0jcr0root0uuid0000000000000",
      "spellCheckerClass" : null,
      "supportHighlighting" : false,
      "synonymProviderClass" : null,
      "synonymProviderConfigPath" : null,
      "type" : "org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex",
      "useCompoundFile" : false,
      "volatileIdleTime" : 3
    },
  "uniqueName" : "repository_production"
}

Returns:

/rest/jcr-backup/info/default-ws-config Will be returned the JSON bean to WorkspaceEntry for default workspace.

URL: http://host:port/rest/jcr-backup/info/default-ws-config

Formats: json

Method: GET

Parameters: no

Returns:

Add the components org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent and org.exoplatform.services.jcr.ext.backup.BackupManager to services configuration :

<component>
  <type>org.exoplatform.services.jcr.ext.backup.server.HTTPBackupAgent</type>
</component>

<component>
  <key>org.exoplatform.services.jcr.ext.backup.BackupManager</key>
  <type>org.exoplatform.services.jcr.ext.backup.impl.BackupManagerImpl</type>
  <init-params>
    <properties-param>
      <name>backup-properties</name>
      <property name="default-incremental-job-period" value="3600" /> <!-- set default incremental periond = 60 minutes -->
      <property name="full-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob" />
      <property name="incremental-backup-type" value="org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob" />
      <property name="backup-dir" value="../temp/backup" />
    </properties-param>
  </init-params>
</component>

33.3. Backup Client

Backup client is console application.

The backup client is http client for HTTPBackupAgent.

Command signature:

Help info:
 <url> <cmd> 
 <url>  :   http(s)//login:password@host:port/<context> 
 <cmd>  :   start <repo/ws> <backup_dir> [<incr>] 
            stop <backup_id> 
            status <backup_id> 
            restores <repo/ws> 
            restore <repo/ws> <backup_id> <pathToConfigFile> 
            list [completed] 
            info 
            drop [force-close-session] <repo/ws>  
            help  

 start          - start backup 
 stop           - stop backup 
 status         - information about the current or completed backup by 'backup_id' 
 restores       - information about the last restore on specific workspace 
 restore        - restore the workspace from specific backup 
 list           - information about the current backups (in progress) 
 list completed - information about the completed (ready to restore) backups 
 info           - information about the service backup 
 drop           - delete the workspace 
 help           - print help information about backup console 

 <repo/ws>           - /<reponsitory-name>/<workspace-name>  the workspace 
 <backup_dir>        - path to folder for backup on remote server 
 <backup_id>         - the identifier for backup 
 <incr>              - incemental job period 
 <pathToConfigFile>  - path (local) to workspace configuration 
 force-close-session - close opened sessions on workspace.

33.4. Backup Client Usage

Note

${JCR-SRC-HOME} the path where eXo JCR sources located

jcrbackup http://root:exo@127.0.0.1:8080 info

Return :

The backup service information : 
  full backup type               : org.exoplatform.services.jcr.ext.backup.impl.fs.FullBackupJob
  incremetal backup type         : org.exoplatform.services.jcr.ext.backup.impl.fs.IncrementalBackupJob
  backup log folder              : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
  default incremental job period : 3600

Start full backup only on workspace "backup", the parameter <bakcup_dir> (../temp/backup) should be exists:

jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup

Return :

Successful : 
  status code = 200

Start full and incremental backup on workspace "production":

jcrbackup http://root:exo@127.0.0.1:8080 start /repository/production ../temp/backup 10000

Return :

Successful : 
 tatus code = 200
jcrbackup http://root:exo@127.0.0.1:8080 list

Return :

The current backups information : 
  1) Backup with id b46370107f000101014b03ea5fbe8d54 :
    repository name           : repository
    workspace name            : production
    backup type               : full + incremetal
    full backup state         : finished
    incremental backup state  : working
    started time              : Fri, 17 Apr 2009 17:03:16 EEST
  2) Backup with id b462e4427f00010101cf243b4c6015bb :
    repository name           : repository
    workspace name            : backup
    backup type               : full only
    full backup state         : finished
    started time              : Fri, 17 Apr 2009 17:02:41 EEST
jcrbackup http://root:exo@127.0.0.1:8080 status b46370107f000101014b03ea5fbe8d54

return:

The current backup information : 
    backup id                : b46370107f000101014b03ea5fbe8d54
    backup folder            : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
    repository name          : repository
    workspace name           : production
    backup type              : full + incremetal
    full backup state        : finished
    incremental backup state : working
    started time             : Fri, 17 Apr 2009 17:03:16 EEST
jcrbackup http://root:exo@127.0.0.1:8080 stop 6c302adc7f00010100df88d29535c6ee

Return:

Successful : 
  status code = 200
jcrbackup http://root:exo@127.0.0.1:8080 list completed

Return:

The completed (ready to restore) backups information : 
  1) Backup with id adf6fadc7f00010100053b2cba43513c :
    repository name           : repository
    workspace name            : backup
    backup type               : full only
    started time              : Thu, 16 Apr 2009 11:07:05 EEST

  2) Backup with id b46370107f000101014b03ea5fbe8d54 :
    repository name           : repository
    workspace name            : production
    backup type               : full + incremetal
    started time              : Fri, 17 Apr 2009 17:03:16 EEST

  3) Backup with id aec419cc7f000101004aca277b2b4e9f :
    repository name           : repository
    workspace name            : backup8
    backup type               : full only
    started time              : Thu, 16 Apr 2009 14:51:08 EEST

Restore to workspace "backup3", for restore need the <backup_id> of completed backup and path to file with workspace configuration:

jcrbackup http://root:exo@127.0.0.1:8080 restore /repository/backup3 6c302adc7f00010100df88d29535c6ee /home/rainf0x/java/exo-working/JCR-839/exo-jcr-config_backup3.xml

Return:

Successful : 
  status code = 200

Get information about the current restore for workspace /repository/backup3:

jcrbackup http://root:exo@127.0.0.1:8080 restores

Return:

The current restores information : 
1) Restore with id 6c302adc7f00010100df88d29535c6ee:
    full backup date        : 2009-04-03T16:34:37.394+03:00
    backup log file         : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup/backup-6c302adc7f00010100df88d29535c6ee.xml
    repository name         : repository
    workspace name          : backup3
    backup type             : full only
    path to backup folder   : /home/rainf0x/java/exo-working/JCR-839/exo-tomcat/bin/../temp/backup
    restore state           : successful

33.5. Full example about creating backup and restoring it for workspace 'backup'

jcrbackup http://root:exo@127.0.0.1:8080 start /repository/backup ../temp/backup 10000

Return :

Successful : 
  status code = 200
jcrbackup http://root:exo@127.0.0.1:8080 list

Return :

The current backups information : 
  1) Backup with id b469ba957f0001010178febaedf20eb7 :
    repository name           : repository
    workspace name            : backup
    backup type               : full + incremetal
    full backup state         : finished
    incremental backup state  : working
    started time              : Fri, 17 Apr 2009 17:10:09 EEST

Stop backup with id b469ba957f0001010178febaedf20eb7 :

jcrbackup http://root:exo@127.0.0.1:8080 stop b469ba957f0001010178febaedf20eb7

Return :

Successful : 
  status code = 200
jcrbackup http://root:exo@127.0.0.1:8080 drop force-close-session /repository/backup

Return :

Successful : 
  status code = 200
jcrbackup http://root:exo@127.0.0.1:8080 restores /repository/backup

Return:

The current restores information : 
  Restore with id b469ba957f0001010178febaedf20eb7:
    backup folder           : /home/rainf0x/java/exo-working/JCR-839/new_JCR/exo-tomcat/bin/../temp/backup
    repository name         : repository
    workspace name          : backup
    backup type             : full + incremetal
    restore state           : successful
    started time            : Fri, 17 Apr 2009 16:38:00 EEST
    finished time           : Fri, 17 Apr 2009 16:38:00 EEST