ptstore

README

-- title: ptstore draft: true

ptstore

This directory holds the implementation for storing dataset collections in a pairtree. It includes support for versioning JSON documents stored in the pairtree.

Documentation

Overview

ptstore is a submodule of the dataset package.

Authors R. S. Doiel, <rsdoiel@library.caltech.edu> and Tom Morrel, <tmorrell@library.caltech.edu>

Copyright (c) 2022, Caltech All rights not granted herein are expressly reserved by Caltech.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

• Constants
• type Storage
  • func Open(name string, dsnURI string) (*Storage, error)
  • func (store *Storage) Close() error
  • func (store *Storage) Create(key string, src []byte) error
  • func (store *Storage) Delete(key string) error
  • func (store *Storage) DocPath(key string) (string, error)
  • func (store *Storage) HasKey(key string) bool
  • func (store *Storage) Keymap() map[string]string
  • func (store *Storage) KeymapName() string
  • func (store *Storage) Keys() ([]string, error)
  • func (store *Storage) Length() int64
  • func (store *Storage) Read(key string) ([]byte, error)
  • func (store *Storage) ReadVersion(key string, version string) ([]byte, error)
  • func (store *Storage) SetVersioning(setting int) error
  • func (store *Storage) Update(key string, src []byte) error
  • func (store *Storage) UpdateKeymap(keymap map[string]string) error
  • func (store *Storage) Versions(key string) ([]string, error)

Constants

const (
	// None means versioning is turned off for collection
	None = iota
	// Major means increment the major semver value on creation or update
	Major
	// Minor means increment the minor semver value on creation or update
	Minor
	// Patach means increment the patch semver value on creation or update
	Patch
)

Types

type Storage

type Storage struct {
	// Working path to the directory where the collections.json is found.
	WorkPath string

	// Versioning holds the type of versioning active for the stored
	// collection. The options are None (no versioning, the default),
	// Major (major value in semver is incremented), Minor (minor value
	// in semver is incremented) and Patch (patch value in semver is incremented)
	Versioning int
	// contains filtered or unexported fields
}

func Open

func Open(name string, dsnURI string) (*Storage, error)

Open opens the storage system and returns an storage struct and error It is passed a directory name that holds collection.json. The second parameter is for a DSN URI which is ignored in a pairtree implementation.

```

name := "testout/T1.ds" // a collection called "T1.ds"
store, err := c.Store.Open(name, "")
if err != nil {
   ...
}
defer store.Close()

```

func (*Storage) Close

func (store *Storage) Close() error

Close closes the storage system freeing resources as needed.

```

if err := store.Close(); err != nil {
   ...
}

```

func (*Storage) Create

func (store *Storage) Create(key string, src []byte) error

Create stores a new JSON object in the collection It takes a string as a key and a byte slice of encoded JSON

err := store.Create("123", []byte(`{"one": 1}`))
if err != nil {
   ...
}

func (*Storage) Delete

func (store *Storage) Delete(key string) error

Delete removes all versions of JSON document and attachment indicated by the key provided.

key := "123"
if err := store.Delete(key); err != nil {
   ...
}

NOTE: If you're versioning your collection then you never really want to delete. An approach could be to use update using an empty JSON document to indicate the document is retired those avoiding the deletion problem of versioned content.

```

key := "123"
if err := store.Delete(key); err != nil {
   ...
}

```

func (*Storage) DocPath

func (store *Storage) DocPath(key string) (string, error)

func (*Storage) HasKey

func (store *Storage) HasKey(key string) bool

HasKey will look up and make sure key is in collection. Storage must be open or zero false will always be returned.

```

key := "123"
if store.HasKey(key) {
   ...
}

```

func (*Storage) Keymap

func (store *Storage) Keymap() map[string]string

func (*Storage) KeymapName

func (store *Storage) KeymapName() string

func (*Storage) Keys

func (store *Storage) Keys() ([]string, error)

List returns all keys in a collection as a slice of strings.

```

var keys []string
keys, _ = store.Keys()
/* iterate over the keys retrieved */
for _, key := range keys {
   ...
}

```

NOTE: the error will always be nil, this func signature needs to match the other storage engines.

func (*Storage) Length

func (store *Storage) Length() int64

Length returns the number of records (len(store.keys)) in the collection Requires collection to be open.

```

var x int64

x = store.Length()

```

func (*Storage) Read

func (store *Storage) Read(key string) ([]byte, error)

Read retrieves takes a string as a key and returns the encoded JSON document from the collection. If versioning is enabled this is always the "current" version of the object. Use Versions() and ReadVersion() for versioned copies.

```

src, err := store.Read("123")
if err != nil {
   ...
}
obj := map[string]interface{}{}
if err := json.Unmarshal(src, &obj); err != nil {
   ...
}

```

func (*Storage) ReadVersion

func (store *Storage) ReadVersion(key string, version string) ([]byte, error)

ReadVersion retrieves a specific version of a JSON document stored in a collection.

```

key, version := "123", "0.0.1"
src, err := store.ReadVersion(key, version)
if err != nil {
   ...
}

```

func (*Storage) SetVersioning

func (store *Storage) SetVersioning(setting int) error

SetVersioning sets the type of versioning associated with the stored collection.

func (*Storage) Update

func (store *Storage) Update(key string, src []byte) error

Update takes a key and encoded JSON object and updates a JSON document in the collection.

```

key := "123"
src := []byte(`{"one": 1, "two": 2}`)
if err := store.Update(key, src); err != nil {
   ...
}

```

func (*Storage) UpdateKeymap

func (store *Storage) UpdateKeymap(keymap map[string]string) error

func (*Storage) Versions

func (store *Storage) Versions(key string) ([]string, error)

Versions retrieves a list of semver version strings available for a JSON document.

```

key := "123"
versions, err := store.Versions(key)
if err != nil {
   ...
}
for _, version := range versions {
     // do something with version string.
}

```