Ace:JSON Interface

The following functionality is visible through a JSON interface. To generate JSON output, append json=1 to the request on any supported servlet.

/Status

Returns an overview of all collections in the current ACE installation

Parameters

• none

Output

A list containing the replication details for all collections is returned. Unless otherwise noted, all values are strings

collections : [ - array containing the following properties
  id - numeric ID of collection (long)
  name - descriptive name
  group - group name this collection belongs to
  directory - base directory
  lastSync - date of last sync (Tue Sep 23 12:31:21 EDT 2008)
  storage - string name for storage type
  checkPeriod - int for number of days to check collection
  proxyData - boolean, true if data may be proxied through ACE
  auditTokens - boolean, should digests and tokens be audited along w/ files
  state - char, current state of collection ....
  totalFiles - long, number of files in collection
  totalSize - total collection size in bytes
  fileAuditRunning - boolean, true if a file audit is in progress
  tokenAuditRunning - boolean, true if a token audit is in progress
  totalErrors - total errors in collection (v 1.4.1)
  missingTokens - number of tokens missing after last audit (v 1.4.1)
  missingFiles - number of files missing after last audit (v 1.4.1)
  activeFiles - number of intact, validated files (v 1.4.1)
  corruptFiles - number of corrupt files (v 1.4.1)
  invalidDigests - number of invalid digests (v 1.4.1)
  remoteMissing - number of missing files on peers (v 1.4.1)
  remoteCorrupt - number of remote files w/ differing digests (v 1.4.1)
  
  The following objects will ONLY exist if a file or token audit is running
  fileAudit : {
    totalErrors - long, total number of errors encountered thus far
    newFilesFound - long, new files found in collection
    filesSeen - long, total files processes so far
    lastFileSeen - last file processed
    tokensAdded - long, new tokens issued during this audit
  }
  tokenAudit : {
    totalErrors - long, total number of errors encountered thus far
    tokensSeen - long, total number of digests/tokens loaded
    validTokens - number of tokensa/digests validated against round summaries
  }
]

Example

Invoking URL: http://localhost:8080/ace-am/Status?json=1

Output

{"collections": [
  {
    "id": 18,
    "name": "3 layer, 10files, 50dirs",
    "directory": "/",
    "lastSync": "Wed Jan 07 12:25:54 EST 2009",
    "storage": "benchmark",
    "checkPeriod": 0,
    "proxyData": false,
    "auditTokens": false,
    "state": "A",
    "totalFiles": 1250000,
    "fileAuditRunning": true,
    "tokenAuditRunning": false,
    "fileAudit": {
      "totalErrors": 0,
      "newFilesFound": 0,
      "filesSeen": 161468,
      "lastFileSeen": "/dir-6/dir-22/dir-46/file-7",
      "tokensAdded": 0
    }
  }
]}

/EventLog

Event log is a session away log servlet that can be used to query for log events. Events are attached to a collection, a particular invocation of an audit called a session, and to a particular item by path.

Parameters

• start - log entry id to start display at
• count - number of results to return
• toggletype - filter to toggle, one of 'errors','missing','newmaster','sync'
• top
• sessionId - sessionID to get events for, or set to 0 to clear
• logpath - path to get events for, or set to empty to clear
• collection - collection to retrieve events for, or set to 0 to clear
• clear - set to 1 to reset any filters, if you do not want to cache filters, then you can supply this with every call

Output

Log items along with current paging and query information for the log

start - long, starting log entry
count - int, number of entries asked for (actual results may be less)
session - long, current session filter if any (opt)
collection - long, current collection filter (opt)
logpath - current path filter (opt)
filter  - array of currently used filters, 'errors','missing','newmaster','sync'
events : [ array containing log events
  id - long, numeric ID of log entry 
  date - timestamp of entry
  session - long, session this entry belongs to
  type - int, type of log entry, complete list available at [Ace:Log Messages]
  collection - long, collection this entry is attached to (opt)
  path - path this item is attached to
  description - descriptive message for this entry
]

Example

Display default (last 20) listings

URL: http://localhost:8080/ace-am/EventLog?clear=1&json=1

Output:

{
  "start": 0,
  "count": 20,
  "filter": [],
  "events": [
    {
      "id": 27796479,
      "date": "Thu Jan 08 21:03:06 EST 2009",
      "session": 1231448172510,
      "type": 5,
      "description": "Round: 681048",
      "collection": 24,
      "path": "/dir-49/dir-49/dir-49/file-0"
    },
    {
      "id": 27796480,
      "date": "Thu Jan 08 21:03:06 EST 2009",
      "session": 1231448172510,
      "type": 5,
      "description": "Round: 681048",
      "collection": 24,
      "path": "/dir-49/dir-49/dir-49/file-1"
    },
...
...
  ]
}

