gorods

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2016 License: BSD-3-Clause Imports: 8 Imported by: 1

README

GoRods

Golang binding for iRods C API. Requires go version >= 1.5 for cgo compile flags variable support.

Notice: This package is incomplete and still under heavy development. API is subject to change without warning until a stable version is released.

Installation

Dependencies (http://irods.org/download/):

  • irods-dev-4.1.8
  • irods-runtime-4.1.8
$ go get github.com/jjacquay712/GoRods
Docs

https://godoc.org/github.com/jjacquay712/GoRods

Example Usage

package main

import (
	"fmt"
	"github.com/jjacquay712/GoRods"
)

func main() {

	// Connect to server, error provided by second parameter
	irods, _ := gorods.New(gorods.ConnectionOptions {

		// Or gorods.System to use the systems preconfigured environment
		Environment: gorods.UserDefined, 

		Host: "localhost",
		Port: 1247,
		Zone: "tempZone",

		Username: "admin",
		Password: "password",
	})

	// Open collection, preload sub collections into memory
	homeDir, _ := irods.Collection("/tempZone/home/admin", true)

	buildFile := homeDir.Cd("gorods").Get("build.sh")

	// Returns MetaCollection containing all metadata for buildFile DataObject
	metas := buildFile.Meta()

	// Returns pointer to Meta struct
	metas.Get("MyAttribute")

	// Or use a shortcut
	buildFile.Attribute("MyAttribute")
	
	// Returns true/false if checksum matches
	buildFile.Verify("GdU5GXvmky9/rw7rduk4JaEtEdlhhhhGufiez+2aI4o=")
	
	// Download remote file
	buildFile.DownloadTo("build.sh")

	// Read file from /tempZone/home/admin/gorods/build.sh
	contents := buildFile.Read()

	// Read file in 5 byte chunks
	var wholeFile []byte

	buildFile.ReadChunk(5, func(chunk []byte) {
		wholeFile = append(wholeFile, chunk...)
	})

	fmt.Printf(string(wholeFile))

	// Print []Byte as string
	fmt.Printf(string(contents))

	// Add local file to collection
	remoteFile := homeDir.Put("local_file.txt")

	// Copy file to gorods directory
	remoteFile.CopyTo("gorods")
	// or
	//
	// gorodsDir := homeDir.Cd("gorods")
	// remoteFile.CopyTo(gorodsDir)

	// Move file
	remoteFile.MoveTo("gorods/local_file2.txt")

	// Rename file
	remoteFile.Rename("local_file3.txt")

	// Create file in home directory, overwrite if it exists
	test := gorods.CreateDataObj(gorods.DataObjOptions {
		Name: "test.txt",
		Mode: 0750,
		Force: true,
	}, homeDir)

	// Write string to test file
	test.Write([]byte("This is a test!"))

	// Write 5 copies of "test" to file
	// Will start writing at last offset (seek) position (typically 0)
	for n := 0; n < 5; n++ {
		test.WriteBytes([]byte("test\n"))
	}

	// We must close the file explicitly after calling WriteBytes()
	test.Close()

	// Stat the test.txt file
	fmt.Printf("%v \n", test.Stat())

	// Read the contents back, print to screen
	fmt.Printf("%v \n", string(test.Read()))

	// Delete the file
	test.Delete()

}

Contributing

Send me a pull request!

Todo

iRods API Coverage
  • Implement DataObj: MoveToResource(), Replicate(), ReplSettings()
  • Implement Meta: set operations, imeta qu
  • Implement Collection: CreateCollection(), MoveTo(), CopyTo(), DownloadTo()
  • Implement Connection: ilocate, interface to query meta (imeta qu), direct DataObj getter like Connection.Collection()?
  • Implement structs: User, Group, Resource, Zone?
  • Implement access control (rcModAccessControl) and tickets
Code Polish
  • Add more robust error handling: Add idiomatic return errors for public functions
  • Add unit tests

Known Issues

  • The static library included (lib/build/libgorods.a) in this repo won't work on 32-bit systems and OSX. Install irods-dev system package, and run the build.sh script to compile binaries for your system.
  • Hardcoded paths for linking iRods static libraries in connection.go, are these paths consistent across distros? Only tested on CentOS 7.
  • Bug list: https://godoc.org/github.com/jjacquay712/GoRods#pkg-note-bug

Copyright (c) 2016, University of Florida Research Foundation, Inc. All Rights Reserved.

GoRods is released under a 3-clause BSD License. For more information please refer to the LICENSE.md file

Documentation

Overview

Package gorods is a Golang binding for the iRods C API (iRods client library). GoRods uses cgo to call iRods client functions.

Index

Constants

View Source 
const (
	System = iota
	UserDefined
)

System and UserDefined constants are used when calling gorods.New(ConnectionOptions{ Environment: ... }) When System is specified, the options stored in ~/.irods/.irodsEnv will be used. When UserDefined is specified you must also pass Host, Port, Username, and Zone. Password should be set regardless.

View Source 
const (
	DataObjType = iota
	CollectionType
	ResourceType
	ResourceGroupType
	UserType
)

Used when calling Type() on different gorods objects

View Source 
const (
	Info = iota
	Warn
	Fatal
)

Log level constants

Variables

This section is empty.

Functions

This section is empty.

Types

type Collection 

type Collection struct {
	Path        string
	Name        string
	DataObjects []IRodsObj
	MetaCol     MetaCollection
	Con         *Connection
	Col         *Collection
	Recursive   bool
	ObjType     int
	// contains filtered or unexported fields
}

Collection structs contain information about single collections in an iRods zone.

func (*Collection) All 

func (col *Collection) All() []IRodsObj

Returns generic interface slice containing both data objects and collections combined

func (*Collection) Attribute 

func (col *Collection) Attribute(attr string) *Meta

Attribute gets specific metadata AVU triple for Collection

func (*Collection) Both 

func (col *Collection) Both() (DataObjs, Collections)

Both returns two slices, the first for DataObjs and the second for Collections

func (*Collection) Cd 

func (col *Collection) Cd(path string) *Collection

Cd is a shortcut for calling collection.Collections().Find(path). It effectively returns (or changes to) the sub collection you specify collection-relatively or absolutely.

func (*Collection) Close 

func (col *Collection) Close() *Collection

Close closes the Collection connection and resets the handle

func (*Collection) Collections 

func (col *Collection) Collections() Collections

Collections returns only the collections contained within the collection

func (*Collection) CreateDataObj 

func (col *Collection) CreateDataObj(opts DataObjOptions) *DataObj

CreateDataObj creates a data object within the collection using the options specified

func (*Collection) DataObjs 

func (col *Collection) DataObjs() DataObjs

DataObjs returns only the data objects contained within the collection

func (*Collection) Exists 

func (col *Collection) Exists(path string) bool

Exists returns true of false depending on whether the DataObj or Collection is found

func (*Collection) Find 

func (col *Collection) Find(path string) IRodsObj

Find returns either a DataObject or Collection using the collection-relative or absolute path specified.

func (*Collection) Get 

func (col *Collection) Get(path string) *DataObj

Get is a shortcut for calling collection.DataObjs().Find(path). It effectively returns the DataObj you specify collection-relatively or absolutely.

func (*Collection) Meta 

func (col *Collection) Meta() MetaCollection

Meta returns collection of all metadata AVU triples for Collection

func (*Collection) Open 

func (col *Collection) Open() *Collection

Open connects to iRods and sets the handle for Collection. Usually called by Collection.init()

func (*Collection) Put 

func (col *Collection) Put(localFile string) *DataObj

Put adds a local file to the remote iRods collection

func (*Collection) ReadCollection 

func (col *Collection) ReadCollection()

ReadCollection reads data (overwrites) into col.DataObjects field.

func (*Collection) Refresh 

func (col *Collection) Refresh()

Refresh is an alias of ReadCollection()

func (*Collection) String 

func (obj *Collection) String() string

String shows the contents of the collection.

D = DataObj

C = Collection

Sample output: 

Collection: /tempZone/home/admin/gorods
	D: build.sh
	C: bin
	C: pkg
	C: src

func (*Collection) Type 

func (col *Collection) Type() int

Type gets the type

type Collections 

type Collections []*Collection

Collections is a slice of Collection structs

func (Collections) Exists 

func (colls Collections) Exists(path string) bool

Exists checks to see if a collection exists in the slice and returns true or false

func (Collections) Find 

func (colls Collections) Find(path string) *Collection

Find gets a collection from the slice and returns nil if one is not found. Both the collection name or full path can be used as input.

func (Collections) FindRecursive 

func (colls Collections) FindRecursive(path string) *Collection

FindRecursive acts just like Find, but also searches sub collections recursively. If the collection was not explicitly loaded recursively, only the first level of sub collections will be searched.

type Connection 

type Connection struct {
	Connected         bool
	Options           *ConnectionOptions
	OpenedCollections Collections
	// contains filtered or unexported fields
}

func New 

func New(opts ConnectionOptions) (*Connection, error)

New creates a connection to an iRods iCAT server. System and UserDefined constants are used in ConnectionOptions{ Environment: ... }). When System is specified, the options stored in ~/.irods/.irodsEnv will be used. When UserDefined is specified you must also pass Host, Port, Username, and Zone. Password should be set regardless.

