One principle assumption in DMS's design is that a file is an atomic unit. It deals exclusively with operating system files alone, nothing smaller, nothing bigger. However, there are cases when you might need to deal with a document as a series of files. For example, you might split a PDF into a series of PNG files, and you need some way to keep them all organized together in a group. In this case, you have now created a new level of indirection. The Series class along with PostgreSQL's integer[] types make handling this easy.

All you have to do now is create a column somewhere that stores an integer array of file IDs and asscociate that with your document. For example, you could create a Document table that looks like this:

-- A simple document table
create table document
(
  name text;
  files integer[];
);

Basically, the Series class is a glorified Array class which just converts it's values to SQL representation and back. The easiest way to see how to use it is by example. So here is some code adapted from the unit tests:

# Update the file list in a document table record:

sql_value = '{1,2,3}'

doc = JW::DMS::Series.new(sql_value)
assert doc.to_s == '{1,2,3}'
assert doc.files.size == 3

sql = "update document set files = #{doc.to_s}"

# Create another document using Ruby Array:
doc = JW::DMS::Series.new([1,2,3])

# Lock all files in series
assert @dms.lockSeries(doc) == true

# Check every lock (should be shared)
doc.locks.each do |lock|
  assert lock.type == :shared
end

# Make sure we got 10 locks
assert doc.locks.size == 10

# Release locks
@dms.unlockSeries doc


# Now delete all the files in the document
@dms.deleteSeries(doc)