Display 20 items, starting at item 0, of type sync, clear all session parameters

URL: http://localhost:8080/ace-am/EventLog?start=0&count=20&toggletype=sync&clear=1&json=1

Output:

{
  "start": 0,
  "count": 20,
  "filter": ["sync"],
  "events": [
    {
      "id": 25296472,
      "date": "Thu Jan 08 15:09:05 EST 2009",
      "session": 1231445345516,
      "type": 20,
      "description": "",
      "collection": 23,
      "path": "/"
    },
    {
      "id": 25296473,
      "date": "Thu Jan 08 15:09:14 EST 2009",
      "session": 1231445345516,
      "type": 21,
      "description": "",
      "collection": 23,
      "path": "/"
    }
  ]
}

/Report

Report generation servlet that will list all items whose state is not currently active.

Parameters

• collectionid - long, id of collection to report on
• start - item to start reporting at (counting forward from item)
• top - item to start reporting at (count backwards from item)
• count - Items to display (default 20)

Output

next
collection
count
items - [ - array containing invalid items, this is the MonitoredItem java object
  id - long, id of item
  state - current state of item, see ....
  directory - boolean, is this item a directory or file (true if directory)
  path - full item path
  parentPath - path of items parent
  lastSeen - last time item was seen intact
  stateChange - date when state of item was changed (when it was noticed bad)
]

Examples

List all corrupt items for collection id=8, starting at item 9467603, 5 results returned

URL: http://localhost:8080/ace-am/Report?start=9467603&collectionid=8&count=5&json=1

Output

{
  "collection": 8,
  "count": 5,
  "next": 11323831,
  "entries": [
    {
      "id": 9474918,
      "state": "M",
      "directory": false,
      "path": "/dlib/DLTs/DLT367/DLT367/1/content/census/sdg13533/s13533.it41501",
      "parentPath": "/dlib/DLTs/DLT367/DLT367/1/content/census/sdg13533",
      "lastSeen": "Mon Oct 27 18:36:16 EDT 2008",
      "stateChange": "Sun Nov 09 19:41:44 EST 2008"
    },
    {
      "id": 9512722,
      "state": "M",
      "directory": false,
      "path": "/dlib/DLTs/DLT367/DLT367/1/content/census/sdg13543/s13543.it21502.zip",
      "parentPath": "/dlib/DLTs/DLT367/DLT367/1/content/census/sdg13543",
      "lastSeen": "Mon Oct 27 19:19:51 EDT 2008",
      "stateChange": "Sun Nov 09 19:41:44 EST 2008"
    },
    {
      "id": 11323829,
      "state": "M",
      "directory": false,
      "path": "/dlib/DLTs/DLT651-601-other/1/content/BACKUPS/acquisitions/comp080406/rms4551.FN21898/SSYSD/Interviews/Not Pseudonymed/Year 5/OTTAWA/doc04551-all_yr51500108.txt",
      "parentPath": "/dlib/DLTs/DLT651-601-other/1/content/BACKUPS/acquisitions/comp080406/rms4551.FN21898/SSYSD/Interviews/Not Pseudonymed/Year 5/OTTAWA",
      "lastSeen": "Wed Oct 29 16:33:40 EDT 2008",
      "stateChange": "Sun Nov 09 19:41:44 EST 2008"
    },
    {
      "id": 11323830,
      "state": "M",
      "directory": false,
      "path": "/dlib/DLTs/DLT651-601-other/1/content/BACKUPS/acquisitions/comp080406/rms4551.FN21898/SSYSD/Interviews/Not Pseudonymed/Year 5/OTTAWA/doc04551-all_yr51500305.txt",
      "parentPath": "/dlib/DLTs/DLT651-601-other/1/content/BACKUPS/acquisitions/comp080406/rms4551.FN21898/SSYSD/Interviews/Not Pseudonymed/Year 5/OTTAWA",
      "lastSeen": "Wed Oct 29 16:33:40 EDT 2008",
      "stateChange": "Sun Nov 09 19:41:44 EST 2008"
    }
  ]
}

/ShowDuplicates

Show items with identical digests, specify either a digest or an item to show duplicates for.

Parameters