func (*Connection) Collection 

func (con *Connection) Collection(startPath string, recursive bool) (collection *Collection, err error)

Collection initializes and returns an existing iRods collection using the specified path

func (*Connection) Disconnect 

func (con *Connection) Disconnect()

Disconnect closes connection to iRods iCAT server

func (*Connection) String 

func (obj *Connection) String() string

String provides connection status and options provided during initialization (gorods.New)

type ConnectionOptions 

type ConnectionOptions struct {
	Environment int

	Host string
	Port int
	Zone string

	Username string
	Password string
}

ConnectionOptions are used when creating iRods iCAT server connections see gorods.New() docs for more info.

type DataObj 

type DataObj struct {
	Path    string
	Name    string
	Size    int64
	Offset  int64
	ObjType int

	MetaCol MetaCollection

	// Con field is a pointer to the Connection used to fetch the data object
	Con *Connection

	// Col field is a pointer to the Collection containing the data object
	Col *Collection
	// contains filtered or unexported fields
}

DataObj structs contain information about single data objects in an iRods zone.

func CreateDataObj 

func CreateDataObj(opts DataObjOptions, coll *Collection) *DataObj

CreateDataObj creates and adds a data object to the specified collection using provided options. Returns the newly created data object.

func (*DataObj) Attribute 

