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
- type Collection
- func (col *Collection) AddMeta(m Meta) (newMeta *Meta, err error)
- func (col *Collection) All() (IRodsObjs, error)
- func (col *Collection) Attribute(attr string) (Metas, error)
- func (col *Collection) Cd(path string) *Collection
- func (col *Collection) Close() error
- func (col *Collection) CreateDataObj(opts DataObjOptions) (*DataObj, error)
- func (col *Collection) CreateSubCollection(name string) (*Collection, error)
- func (col *Collection) Delete(recursive bool) error
- func (col *Collection) DeleteMeta(attr string) (*MetaCollection, error)
- func (col *Collection) Destroy() error
- func (col *Collection) Exists(path string) bool
- func (col *Collection) Find(path string) IRodsObj
- func (col *Collection) FindCol(path string) *Collection
- func (col *Collection) FindObj(path string) *DataObj
- func (col *Collection) FindRecursive(path string) IRodsObj
- func (col *Collection) Get(path string) *DataObj
- func (col *Collection) GetCol() *Collection
- func (col *Collection) GetCollections() (response IRodsObjs, err error)
- func (col *Collection) GetCon() *Connection
- func (col *Collection) GetCreateTime() int
- func (col *Collection) GetDataObjs() (response IRodsObjs, err error)
- func (col *Collection) GetModifyTime() int
- func (col *Collection) GetName() string
- func (col *Collection) GetOwnerName() string
- func (col *Collection) GetPath() string
- func (col *Collection) GetType() int
- func (col *Collection) IsRecursive() bool
- func (col *Collection) Meta() (*MetaCollection, error)
- func (col *Collection) Open() error
- func (col *Collection) Put(localFile string) (*DataObj, error)
- func (col *Collection) ReadCollection() error
- func (col *Collection) Refresh() error
- func (col *Collection) Rm(recursive bool, force bool) error
- func (obj *Collection) String() string
- func (col *Collection) Trash(recursive bool) error
- type Connection
- func (con *Connection) Collection(startPath string, recursive bool) (*Collection, error)
- func (con *Connection) DataObject(dataObjPath string) (dataobj *DataObj, err error)
- func (con *Connection) Disconnect() error
- func (con *Connection) GetCcon() *C.rcComm_t
- func (con *Connection) QueryMeta(qString string) (response IRodsObjs, err error)
- func (con *Connection) ReturnCcon(ccon *C.rcComm_t)
- func (con *Connection) SearchDataObjects(dataObjPath string) (dataobj *DataObj, err error)
- func (con *Connection) SetTicket(t string) error
- func (obj *Connection) String() string
- type ConnectionOptions
- type DataObj
- func (obj *DataObj) AddMeta(m Meta) (nm *Meta, err error)
- func (obj *DataObj) Attribute(attrName string) (Metas, error)
- func (obj *DataObj) Chksum() (string, error)
- func (obj *DataObj) Close() error
- func (obj *DataObj) CopyTo(iRodsCollection interface{}) error
- func (obj *DataObj) Delete(recursive bool) error
- func (obj *DataObj) DeleteMeta(attr string) (*MetaCollection, error)
- func (obj *DataObj) Destroy() error
- func (obj *DataObj) DownloadTo(localPath string) error
- func (obj *DataObj) GetCol() *Collection
- func (obj *DataObj) GetCon() *Connection
- func (obj *DataObj) GetCreateTime() int
- func (obj *DataObj) GetModifyTime() int
- func (obj *DataObj) GetName() string
- func (obj *DataObj) GetOwnerName() string
- func (obj *DataObj) GetPath() string
- func (obj *DataObj) GetType() int
- func (obj *DataObj) LSeek(offset int64) error
- func (obj *DataObj) Meta() (*MetaCollection, error)
- func (obj *DataObj) MoveTo(iRodsCollection interface{}) error
- func (obj *DataObj) MoveToResource(destinationResource string) *DataObj
- func (obj *DataObj) Open() error
- func (obj *DataObj) OpenRW() error
- func (obj *DataObj) Read() ([]byte, error)
- func (obj *DataObj) ReadBytes(pos int64, length int) ([]byte, error)
- func (obj *DataObj) ReadChunk(size int64, callback func([]byte)) error
- func (obj *DataObj) Rename(newFileName string) error
- func (obj *DataObj) ReplSettings(resource map[string]interface{}) *DataObj
- func (obj *DataObj) Replicate(targetResource string) *DataObj
- func (obj *DataObj) Rm(recursive bool, force bool) error
- func (obj *DataObj) Stat() (map[string]interface{}, error)
- func (obj *DataObj) String() string
- func (obj *DataObj) Trash(recursive bool) error
- func (obj *DataObj) Unlink() error
- func (obj *DataObj) Verify(md5Checksum string) bool
- func (obj *DataObj) Write(data []byte) error
- func (obj *DataObj) WriteBytes(data []byte) error
- type DataObjOptions
- type GoRodsError
- type IRodsObj
- type IRodsObjs
- type Meta
- func (m *Meta) Delete() (*MetaCollection, error)
- func (m *Meta) Rename(attributeName string) (*Meta, error)
- func (m *Meta) Set(value string, units string) (*Meta, error)
- func (m *Meta) SetAll(attributeName string, value string, units string) (newMeta *Meta, e error)
- func (m *Meta) SetUnits(units string) (*Meta, error)
- func (m *Meta) SetValue(value string) (*Meta, error)
- func (m *Meta) String() string
- type MetaCollection
- func (mc *MetaCollection) Add(m Meta) (*Meta, error)
- func (mc *MetaCollection) All() (Metas, error)
- func (mc *MetaCollection) Delete(attr string) (err error)
- func (mc *MetaCollection) Each(iterator func(*Meta)) error
- func (mc *MetaCollection) First(attr string) (*Meta, error)
- func (mc *MetaCollection) Get(attr string) (Metas, error)
- func (mc *MetaCollection) ReadMeta() error
- func (mc *MetaCollection) Refresh() error
- func (mc *MetaCollection) String() string
- type Metas
- Bugs
Constants ¶
const ( EnvironmentDefined = iota UserDefined )
EnvironmentDefined and UserDefined constants are used when calling gorods.New(ConnectionOptions{ Type: ... }) When EnvironmentDefined is specified, the options stored in ~/.irods/irods_environment.json will be used. When UserDefined is specified you must also pass Host, Port, Username, and Zone. Password should be set regardless.
const ( DataObjType = iota CollectionType ResourceType ResourceGroupType UserType )
Used when calling Type() on different gorods objects
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 IRodsObjs MetaCol *MetaCollection Con *Connection Col *Collection Recursive bool Init bool Type int OwnerName string CreateTime int ModifyTime int // contains filtered or unexported fields }
Collection structs contain information about single collections in an iRods zone.
func CreateCollection ¶ added in v0.1.3
func CreateCollection(name string, coll *Collection) (*Collection, error)
CreateCollection creates a collection in the specified collection using provided options. Returns the newly created collection object.
func (*Collection) AddMeta ¶ added in v0.1.1
func (col *Collection) AddMeta(m Meta) (newMeta *Meta, err error)
AddMeta adds a single Meta triple struct
func (*Collection) All ¶
func (col *Collection) All() (IRodsObjs, error)
Returns generic interface slice containing both data objects and collections combined
func (*Collection) Attribute ¶
func (col *Collection) Attribute(attr string) (Metas, error)
Attribute gets slice of Meta AVU triples, matching by Attribute name for Collection
func (*Collection) Cd ¶
func (col *Collection) Cd(path string) *Collection
Cd is a shortcut for calling collection.GetCollections().Find(path). It effectively returns (or changes to) the sub collection you specify collection-relatively or absolutely.
func (*Collection) Close ¶
func (col *Collection) Close() error
Close closes the Collection connection and resets the handle
func (*Collection) CreateDataObj ¶
func (col *Collection) CreateDataObj(opts DataObjOptions) (*DataObj, error)
CreateDataObj creates a data object within the collection using the options specified
func (*Collection) CreateSubCollection ¶ added in v0.1.3
func (col *Collection) CreateSubCollection(name string) (*Collection, error)
CreateSubCollection creates a collection within the collection using the options specified
func (*Collection) Delete ¶ added in v0.1.4
func (col *Collection) Delete(recursive bool) error
Delete is equivalent to irm -f {-r}
func (*Collection) DeleteMeta ¶ added in v0.1.1
func (col *Collection) DeleteMeta(attr string) (*MetaCollection, error)
DeleteMeta deletes a single Meta triple struct, identified by Attribute field
func (*Collection) Destroy ¶ added in v0.1.4
func (col *Collection) Destroy() error
Destroy is equivalent to irm -rf
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) FindCol ¶ added in v0.1.1
func (col *Collection) FindCol(path string) *Collection
func (*Collection) FindObj ¶ added in v0.1.1
func (col *Collection) FindObj(path string) *DataObj
func (*Collection) FindRecursive ¶ added in v0.1.1
func (col *Collection) FindRecursive(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.GetDataObjs().Find(path). It effectively returns the DataObj you specify collection-relatively or absolutely.
func (*Collection) GetCol ¶ added in v0.1.1
func (col *Collection) GetCol() *Collection
GetCol returns the *Collection of the collection
func (*Collection) GetCollections ¶ added in v0.1.1
func (col *Collection) GetCollections() (response IRodsObjs, err error)
GetCollections returns only the IRodsObjs that represent collections
func (*Collection) GetCon ¶ added in v0.1.1
func (col *Collection) GetCon() *Connection
Connection returns the *Connection used to get collection
func (*Collection) GetCreateTime ¶ added in v0.1.4
func (col *Collection) GetCreateTime() int
GetCreateTime returns the create time of the collection
func (*Collection) GetDataObjs ¶ added in v0.1.1
func (col *Collection) GetDataObjs() (response IRodsObjs, err error)
GetDataObjs returns only the data objects contained within the collection
func (*Collection) GetModifyTime ¶ added in v0.1.4
func (col *Collection) GetModifyTime() int
GetModifyTime returns the modify time of the collection
func (*Collection) GetName ¶ added in v0.1.1
func (col *Collection) GetName() string
GetName returns the Name of the collection
func (*Collection) GetOwnerName ¶ added in v0.1.4
func (col *Collection) GetOwnerName() string
GetOwnerName returns the owner name of the collection
func (*Collection) GetPath ¶ added in v0.1.1
func (col *Collection) GetPath() string
GetPath returns the Path of the collection
func (*Collection) GetType ¶ added in v0.1.1
func (col *Collection) GetType() int
Type gets the type
func (*Collection) IsRecursive ¶ added in v0.1.1
func (col *Collection) IsRecursive() bool
IsRecursive returns true or false
func (*Collection) Meta ¶
func (col *Collection) Meta() (*MetaCollection, error)
Meta returns collection of all metadata AVU triples for Collection
func (*Collection) Open ¶
func (col *Collection) Open() error
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, error)
Put adds a local file to the remote iRods collection
func (*Collection) ReadCollection ¶
func (col *Collection) ReadCollection() error
ReadCollection reads data (overwrites) into col.DataObjects field.
func (*Collection) Refresh ¶
func (col *Collection) Refresh() error
Refresh is an alias of ReadCollection()
func (*Collection) Rm ¶ added in v0.1.4
func (col *Collection) Rm(recursive bool, force bool) error
Rm is equivalent to irm {-r} {-f}
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) Trash ¶ added in v0.1.4
func (col *Collection) Trash(recursive bool) error
Trash is equivalent to irm {-r}
type Connection ¶
type Connection struct { Connected bool Options *ConnectionOptions OpenedObjs IRodsObjs // contains filtered or unexported fields }
func New ¶
func New(opts ConnectionOptions) (*Connection, error)
New creates a connection to an iRods iCAT server. EnvironmentDefined and UserDefined constants are used in ConnectionOptions{ Type: ... }). When EnvironmentDefined is specified, the options stored in ~/.irods/irods_environment.json will be used. When UserDefined is specified you must also pass Host, Port, Username, and Zone. Password should be set unless using an anonymous user account with tickets.
func (*Connection) Collection ¶
func (con *Connection) Collection(startPath string, recursive bool) (*Collection, error)
Collection initializes and returns an existing iRods collection using the specified path
func (*Connection) DataObject ¶ added in v0.1.1
func (con *Connection) DataObject(dataObjPath string) (dataobj *DataObj, err error)
DataObject directly returns a specific DataObj without the need to traverse collections. Must pass full path of data object.
func (*Connection) Disconnect ¶
func (con *Connection) Disconnect() error
Disconnect closes connection to iRods iCAT server, returns error on failure or nil on success
func (*Connection) GetCcon ¶ added in v0.1.4
func (con *Connection) GetCcon() *C.rcComm_t
func (*Connection) QueryMeta ¶ added in v0.1.1
func (con *Connection) QueryMeta(qString string) (response IRodsObjs, err error)
QueryMeta
func (*Connection) ReturnCcon ¶ added in v0.1.4
func (con *Connection) ReturnCcon(ccon *C.rcComm_t)
func (*Connection) SearchDataObjects ¶ added in v0.1.1
func (con *Connection) SearchDataObjects(dataObjPath string) (dataobj *DataObj, err error)
SearchDataObjects searchs for and returns DataObjs slice based on a search string. Use '%' as a wildcard. Equivalent to ilocate command
func (*Connection) SetTicket ¶ added in v0.1.2
func (con *Connection) SetTicket(t string) error
SetTicket is equivalent to using the -t flag with icommands
func (*Connection) String ¶
func (obj *Connection) String() string
String provides connection status and options provided during initialization (gorods.New)
type ConnectionOptions ¶
type ConnectionOptions struct { Type int Host string Port int Zone string Username string Password string Ticket 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 Checksum string Size int64 Offset int64 Type int DataId string Resource string PhyPath string OpenedAs C.int OwnerName string CreateTime int ModifyTime 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, error)
CreateDataObj creates and adds a data object to the specified collection using provided options. Returns the newly created data object.
func (*DataObj) Attribute ¶
Attribute gets slice of Meta AVU triples, matching by Attribute name for DataObj
func (*DataObj) CopyTo ¶
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 error.
func (*DataObj) DeleteMeta ¶ added in v0.1.1
func (obj *DataObj) DeleteMeta(attr string) (*MetaCollection, error)
DeleteMeta deletes a single Meta triple struct, identified by Attribute field
func (*DataObj) DownloadTo ¶
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 error.
func (*DataObj) GetCol ¶ added in v0.1.1
func (obj *DataObj) GetCol() *Collection
GetName returns the *Collection of the data object
func (*DataObj) GetCon ¶ added in v0.1.1
func (obj *DataObj) GetCon() *Connection
Connection returns the *Connection used to get data object
func (*DataObj) GetCreateTime ¶ added in v0.1.4
GetCreateTime returns the create time of the data object
func (*DataObj) GetModifyTime ¶ added in v0.1.4
GetModifyTime returns the modify time of the data object
func (*DataObj) GetOwnerName ¶ added in v0.1.4
GetOwnerName returns the owner name of the data object
func (*DataObj) Meta ¶
func (obj *DataObj) Meta() (*MetaCollection, error)
Meta returns collection of Meta AVU triple structs of the data object
func (*DataObj) MoveTo ¶
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 error.
func (*DataObj) MoveToResource ¶
NEED TO IMPLEMENT
func (*DataObj) OpenRW ¶ added in v0.1.4
OpenRW opens a connection to iRods and sets the data object handle for read/write access
func (*DataObj) Read ¶
Read reads the entire data object into memory and returns a []byte slice. Don't use this for large files.
func (*DataObj) ReadBytes ¶
ReadBytes reads bytes from a data object at the specified position and length, returns []byte slice and error.
func (*DataObj) ReadChunk ¶
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 ¶
Rename is equivalent to the Linux mv command except that the data object must stay within the current collection (directory), returns error.
func (*DataObj) ReplSettings ¶
NEED TO IMPLEMENT
func (*DataObj) Stat ¶
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) Unlink ¶
Unlink deletes the data object from the iRods server, no force flag is used
func (*DataObj) Verify ¶
Verify returns true or false depending on whether the checksum md5 string matches
func (*DataObj) Write ¶
Write writes the data to the data object, starting from the beginning. Returns error.
func (*DataObj) WriteBytes ¶
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 error.
type DataObjOptions ¶
DataObjOptions is used for passing options to the CreateDataObj function
type GoRodsError ¶
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 { GetType() int GetName() string GetPath() string GetCol() *Collection GetCon() *Connection GetOwnerName() string GetCreateTime() int GetModifyTime() int // irm -rf Destroy() error // irm -f {-r} Delete(bool) error // irm {-r} Trash(bool) error // irm {-r} {-f} Rm(bool, bool) error Meta() (*MetaCollection, error) Attribute(string) (Metas, error) AddMeta(Meta) (*Meta, error) DeleteMeta(string) (*MetaCollection, error) String() string Open() error Close() error }
IRodsObj is a generic interface used to detect the object type and access common fields
type IRodsObjs ¶ added in v0.1.1
type IRodsObjs []IRodsObj
func (IRodsObjs) Exists ¶ added in v0.1.1
Exists checks to see if a collection exists in the slice and returns true or false
func (IRodsObjs) Find ¶ added in v0.1.1
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 (IRodsObjs) FindRecursive ¶ added in v0.1.1
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 Meta ¶
type Meta struct { Attribute string Value string Units string Parent *MetaCollection }
Meta structs contain information about a single iRods metadata attribute-value-units (AVU) triple
func (*Meta) Delete ¶ added in v0.1.1
func (m *Meta) Delete() (*MetaCollection, error)
Delete deletes the current Meta struct from iRods object
func (*Meta) SetAll ¶ added in v0.1.1
SetAll will modify metadata AVU with all three paramaters (Attribute, Value, Unit)
type MetaCollection ¶
type MetaCollection struct { Metas Metas Obj IRodsObj Con *Connection }
MetaCollection is a collection of metadata AVU triples for a single data object
func (*MetaCollection) Add ¶ added in v0.1.1
func (mc *MetaCollection) Add(m Meta) (*Meta, error)
Add creates a new meta AVU triple, returns pointer to the created Meta struct
func (*MetaCollection) All ¶ added in v0.1.2
func (mc *MetaCollection) All() (Metas, error)
All returns a slice of all Meta structs in the MetaCollection
func (*MetaCollection) Delete ¶ added in v0.1.1
func (mc *MetaCollection) Delete(attr string) (err error)
Delete deletes the meta AVU triple from the data object, identified by it's Attribute field
func (*MetaCollection) Each ¶ added in v0.1.2
func (mc *MetaCollection) Each(iterator func(*Meta)) error
Each accepts an iterator function for looping over all Meta structs in the MetaCollection
func (*MetaCollection) First ¶ added in v0.1.4
func (mc *MetaCollection) First(attr string) (*Meta, error)
First finds the first matching Meta struct by it's Attribute field
func (*MetaCollection) Get ¶
func (mc *MetaCollection) Get(attr string) (Metas, error)
Get returns a Meta struct slice (since attributes can share the same name in iRods), matching by their Attribute field. Similar to Attribute() function of other types
func (*MetaCollection) ReadMeta ¶ added in v0.1.1
func (mc *MetaCollection) ReadMeta() error
ReadMeta clears existing metadata triples and grabs updated copy from iCAT server.
func (*MetaCollection) Refresh ¶ added in v0.1.1
func (mc *MetaCollection) Refresh() error
Refresh clears existing metadata triples and grabs updated copy from iCAT server. It's an alias of ReadMeta()
func (*MetaCollection) String ¶
func (mc *MetaCollection) String() string
String shows the contents of the meta collection.
Sample output:
Attr1: Val (unit: ) Attr2: Yes (unit: bool)
Notes ¶
Bugs ¶
iRods C API code outputs errors messages, need to implement connect wrapper (gorods_connect_env) from a lower level to suppress this output https://github.com/irods/irods/blob/master/iRODS/lib/core/src/rcConnect.cpp#L109