• item - long, id of item to show duplicates for.
• digest - string, show all items w/ digest (ignored if item is set)

Output

source source object if one is specified
{
  id - long, internal identifier for item
  state - char, state of this item
  directory - (0 or 1), 1 if this item is a directory, 0 otherwise
  path - String, full path of item
  parentpath - String, parent path of this item
  lastSeen - date, last time we saw this item intact
  stateChange - date, last time item changed state
  lastVisited - date, last time we scanned this item regardless of state (v 1.4.1)
  size - size of this item if its a file (v 1.4.1)
}
duplicates - list of duplicate objects
[
  id - long, internal identifier for item
  state - char, state of this item
  directory - (0 or 1), 1 if this item is a directory, 0 otherwise
  path - String, full path of item
  parentpath - String, parent path of this item
  lastSeen - date, last time we saw this item intact
  stateChange - date, last time item changed state
  lastVisited - date, last time we scanned this item regardless of state (v 1.4.1)
  size - size of this item if its a file (v 1.4.1)
]

Example

Show dups for item with id 6296855

URL: http://localhost:8080/ace-am/ShowDuplicates?item=6296855&json=1

Output

 

{
  "source": {
    "id": 6296855,
    "state": "A",
    "directory": false,
    "path": "/Archive0/1001/doc01001-0001_usernote.txt.zip",
    "parentPath": "/Archive0/1001",
    "lastSeen": "Tue Nov 04 13:21:39 EST 2008",
    "stateChange": ""
  },
  "duplicates": [
    "",
    {
      "id": 6337395,
      "state": "A",
      "directory": false,
      "path": "/Archive0/Archive0/1001/doc01001-0001_usernote.txt.zip",
      "parentPath": "/Archive0/Archive0/1001",
      "lastSeen": "Tue Nov 04 13:51:44 EST 2008",
      "stateChange": ""
    },
    {
      "id": 6989247,
      "state": "A",
      "directory": false,
      "path": "/Archive0/Archive0/Archive0/1001/doc01001-0001_usernote.txt.zip",
      "parentPath": "/Archive0/Archive0/Archive0/1001",
      "lastSeen": "Wed Nov 05 01:41:39 EST 2008",
      "stateChange": ""
    }
  ]
}

/ListItem

View details on a single item or directory. Useful for remote browsing of collections (V1.3.1)

Parameters

Output

parent object containing details on requested item
{
  id - long, internal identifier for item
  state - char, state of this item
  directory - (0 or 1), 1 if this item is a directory, 0 otherwise
  path - String, full path of item
  parentpath - String, parent path of this item
  lastSeen - date, last time we saw this item intact
  stateChange - date, last time item changed state
  lastVisited - date, last time we scanned this item regardless of state
  size - size of this item if its a file
}
children list of children if this object is a directory
[
  id - long, internal identifier for item
  state - char, state of this item
  directory - (0 or 1), 1 if this item is a directory, 0 otherwise
  path - String, full path of item
  parentpath - String, parent path of this item
  lastSeen - date, last time we saw this item intact
  stateChange - date, last time item changed state
  lastVisited - date, last time we scanned this item regardless of state
  size - size of this item if its a file
]

/ViewSummary

View a list of collection summaries. If no parameters are give, then all reports are returned.

Parameters

• collectionid - optional, if included show only summaries from the specified collection
• latest - optional (0 or 1), if set to 1, this will only show the latest report from the specified collection, or latest from each collection (v 1.4.1)
• limit - optional, number of reports to return. (v 1.4.1)

Output

collection - long, id of collection selected or "" if none specified
summaries [
  reportName - String, descriptive name of report
  id - long, internal identifier for report, newer reports have higher ids
  collection - long, id of collection this summary refers to
  collectionName - descriptive name of collection this summary refers to
  start - start date of report
  end - end date of report
  collectionState object w/ items refering to current state, if an item is not is the JSON, is may be assumed to be 0
  {
    Total Items - total number of items currently monitored (all states)
    Total Errors - total number of items with any error (state != A)
    Active Items - number of valid items in a collection
    Corrupt Items - number of items where file does not match stored digest
    Missing Files - number of files that have disappeared
    Missing Tokens - number of digests w/o a token to validate them
    Corrupt Digests - number of digests where digest could not be validated
  }
  logSummary object with counts showing how many occurances of a given log entry occured during the summary time, items not present may be assumed to be 0
  {
https://wiki.umiacs.umd.edu/adapt/index.php/Ace:Log_Messages for types of messages
  }
]