func (obj *DataObj) Attribute(attrName string) *Meta

Attribute returns a single Meta triple struct found by the attributes name

func (*DataObj) Chksum 

func (obj *DataObj) Chksum() string

Chksum returns md5 hash string of data object

func (*DataObj) Close 

func (obj *DataObj) Close() *DataObj

Close closes the data object handler, returns the closed data object.

func (*DataObj) CopyTo 

func (obj *DataObj) CopyTo(iRodsCollection interface{}) *DataObj

CopyTo copies the data object to the specified collection. Supports Collection struct or string as input. Also refreshes the destination collection automatically to maintain correct state. Returns self (source DataObj).

func (*DataObj) Delete 

func (obj *DataObj) Delete()

Delete deletes the data object from the iRods server with a force flag

func (*DataObj) DownloadTo 

func (obj *DataObj) DownloadTo(localPath string) *DataObj

DownloadTo downloads and writes the entire data object to the provided path. Don't use this with large files unless you have RAM to spare, use ReadChunk() instead. Returns self (DataObj).

func (*DataObj) LSeek 

func (obj *DataObj) LSeek(offset int64) *DataObj

LSeek sets the read/write offset pointer of a data object, returns self (DataObj)

func (*DataObj) Meta 

func (obj *DataObj) Meta() MetaCollection

Meta returns collection of Meta AVU triple structs of the data object

func (*DataObj) MoveTo 

func (obj *DataObj) MoveTo(iRodsCollection interface{}) *DataObj

MoveTo moves the data object to the specified collection. Supports Collection struct or string as input. Also refreshes the source and destination collections automatically to maintain correct state. Returns self (DataObj).

func (*DataObj) MoveToResource 

func (obj *DataObj) MoveToResource(destinationResource string) *DataObj

NEED TO IMPLEMENT

func (*DataObj) Open 

func (obj *DataObj) Open()

Open opens a connection to iRods and sets the data object handle

func (*DataObj) Read 

func (obj *DataObj) Read() []byte

Read reads the entire data object into memory and returns a []byte slice. Don't use this for large files.

func (*DataObj) ReadBytes 

func (obj *DataObj) ReadBytes(pos int64, length int) []byte

