Documentation

Index

Constants

View Source
const (
	NoSessionID                       = -1
	MaxSupportedBinaryProtocolVersion = 28 // max protocol supported by this client
	MinSupportedBinaryProtocolVersion = 21 // min protocol supported by this client
	MinBinarySerializerVersion        = 22 // if server protocol version is less, use csv serde, not binary serde
	RequestNewSession                 = -4 // arbitrary negative number sent to start session
	DriverName                        = "ogonori OrientDB Go client"
	DriverVersion                     = "1.0"
	BinarySerialization               = "ORecordSerializerBinary" // do not change: required by server
	CsvSerialization                  = "ORecordDocument2csv"     // do not change: required by server
)

    internal client constants

    View Source
    const (
    	// OUTGOING
    	REQUEST_SHUTDOWN                       = 1
    	REQUEST_CONNECT                        = 2
    	REQUEST_DB_OPEN                        = 3
    	REQUEST_DB_CREATE                      = 4
    	REQUEST_DB_CLOSE                       = 5
    	REQUEST_DB_EXIST                       = 6
    	REQUEST_DB_DROP                        = 7
    	REQUEST_DB_SIZE                        = 8
    	REQUEST_DB_COUNTRECORDS                = 9
    	REQUEST_DATACLUSTER_ADD                = 10
    	REQUEST_DATACLUSTER_DROP               = 11
    	REQUEST_DATACLUSTER_COUNT              = 12
    	REQUEST_DATACLUSTER_DATARANGE          = 13
    	REQUEST_DATACLUSTER_COPY               = 14
    	REQUEST_DATACLUSTER_LH_CLUSTER_IS_USED = 16 // since 1.2.0
    	REQUEST_DATASEGMENT_ADD                = 20
    	REQUEST_DATASEGMENT_DROP               = 21
    	REQUEST_RECORD_METADATA                = 29 // since 1.4.0
    	REQUEST_RECORD_LOAD                    = 30
    	REQUEST_RECORD_CREATE                  = 31
    	REQUEST_RECORD_UPDATE                  = 32
    	REQUEST_RECORD_DELETE                  = 33
    	REQUEST_RECORD_COPY                    = 34
    	REQUEST_POSITIONS_HIGHER               = 36 // since 1.3.0
    	REQUEST_POSITIONS_LOWER                = 37 // since 1.3.0
    	REQUEST_RECORD_CLEAN_OUT               = 38 // since 1.3.0
    	REQUEST_POSITIONS_FLOOR                = 39 // since 1.3.0
    	REQUEST_COUNT                          = 40 // DEPRECATED: USE REQUEST_DATACLUSTER_COUNT
    	REQUEST_COMMAND                        = 41
    	REQUEST_POSITIONS_CEILING              = 42 // since 1.3.0
    	REQUEST_RECORD_HIDE                    = 43 // since 1.7
    	REQUEST_TX_COMMIT                      = 60
    	REQUEST_CONFIG_GET                     = 70
    	REQUEST_CONFIG_SET                     = 71
    	REQUEST_CONFIG_LIST                    = 72
    	REQUEST_DB_RELOAD                      = 73 // SINCE 1.0rc4
    	REQUEST_DB_LIST                        = 74 // SINCE 1.0rc6
    	REQUEST_PUSH_DISTRIB_CONFIG            = 80
    	// DISTRIBUTED
    	REQUEST_DB_COPY     = 90 // SINCE 1.0rc8
    	REQUEST_REPLICATION = 91 // SINCE 1.0
    	REQUEST_CLUSTER     = 92 // SINCE 1.0
    	REQUEST_DB_TRANSFER = 93 // SINCE 1.0.2
    	// Lock + sync
    	REQUEST_DB_FREEZE           = 94 // SINCE 1.1.0
    	REQUEST_DB_RELEASE          = 95 // SINCE 1.1.0
    	REQUEST_DATACLUSTER_FREEZE  = 96
    	REQUEST_DATACLUSTER_RELEASE = 97
    	// REMOTE SB-TREE COLLECTIONS
    	REQUEST_CREATE_SBTREE_BONSAI            = 110
    	REQUEST_SBTREE_BONSAI_GET               = 111
    	REQUEST_SBTREE_BONSAI_FIRST_KEY         = 112
    	REQUEST_SBTREE_BONSAI_GET_ENTRIES_MAJOR = 113
    	REQUEST_RIDBAG_GET_SIZE                 = 114
    
    	// INCOMING
    	RESPONSE_STATUS_OK    = 0
    	RESPONSE_STATUS_ERROR = 1
    	PUSH_DATA             = 3
    
    	// CONSTANTS
    	RECORD_NULL = -2 // TODO: these are dups -> I have them elsewhere: choose one and cleanup
    	RECORD_RID  = -3
    
    	// FOR MORE INFO:
    	// https://github.com/orientechnologies/orientdb/wiki/Network-Binary-Protocol#wiki-Compatibility
    	PROTOCOL_VERSION_21      = 21
    	PROTOCOL_VERSION_24      = 24
    	PROTOCOL_VERSION_25      = 25
    	PROTOCOL_VERSION_26      = 26
    	PROTOCOL_VERSION_27      = 27
    	CURRENT_PROTOCOL_VERSION = 28 // SENT AS SHORT AS FIRST PACKET AFTER SOCKET CONNECTION
    )

      command and server-related constants copied from Java OChannelBinaryProtocol

      View Source
      const (
      	// binary protocol sentinel values when reading single records
      	RecordNull = -2
      	RecordRID  = -3
      )
      View Source
      const (
      	UpdateOp operationType = 1
      	DeleteOp operationType = 2
      	CreateOp operationType = 3
      )

      Variables

      This section is empty.

      Functions

      func AddCluster

      func AddCluster(dbc *DBClient, clusterName string) (clusterID int16, err error)

        AddCluster adds a cluster to the current database. It is a database-level operation, so OpenDatabase must have already been called first in order to start a session with the database. The clusterID is returned if the command is successful.

        func CloseDatabase

        func CloseDatabase(dbc *DBClient) error

          CloseDatabase closes down a session with a specific database that has already been opened (via OpenDatabase). This should be called when exiting an app or before starting a connection to a different OrientDB database.

          func ConnectToServer

          func ConnectToServer(dbc *DBClient, adminUser, adminPassw string) error

            ConnectToServer logs into the OrientDB server with the appropriate admin privileges in order to execute server-level commands (as opposed to database-level commands). This must be called to establish a server session before any other server-level commands. The username and password required are for the server (admin) not any particular database.

            func CreateDatabase

            func CreateDatabase(dbc *DBClient, dbname string, dbtype constants.DatabaseType, storageType constants.StorageType) error

              CreateDatabase will create a `remote` database of the type and storageType specified. dbType must be type DocumentDBType or GraphDBType. storageType must type PersistentStorageType or VolatileStorageType.

              func CreateRecord

              func CreateRecord(dbc *DBClient, doc *oschema.ODocument) error

                Use this to create a new record in the OrientDB database you are currently connected to. Does REQUEST_RECORD_CREATE OrientDB cmd (binary network protocol).

                func DatabaseExists

                func DatabaseExists(dbc *DBClient, dbname string, storageType constants.StorageType) (bool, error)

                  DatabaseExists is a server-level command, so must be preceded by calling ConnectToServer, otherwise an authorization error will be returned. The storageType param must be either PersistentStorageType or VolatileStorageType.

                  func DeleteRecordByRID

                  func DeleteRecordByRID(dbc *DBClient, rid string, recVersion int32) error

                    DeleteRecordByRID deletes a record specified by its RID and its version. This is the synchronous version where the server confirms whether the delete was successful and the client reports that back to the caller. See DeleteRecordByRIDAsync for the async version.

                    If nil is returned, delete succeeded. If error is returned, delete request was either never issued, or there was a problem on the server end or the record did not exist in the database.

                    func DeleteRecordByRIDAsync

                    func DeleteRecordByRIDAsync(dbc *DBClient, rid string, recVersion int32) error

                    func DropCluster

                    func DropCluster(dbc *DBClient, clusterName string) error

                      DropCluster drops a cluster to the current database. It is a database-level operation, so OpenDatabase must have already been called first in order to start a session with the database. If nil is returned, then the action succeeded.

                      func DropDatabase

                      func DropDatabase(dbc *DBClient, dbname string, dbtype constants.DatabaseType) error

                        DropDatabase drops the specified database. The caller must provide both the name and the type of the database. The type should either:

                        obinary.DocumentDBType
                        obinary.GraphDBType
                        

                        This is a "server" command, so you must have already called ConnectToServer before calling this function.

                        func ExecTransaction

                        func ExecTransaction(txentries []TxEntry) error

                        func FetchClusterCount

                        func FetchClusterCount(dbc *DBClient, clusterNames ...string) (count int64, err error)

                          FetchClusterCountIncludingDeleted gets the number of records in all the clusters specified. The count does NOT include deleted records in autosharded storage. Use FetchClusterCountIncludingDeleted if you want the count including deleted records

                          func FetchClusterCountIncludingDeleted

                          func FetchClusterCountIncludingDeleted(dbc *DBClient, clusterNames ...string) (count int64, err error)

                            GetClusterCountIncludingDeleted gets the number of records in all the clusters specified *including* deleted records (applicable for autosharded storage only)

                            func FetchClusterDataRange

                            func FetchClusterDataRange(dbc *DBClient, clusterName string) (begin, end int64, err error)

                              FetchClusterDataRange returns the range of record ids for a cluster

                              func FetchDatabaseSize

                              func FetchDatabaseSize(dbc *DBClient) (int64, error)

                                FetchDatabaseSize retrieves the size of the current database in bytes. It is a database-level operation, so OpenDatabase must have already been called first in order to start a session with the database.

                                func FetchEntriesOfRemoteLinkBag

                                func FetchEntriesOfRemoteLinkBag(dbc *DBClient, linkBag *oschema.OLinkBag, inclusive bool) error

                                  FetchEntriesOfRemoteLinkBag fills in the links of an OLinkBag that is remote (tree-based) rather than embedded. This function will fill in the links of the passed in OLinkBag, rather than returning the new links. The Links will have RIDs only, not full Records (ODocuments). If you then want the Records filled in, call the ResolveLinks function.

                                  func FetchFirstKeyOfRemoteLinkBag

                                  func FetchFirstKeyOfRemoteLinkBag(dbc *DBClient, linkBag *oschema.OLinkBag) (*oschema.OLink, error)

                                    FetchFirstKeyOfRemoteLinkBag is the entry point for retrieving links from a remote server-side side LinkBag. In general, this method should not be called by end users. Instead, end users should call FetchEntriesOfRemoteLinkBag

                                    TODO: make this an unexported func?

                                    func FetchNumRecordsInDatabase

                                    func FetchNumRecordsInDatabase(dbc *DBClient) (int64, error)

                                      FetchNumRecordsInDatabase retrieves the number of records of the current database. It is a database-level operation, so OpenDatabase must have already been called first in order to start a session with the database.

                                      func FetchRecordByRID

                                      func FetchRecordByRID(dbc *DBClient, orid oschema.ORID, fetchPlan string) ([]*oschema.ODocument, error)

                                        FetchRecordByRID takes an ORID and reads that record from the database. NOTE: for now I'm assuming all records are Documents (they can also be "raw bytes" or "flat data") and for some reason I don't understand, multiple records can be returned, so I'm returning a slice of ODocument

                                        TODO: may also want to expose options: ignoreCache, loadTombstones bool TODO: need to properly handle fetchPlan

                                        func FetchSizeOfRemoteLinkBag

                                        func FetchSizeOfRemoteLinkBag(dbc *DBClient, linkBag *oschema.OLinkBag) (int, error)

                                          Large LinkBags (aka RidBags) are stored on the server. To look up their size requires a call to the database. The size is returned. Note that the Size field of the linkBag is NOT updated. That is left for the caller to decide whether to do.

                                          func OpenDatabase

                                          func OpenDatabase(dbc *DBClient, dbname string, dbtype constants.DatabaseType, username, passw string) error

                                            OpenDatabase sends the REQUEST_DB_OPEN command to the OrientDB server to open the db in read/write mode. The database name and type are required, plus username and password. Database type should be one of the obinary constants: DocumentDBType or GraphDBType.

                                            func ReloadSchema

                                            func ReloadSchema(dbc *DBClient) error

                                              ReloadSchema should be called after a schema is altered, such as properties added, deleted or renamed.

                                              func RequestDBList

                                              func RequestDBList(dbc *DBClient) (map[string]string, error)

                                                RequestDBList works like the "list databases" command from the OrientDB client. The result is put into a map, where the key of the map is the name of the database and the value is the type concatenated with the path, like so:

                                                key:  cars
                                                val:  plocal:/path/to/orientdb-community-2.0.1/databases/cars
                                                
                                                func ResolveLinks(dbc *DBClient, links []*oschema.OLink) error

                                                  ResolveLinks iterates over all the OLinks passed in and does a FetchRecordByRID for each one that has a null Record. TODO: maybe include a fetchplan here?

                                                  func SQLCommand

                                                  func SQLCommand(dbc *DBClient, sql string, params ...string) (retval string, docs []*oschema.ODocument, err error)

                                                    SQLCommand executes SQL commands that are not queries. Any SQL statement that does not being with "SELECT" should be sent here. All SELECT statements should go to the SQLQuery function.

                                                    Commands can be optionally paramterized using ?, such as:

                                                    INSERT INTO Foo VALUES(a, b, c) (?, ?, ?)
                                                    

                                                    The values for the placeholders (currently) must be provided as strings.

                                                    Constraints (for now): 1. cmds with only simple positional parameters allowed 2. cmds with lists of parameters ("complex") NOT allowed 3. parameter types allowed: string only for now

                                                    SQL commands in OrientDB tend to return one of two types - a string return value or one or more documents. The meaning are specific to the type of query.

                                                    ---------------- For example: ----------------

                                                    for a DELETE statement:
                                                      retval = number of rows deleted (as a string)
                                                      docs = empty list
                                                    
                                                    for an INSERT statement:
                                                      n = ?
                                                      docs = ?
                                                    
                                                    for an CREATE CLASS statement:
                                                      retval = cluster id of the class (TODO: or it might be number of classes in cluster)
                                                      docs = empty list
                                                    
                                                    for an DROP CLASS statement:
                                                      retval = "true" if successful, "" if class didn't exist (technically it returns null)
                                                      docs = empty list
                                                    

                                                    func SQLQuery

                                                    func SQLQuery(dbc *DBClient, sql string, fetchPlan string, params ...string) ([]*oschema.ODocument, error)

                                                      SQLQuery

                                                      TODO: right now I return the entire resultSet as an array, thus all loaded into memory

                                                      it would be better to have obinary.dbCommands provide an iterator based model
                                                      that only needs to read a "row" (ODocument) at a time
                                                      

                                                      Perhaps SQLQuery() -> iterator/cursor

                                                      SQLQueryGetAll() -> []*ODocument ??
                                                      

                                                      func UpdateRecord

                                                      func UpdateRecord(dbc *DBClient, doc *oschema.ODocument) error

                                                        UpdateRecord should be used update an existing record in the OrientDB database. It does the REQUEST_RECORD_UPDATE OrientDB cmd (network binary protocol)

                                                        Types

                                                        type ClientOptions

                                                        type ClientOptions struct {
                                                        	ServerHost string
                                                        	ServerPort string
                                                        }

                                                          ClientOptions should be created by the end user to configure details and options needed when opening a database or connecting to the OrientDB server

                                                          type DBClient

                                                          type DBClient struct {
                                                          	RecordSerDes []ORecordSerializer
                                                          	// contains filtered or unexported fields
                                                          }

                                                            DBClient encapsulates the active TCP connection to an OrientDB server to be used with the Network Binary Protocol. It also may be connected to up to one database at a time. Do not create a DBClient struct directly. You should use NewDBClient, followed immediately by ConnectToServer, to connect to the OrientDB server, or OpenDatabase, to connect to a database on the server.

                                                            func NewDBClient

                                                            func NewDBClient(opts ClientOptions) (*DBClient, error)

                                                              NewDBClient creates a new DBClient after contacting the OrientDB server specified in the ClientOptions and validating that the server and client speak the same binary protocol version. The DBClient returned is ready to make calls to the OrientDB but has not yet established a database session or a session with the OrientDB server. After this, the user needs to call either OpenDatabase or CreateServerSession.

                                                              func (*DBClient) Close

                                                              func (dbc *DBClient) Close() error

                                                              func (*DBClient) GetCurrDB

                                                              func (dbc *DBClient) GetCurrDB() *ODatabase

                                                                ---[ getters for testing ]---

                                                                func (*DBClient) GetSessionID

                                                                func (dbc *DBClient) GetSessionID() int32

                                                                func (*DBClient) String

                                                                func (dbc *DBClient) String() string

                                                                type ErrUnsupportedVersion

                                                                type ErrUnsupportedVersion struct {
                                                                	// contains filtered or unexported fields
                                                                }

                                                                func (ErrUnsupportedVersion) Error

                                                                func (e ErrUnsupportedVersion) Error() string

                                                                type OCluster

                                                                type OCluster struct {
                                                                	Name string
                                                                	Id   int16
                                                                }

                                                                type ODatabase

                                                                type ODatabase struct {
                                                                	Name             string
                                                                	Typ              constants.DatabaseType
                                                                	Clusters         []OCluster
                                                                	ClustCfg         []byte                // TODO: why is this a byte array? Just placeholder? What is it in the Java client?
                                                                	StorageCfg       OStorageConfiguration // TODO: redundant to ClustCfg ??
                                                                	SchemaVersion    int32
                                                                	GlobalProperties map[int]oschema.OGlobalProperty // key: property-id (aka field-id)
                                                                	Classes          map[string]*oschema.OClass      // key: class name (TODO: check how Java client does it)
                                                                }

                                                                func NewDatabase

                                                                func NewDatabase(name string, dbtype constants.DatabaseType) *ODatabase

                                                                type ORecordSerializer

                                                                type ORecordSerializer interface {
                                                                	//
                                                                	// Deserialize reads bytes from the bytes.Buffer and puts the data into the
                                                                	// ODocument object.  The ODocument must already be created; nil cannot be
                                                                	// passed in for the `doc` field.  The serialization version (the first byte
                                                                	// of the serialized record) should be stripped off (already read) from the
                                                                	// io.Reader being passed in
                                                                	//
                                                                	Deserialize(dbc *DBClient, doc *oschema.ODocument, buf *obuf.ReadBuf) error
                                                                
                                                                	//
                                                                	// Deserialize reads bytes from the io.Reader and updates the ODocument object
                                                                	// passed in, but only for the fields specified in the `fields` slice.
                                                                	// The ODocument must already be created; nil cannot be passed in for the `doc` field.
                                                                	// TODO: unclear if this is necessary -> idea comes from the Java client API
                                                                	//
                                                                	DeserializePartial(doc *oschema.ODocument, buf io.Reader, fields []string) error
                                                                
                                                                	//
                                                                	// Serialize reads the ODocument and serializes to bytes into the bytes.Buffer.
                                                                	//
                                                                	Serialize(dbc *DBClient, doc *oschema.ODocument) ([]byte, error)
                                                                
                                                                	//
                                                                	// SerializeClass gets the class from the ODocument and serializes it to bytes
                                                                	// into the bytes.Buffer.
                                                                	//
                                                                	SerializeClass(doc *oschema.ODocument) ([]byte, error)
                                                                }

                                                                  ORecordSerializer is the interface for the binary Serializer/Deserializer. More than one implementation will be needed if/when OrientDB creates additional versions of the binary serialization format. TODO: may want to use this interface for the csv serializer also - if so need to move this interface up a level

                                                                  type ORecordSerializerV0

                                                                  type ORecordSerializerV0 struct {
                                                                  	// contains filtered or unexported fields
                                                                  }

                                                                    ORecordSerializerV0 implements the ORecordSerializerBinary interface for version 0.

                                                                    ORecordSerializerV0 is NOT thread safe. Each DBClient should keep its own private serializer object.

                                                                    func (ORecordSerializerV0) Deserialize

                                                                    func (serde ORecordSerializerV0) Deserialize(dbc *DBClient, doc *oschema.ODocument, buf *obuf.ReadBuf) (err error)

                                                                      The serialization version (the first byte of the serialized record) should be stripped off (already read) from the io.Reader being passed in.

                                                                      func (ORecordSerializerV0) DeserializePartial

                                                                      func (serde ORecordSerializerV0) DeserializePartial(doc *oschema.ODocument, buf io.Reader, fields []string) error

                                                                        TODO: need to study what exactly this method is supposed to do and not do

                                                                        -> check the Java driver version
                                                                        

                                                                        IDEA: maybe this could be DeserializeField? Might be useful for RidBags. Anything else?

                                                                        func (ORecordSerializerV0) Serialize

                                                                        func (serde ORecordSerializerV0) Serialize(dbc *DBClient, doc *oschema.ODocument) ([]byte, error)

                                                                          Serialize takes an ODocument and serializes it to bytes in accordance with the OrientDB binary serialization spec and writes them to the bytes.Buffer passed in.

                                                                          func (ORecordSerializerV0) SerializeClass

                                                                          func (serde ORecordSerializerV0) SerializeClass(doc *oschema.ODocument) ([]byte, error)

                                                                          type OStorageConfiguration

                                                                          type OStorageConfiguration struct {
                                                                          	// contains filtered or unexported fields
                                                                          }

                                                                            OStorageConfiguration holds (some of) the information in the "Config Record" #0:0. At this time, I'm throwing away a lot of the info in record #0:0 until proven that the ogonori client needs them.

                                                                            type TxEntry

                                                                            type TxEntry struct {
                                                                            	Optype operationType
                                                                            	Doc    *oschema.ODocument
                                                                            }

                                                                            func (TxEntry) String

                                                                            func (txe TxEntry) String() string

                                                                            Directories

                                                                            Path Synopsis
                                                                            varint
                                                                            Package varint is used for the OrientDB schemaless serialization where variable size integers are used with zigzag encoding to convert negative integers to a positive unsigned int format so that smaller integers (whether negative or positive) can be transmitted in less than 4 bytes on the wire.
                                                                            Package varint is used for the OrientDB schemaless serialization where variable size integers are used with zigzag encoding to convert negative integers to a positive unsigned int format so that smaller integers (whether negative or positive) can be transmitted in less than 4 bytes on the wire.
                                                                            rw is the read-write package for reading and writing types from the OrientDB binary network protocol.
                                                                            rw is the read-write package for reading and writing types from the OrientDB binary network protocol.