ReadBytes reads bytes from a data object at the specified position and length, returns []byte slice.

func (*DataObj) ReadChunk 

func (obj *DataObj) ReadChunk(size int64, callback func([]byte)) *DataObj

ReadChunk reads the entire data object in chunks (size of chunk specified by size parameter), passing the data into a callback function for each chunk. Use this to read/write large files.

func (*DataObj) Rename 

func (obj *DataObj) Rename(newFileName string) *DataObj

Rename is equivalent to the Linux mv command except that the data object must stay within the current collection (directory), returns self (DataObj).

func (*DataObj) ReplSettings 

func (obj *DataObj) ReplSettings(resource map[string]interface{}) *DataObj

NEED TO IMPLEMENT

func (*DataObj) Replicate 

func (obj *DataObj) Replicate(targetResource string) *DataObj

NEED TO IMPLEMENT

func (*DataObj) Stat 

func (obj *DataObj) Stat() map[string]interface{}

Stat returns a map (key/value pairs) of the system meta information. The following keys can be used with the map:

"objSize"

"dataMode"

"dataId"

"chksum"

"ownerName"

"ownerZone"

"createTime"

"modifyTime"

func (*DataObj) String 

func (obj *DataObj) String() string

String returns path of data object

func (*DataObj) Type 

func (obj *DataObj) Type() int

Type gets the type 

func (obj *DataObj) Unlink()

Unlink deletes the data object from the iRods server, no force flag is used

func (*DataObj) Verify 

func (obj *DataObj) Verify(md5Checksum string) bool

Verify returns true or false depending on whether the checksum md5 string matches

func (*DataObj) Write 

func (obj *DataObj) Write(data []byte) *DataObj

Write writes the data to the data object, starting from the beginning. Returns self (DataObj).

func (*DataObj) WriteBytes 

func (obj *DataObj) WriteBytes(data []byte) *DataObj

WriteBytes writes to the data object wherever the object's offset pointer is currently set to. It advances the pointer to the end of the written data for supporting subsequent writes. Be sure to call obj.LSeek(0) before hand if you wish to write from the beginning. Returns self (DataObj).

type DataObjOptions 

type DataObjOptions struct {
	Name     string
	Size     int64
	Mode     int
	Force    bool
	Resource string
}

DataObjOptions is used for passing options to the CreateDataObj function

type DataObjs 

type DataObjs []*DataObj

DataObjs is a slice of DataObj structs

func (DataObjs) Exists 

func (dos DataObjs) Exists(path string) bool

Exists checks to see if a data object exists in the slice and returns true or false

func (DataObjs) Find 

func (dos DataObjs) Find(path string) *DataObj

Find gets a data object from the slice and returns nil if one is not found. Both the data object name or full path can be used as input.

type GoRodsError 

type GoRodsError struct {
	LogLevel int
	Message  string
	Time     time.Time
}

GoRodsError stores information about errors

func (*GoRodsError) Error 

func (err *GoRodsError) Error() string

Error returns error string, alias of String(). Sample output: 

2016-04-22 10:02:30.802355258 -0400 EDT: Fatal - iRods Connect Failed: rcConnect failed

func (*GoRodsError) String 

func (err *GoRodsError) String() string

String returns error string. Sample output: 

2016-04-22 10:02:30.802355258 -0400 EDT: Fatal - iRods Connect Failed: rcConnect failed

type IRodsObj 

type IRodsObj interface {
	Type() int
}

IRodsObj is a generic interface used to detect the object type

type Meta 

type Meta struct {
	Attribute string
	Value     string
	Units     string
}

Meta structs contain information about a single iRods metadata attribute-value-units (AVU) triple

func (*Meta) String 

func (m *Meta) String() string

String shows the contents of the meta struct.

Sample output: 

Attr1: Val (unit: foo)

type MetaCollection 

type MetaCollection []*Meta

MetaCollection is a collection of metadata AVU triples for a single data object

func (MetaCollection) Get 

func (metas MetaCollection) Get(attr string) *Meta

Get finds a single Meta struct by it's Attribute field. Similar to Attribute() function of other types.

func (MetaCollection) String 

func (metas MetaCollection) String() string

String shows the contents of the meta collection.

Sample output: 

Attr1: Val (unit: )
Attr2: Yes (unit: bool)

Notes

Bugs

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.