Copyrighted 2010 - 2013 EOSSOnline Limited (New Zealand)
www.eossonline.com
INTRODUCTION :
See the changes.txt file for details of changes between releases.
eDrive is a utility of the EOSS Stack developed by EOSSOnline Limited and is
designed to be run as a service on your computer.It is designed to Synchronise
directories on any file system to any CMIS enabled Repositories.
eDrive can manage zero or more Synchronisers, each of which can Synchronise one
directory structure on File System to one Folder structure in a CMIS Repository.
Each Synchroniser can connect to different Repositories.
eDrive is highly configurable and should be able to cater for any use case
regarding Synchronisation. It is however important to point out that eDrive is
NOT designed as a utility for Bulk Import into a CMIS enabled Content
Repository.
eDrive has been tested with only the Alfresco ECMS community version 4.2.x and
the Apache Chemistry In-Memory Repository. However, it is written using the
Apache Chemistry OpenCMIS library and should therefore be compatible with any
CMIS 1.0 or 1.1 compliant Content Repository.
CONFIGURATION :
NOTE : eDrive requires Java 7 as it uses the NIO classes File, Paths and Path.
Since eDrive version 0.1.3 it now remembers the last state of each
Synchroniser and restores this on startup. This results in much less
load on the machine running eDrive at startup which means it's much
less important to reconfigure the default JVM memory settings or the
number of threads for both the inbound and outbound processors.
JVM Settings :
(a) -Xmx -Xms
eDrive will run with the default Java settings but you should set the
-Xmx and -Xms values to around 128m. eDrive is not very memory hungry it's
self, but does require memory when Synchronising Documents, especially
large ones. The more Documents in your hierarchy that need syncing the
more memory may be required. Under reasonable initial load we generally
set both -Xmx and -Xms to 256m and have had no issues.
(b) -Dedrive.config.file=<file path>
The edrive.config.file points to a JSON file on your local file system
that eDrive will use to load and save configurations to. If this property
is not set it will default to "user.home"/eDrive.json
(c) -Dedrive.server.port=<port number>
eDrive incorporates a Command Server that can be used to configure and
query eDrive. This is the port that clients can connect to eDrive.
You can use telnet as a client and we generally use telnet with the
rlwrap utility for command history with up and down arrow support.
rlwrap telnet <host | IP> <port>
If edrive.server.port is not set, or is set to 0, it will pick an
available port to listen on which will be reported in the log file at log
level INFO. In general, it is best to set this value so that you can
connect to it in the future with a dedicated client.
If there are any Errors while initialising the Command Server it will NOT
be available.
Multiple Clients can be connected to the Command Server at the same time.
(d) -Dedrive.multicast.ip=<Multicast IP>
-Dedrive.multicast.port=<port number>
eDrive incorporates a Multicast Server that can be used to listen for
eDrive Events such as Sync Events. You MUST specify the
edrive.multicast.ip and it MUST be a valid Multicast IP on your computer.
To check what Multicast IP's are available you can run :
(Windows) netsh interface ip show joins
(Linux / mac OSX) netstat -g
If the edrive.multicast.port is not set it will default to 0 and the first
available port will be selected. The Multicast Group IP and port are
reported in the log file at log level INFO.
eDrive ships with a simple Multicast Listener that can be run
independently to view the generated Events.
java com.eossonline.utils.MulticastListener <Multicast Group IP> <port>
NOTE :
The eDriveEvents are generated by AOP LTW (Load Time Weaving). To enable
these events to be generated and thus be multicast to the multicast
group, you need to use the aspectj weaver in the JVM options. To enable
the eDriveEventAspect to weave it's magic add the following to your JVM
arguments.
-javaagent:<path to aspectj>/aspectjweaver-<version>.jar
Alternatively, you could pre-weave the eSync jar file and add that to
classpath, this agent setting would not then be required.
(e) -Desync.inbound.threads=<num>
eDrive has an Inbound Processor to Synchronise content from the Repository
to the File System. By default eDrive will allocate 20 concurrent threads
to process this content. You can override this default with this property.
If you have large amounts of changes in your Repository you may want to
change this to a higher number. Otherwise just leave it be.
(f) -Desync.outbound.threads=<num>
eDrive has an Outbound Processor to Synchronise content from the File
System to the Repository. By default eDrive will allocate 20 concurrent
threads to process this content. You can override this default with this
property. If you have large amounts of changes in your File System you may
want to change this to a higher number. Otherwise just leave it be.
(g) -Desync.inbound.sync.seconds=<num>
By default eDrive will Synchronise content from the Repository to the File
System every 20 seconds. This time is a minimum time between Sync Cycles.
If processing the changes identified in a single Sync Cycle takes longer
than this time, a new Sync Cycle will start immediately after this one has
finished.
Generally the very first Sync Cycle after startup will take longer and
require more resources. After this it should settle down for subsequent
Sync Cycles as the processor will generally only be interested in the
differences between snapshots taken at each Sync Cycle. You can use this
property to set the initial default Sync Cycle for each Synchroniser
managed by eDrive. This value can however be overridden in each
Synchroniser later using the Command Server.
(h) -Desync.outbound.sync.seconds=<num>
By default eDrive will Synchronise content from the File System to the
Repository every 20 seconds. This time is a minimum time between Sync
Cycles. If processing the changes identified in a single Sync Cycle takes
longer than this time, a new Sync Cycle will start immediately after this
one has finished.
Generally the very first Sync Cycle after startup will take longer and
require more resources. After this it should settle down for subsequent
Sync Cycles as the processor will generally only be interested in the
differences between snapshots taken at each Sync Cycle. You can use this
property to set the initial default Sync Cycle for each Synchroniser
managed by eDrive. This value can however be overridden in each
Synchroniser later using the Command Server.
(i) -Dedrive.passphrase.file=<file path>
eDrive stores the repositoryUserName as an encrypted value. This property
identifies a file on the File System that contains a Pass Phase used to
encode this password. If the edrive.passphrase.file property is not
defined, eDrive will try to locate a file called eDrive.pass in the users
home directory.
If eDrive is unable to locate a Pass Phase file it will use a default Pass
Phrase instead. A Pass phrase can be any number of characters but must be
at least 8. eDrive uses the bouncy castle library for encryption. If the
repositoryPassword element is stored in clear text in the JSON file
identified by the edrive.config.file property (see (b) above) it will be
stored encrypted internally and will be stored encrypted when Synchroniser
Configurations are stored to disk.
If this property is not set it will try to locate a default file at
"user.home"/eDrive.pass
You may have noticed that eDrive uses both edrive.xxx.xxx and esync.xxx.xxx
properties. This is because the underlying functionality of eDrive is provided
by the EOSS ESync library. eDrive uses AOP to identify pointcuts within the
ESync library and advice's these to generate the eDriveEvent(s) published by
the eDrive Multicast Server.
USAGE :
eDrive Command Server :
The eDrive Command Server is a simple socket server that listens for client
connections, spawning a thread for each. The Protocol and command structure
is very simple and is intended for easy usage by third part clients such as
a REST server, native Windows Explorer plugin, Nautilus plugin etc etc.
For testing and playing around with the server we generally use Telnet with
the Read Line wrapper utility rlwrap which provides command history through
the up and down arrow keys as well as editing of command prior to sending
the requests to Telnet. Without the use of rlwrap Telnet is difficult to use
as ALL key strokes are interpreted as command characters and neither editing
not command history would be possible without incorporating that in the
actual Command Server.
rlwrap telnet <host | IP> <port>
The eDrive Command Server accepts either 1 or 2 word commands, of which may
take a parameters object which must be represented in valid JSON format i.e.
{"name":"A name", "syncing":true, "paths": []}
This JSON String represent a String keyed by "name", a Boolean keyed by
"syncing" and an empty array keyed by "paths".
The first word of a command is the primary command and depending on the
command it may be required to provide a secondary command and or a JSON
parameter object.
In the commands below O and [] are optional and both M and {} are mandatory.
[JSON param] optionally provide a JSON string.
O {"repositoryId":"ABCDEFG"}
{JSON param} you must provide a JSON string.
M {"name":"My Sync"}
All commands with the exception of (help | licence | quit | test) return the
Configuration after applying the command. UNLESS they result in either an
ERROR or an EXCEPTION.
COMMANDS :
Commands can be sent as either a pure JSON String in the format :
{"command":"<Command>", "params":{<JSON String>}}
An example :
{"command":"get configuration","params":{"name":"My eDrive"}}
is equivalent to :
get configuration {"name":"My eDrive"}
Another example :
{"command":"save"}
is equivalent to :
save
Either form is acceptable but the JSON String version MUST conform as follows:
M "command" - i.e "command":"get configuration"
O "params" - i.e. "params":{"name":"My eDrive"} - Required if the command
requires parameters.
NOTE : It is perfectly acceptable to add ALL necessary configuration to
the JSON configuration file identified by the
-Dedrive.config.file by hand. If editing a JSON file is better for
your situation then just go ahead and edit the file directly.
Some checks, such as valid types for Documents and Folders, will
be automatically applied. Others will fail when trying to connect
to the Repository.
(a) help
Returns this README document.
(b) licence
returns the Apache 2.0 LICENCE file
(c) quit
This will terminate the connection for this Client returning the text
"Good by..." before doing so. This text string can be used by clients to
identify a connection closed.
Returns "Good by..."
(d) save
This will save the current internal representation of all the configured
Synchronisers to the file identified by the
-Dedrive.config.file=<file path> JVM property.
If the property is missing it will save to a file named eDrive.json in
the users home directory.
If save is not called by the client, eDrive will NOT override the
original JSON configuration file if there was one.
Returns configuration for ALL Synchronisers
(e) disable [JSON param]
If no JSON parameter is provided this command will disable ALL of the
currently configured Synchronisers. Disabling a Synchroniser just pauses
further synchronisations once the current Sync Cycle has finished.
Disabling an already disabled Synchroniser has no effect.
To target a particular Synchroniser you must provide a valid JSON string
containing at least the name of the Synchroniser you which to disable.
i.e. {"name":"My sync 1"}
The Command will ignore all other elements in
the JSON string but if it does not contain a valid Synchroniser name it
will disable ALL currently enabled Synchronisers.
disable
disable {"name","My Sync"}
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(f) enable [JSON param]
If no JSON parameter is provided this command will enable ALL of the
currently configured Synchronisers.Enabling a Synchroniser just
un-pauses it and synchronisation will continue. Enabling an already
enabled Synchroniser has no effect.
To target a particular Synchroniser you must provide a valid JSON string
containing at least the name of the Synchroniser you which to enable.
i.e. {"name":"My sync 1"}
The Command will ignore all other elements in the JSON string but if it
does not contain a valid Synchroniser name it will enable ALL currently
disabled Synchronisers.
enable
enable {"name","My Sync"}
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(g) test connection {JSON param}
This command is used by clients to test a connection to a Repository.
If you are setting up a new Synchroniser you will want to call this
command first.
The following JSON parameters are acceptable
M "repositoryUrl" - This is the URL to the WEB Services CMIS endpoint.
You do NOT provide the RepositoryService part of the URL i.e.
http://localhost:8080/alfresco/cmisws
http://localhost:9090/chemistry/services
"repositoryUrl":"http://localhost:8080/alfresco/cmisws"
M "repositoryUserName" - The user to connect to the Repository as.
Even if your Repository accepts connections with no credentials,
you need to provide this as an empty string.
"repositoryUserName":"guest"
M "repositoryPassword" - The password for the Repository user.
Even if your Repository accepts connections with no credentials,
you need to provide this as an empty string.
"repositoryPassword":"guest"
O "repositoryId" - The ID of a Repository in the CMS
Some Repositories support more than one Repository. If this is the
case for your Repository you can provide this value to identify the
Repository you are interested in connecting to.
If you do not provide this value then eDrive will query ALL of the
Repositories in your CMS.
"repositoryId":"A1"
O "getFolders" - Ask eDrive to return a list of the Folders from the
ROOT of each Repository
If this property is provided and set to true, eDrive will navigate
the Folder tree of the Repository identified by the "repositoryId"
property, or ALL Repositories if "repositoryId" is not provided.
Each Folder returned has either a true or false boolean value that
indicated whether or not the user connecting to the Repository has
WRITE permission.
If this property is not provided eDrive will NOT navigate the Folder
tree of the Repository.
These results can be used by a Client to provide a list of available
Sync Folders to the user.
BEWARE : If your Repository contains a lot of Folders, this call may
take some time.
"getFolders":true
O "startFolder" - Where eDrive should start navigating the Folder
structure from in the Repository
This property is ONLY used if "getFolders" is set to true.
If your Repository has a lot of Folders you can user this property
to restrict the Folder navigation eDrive performs.
O "proxyUserName" - If connecting through a proxy you can provide
the name of the proxy user.
O "proxyPassword" - If connecting through a proxy this is the password
of the proxy user.
NOTE : If you do not specify "repositoryId" and your CMS supports
more than one Repository, it is likely that this Folder will
match only one of them. In this case, eDrive will navigate
the Folder structure of every other Repository from the ROOT
Folder.
Likewise, if eDrive is unable to locate this Folder in the
Repository it will navigate the entire Repository Folder
structure from the ROOT.
"startFolder":"\\User Homes"
A complete JSON string for this call could be :
{
"repositoryUrl": "http://localhost:9090/alfresco/cmisws",
"repositoryUserName": "steve",
"repositoryPassword": "steve",
"getFolders": true,
"startFolder": "/User Homes"
}
And a result could look like :
{
"result": {
"repositories": [
{
"id":"253cc3ea-9b12-492c-b9ad-26a67c2b7f20",
"description":"Main Repository",
"vendor":"Alfresco",
"folders": [
{
"/User Homes/steve/sync/some docs": true,
"/User Homes": false,
"/User Homes/steve": true
}
],
"productVersion":"4.2.0 (4576)",
"productName":"Alfresco Repository (contentUrl=|mimetype=|size=0|encoding=|locale=en_US_|id=120)"
}
]
},
"status": "OK"
}
(h) add (mime-mapping | synchroniser | ignore-pattern) {JSON param}
(i) add mime-mapping {JSON param}
This command will add one or more mime type mappings to a
Configuration. When a Synchroniser creates a Document in the
Repository it has to define the base type to use for that Document.
The default document type is set to cmis:document and this is the
type that will be used for all Documents no matter what the MIME type
of the content is. Using this command you can override the default
document type for content of specific MIME types.
If any mappings already exist for a documentType, this command will
add the new mimeTypes to the existing mapping, otherwise it will creat
a new mapping.
This JSON param object can be either an Array of mime mappings or a
single mime mapping.
The following show examples of each type of JSON param :
{
"mimeMappings": [
{"documentType":"customDocument", "mimeTypes":"text/xml,text/html"},
{"documentType":"anotherType", "mimeTypes":"application/x-gzip"}
]
}
{
"name":"My EDrive",
"documentType":"D:cmiscustom:document", "mimeTypes":"video/mpeg"
}
In the first example there are 2 document types being set and in
the second example there is only 1 document type being set.
In the first example ALL Synchronisers will have the two mappings
added and in the second, only the Synchroniser named "My EDrive"
will have the mappings added.
Once a mapping is set, if any content is to be created in the
Repository where the MIME type matches any of these, the Synchroniser
will use the type specified by the "documentType" instead of the
default "cmis:document" type.
M "documentType" - The document type to use. Must be in the Repository
M "mimeTypes" - One or more comma separated MIME types.
O "name" - The name of a specific Synchroniser.
If "name" is not defined, eDrive will add the ignore pattern to ALL
configured Synchronisers.
NOTE :
eDrive will check that the documentType defined actually exists in
the Repository before setting the type. It will also check that the
Type is actually a descendant of the "cmis:document" first.
If these conditions are not met you will get an EXCEPTION response.
It does NOT check the mime types are valid. If they are invalid,
they will just never match and the documentType will not be used.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(ii) add synchroniser {JSON param}
This command will add a new Synchroniser to eDrive. The JSON String
MUST contain ALL of the MANDATORY properties.
M "repositoryUrl" - The URL of the repository to Synchronise.
M "repositoryUserName" - The user to connect to the Repository as.
M "repositoryPassword" - The password for the user connecting to the
Repository. For the add command this should be in plain text.
eDrive will then encrypt this internally and only the encrypted
version will be returned when displaying configurations.
M "name" - The name of the Synchroniser. This MUST be unique among
Synchronisers.
M "repositoryRoot" - The ROOT Folder to Synchronise in the Repository.
If this Folder overlaps ANY other configured Synchroniser's
repositoryRoot, the add request will be rejected and an JSONObject
containing the Error will be returned.
M "fileSystemRoot" - The ROOT Directory on the File System to
Synchronise.
If this Directory overlaps ANY other configured Synchroniser's
fileSystemRoot, the add request will be rejected and an JSONObject
containing the Error will be returned.
NOTE : To avoid issues with Synchronisation it is NOT valid to have two
Synchronisers syncing to the same hierarchies in any overlapping way.
If the "fileSystemRoot" does not exist then eDrive will attempt to
create it. If eDrive is unable to create the Directory for some reason
i.e. a regular file with that name exists already, eDrive will return a
JSONObject with the Exception details.
O "enabled" - Is Synchroniser enabled or disabled. Defaults to true.
O "outboundSyncSecond" - The minimum time between syncs from the
File System to the Repository. Defaults to 20.
O "inboundSyncSeconds" - The minimum time between syncs from the
Repository to the File System. Defaults to 20.
O "syncDirection" - Can be one of TO_REPOSITORY, FROM_REPOSITORY,
TO_REPOSITORY_DELETE_SOURCE, BI_DIRECTIONAL or NO_SYNC.
Default is BI_DIRECTIONAL.
1. TO_REPOSITORY - Only the OutboundProcessor will be enabled and
the Synchroniser will only Synchronise files on the File System to
the Repository.
2. FROM_REPOSITORY - Only the InboundProcessor will be enabled and
the Synchroniser will only Synchronise Documents in the Repository
to the File System.
3. TO_REPOSITORY_DELETE_SOURCE - Both the Inbound and Outbound
Processors are enabled but the InboundProcessor will ONLY consider
deletes. This direction is good for situations such as
Synchronising scanned documents from a Directory to the Repository
and the Repository then further processes those Documents and
moves them to a Processed Folder outside of the Folder structure
being Synchronised. Without this mode, the OutboundProcessor would
think the Document was missing from the Repository on the next
Sync Cycle and again try to upload it from the File System.
4. BI_DIRECTIONAL - Both the Inbound and Outbound Processors are
enabled and eDrive will do it's best to identify the latest
versions of Documents either within the Repository or on the File
System and keep them in sync.
5. NO_SYNC - Neither the Inbound or Outbound Processors will be
enabled and NO Synchronisation will take place.
O "unfilingEnabled" - If this is set to true and the Repository
supports unfiling of Documents eDrive will unfile Documents instead
of Deleting them. If unfiling is not supported eDrive will override
this value and set it to false.
O "repositoryDeleteEnabled" - If this property is set to false eDrive
will not Delete or Unfile any content from the Repository. The down
side of this setting is that any files deleted from the File System
will be recreated either at the next Sync Cycle or on restarting
eDrive. Defaults to true.
O "repositoryId" - If this property is set eDrive will attempt to
connect to the specified Repository. If eDrive is unable to connect
to this repository the request to add this Synchroniser will be
rejected. No default.
O "ignorePatterns" - This property contains an Array of one or more
Base64 Encoded regular expression. The ignorePatterns property is
intended to overcome the issue of editors creating temporary files
which eDrive would otherwise detect and attempt to Synchronise.
For example a single entry {"base64":"Lip+"} translates to the
regular expression .*~ which would exclude ANY File or Document
ending with the ~ character from being Synchronised.
As the ignorePatterns match against a whole path, they can also
be used to exclude entire Directory or Folder hierachies, For
instance, the pattern .*[\\\/]\.svn[\\\/].* would exclude any
Folder or Directory that has a /.svn/ or \.svn\ part in the path.
This pattern translates to LipbXFxcL11cLnN2bltcXFwvXS4q in
Base64 encoded format.
{"base64":"LipbXFxcL11cLnN2bltcXFwvXS4q"}
You may also want to add an ignorePattern for any Folder ending
with \.svn or /.svn just to stop the path being created. The
ignorePattern for this would be {"base64":"LipbXFxcL11cLnN2bg=="}
No Default.
O "paths" - This property defines an Array of Relative File System
paths from the "fileSystemRoot" Directory. Each entry in this Array
identifies a relative path to a Directory under the "fileSystemRoot"
that should or should not be synchronised. If the "syncing" property
is false for this path, eDrive will ignore ALL content in this
Directory (not it's sub Directories). If a defined path does not
exist under the "fileSystemRoot" it will be ignored. An example of a
"paths" property could be :
"paths": [
{
"syncing": true,
"path": ""
},
{
"syncing": true,
"path": "some docs"
},
{
"syncing": false,
"path": "some docs/sso_auth/sso_test/Debug"
}
]
In this example we are explicitly telling the OutboundProcessor to
NOT synchronise the the path "some docs\\sso_auth\\sso_test\\Debug"
under the "fileSystemRoot". The other 2 entries are infact not
necessary here because the default is is to synchronise Directories
and could therefore be re-written as
"paths": [
{
"syncing": false,
"path": "some docs/sso_auth/sso_test/Debug"
}
]
You will notice that when commands return the Current Configuration,
ALL paths in the Directory structure are included in the response
not just the disabled paths. The default is an empty Array.
Returns configuration for named Synchroniser
(iii) add ignore-pattern {JSON param}
Add one or more ignore pattern to a specific Synchroniser
or ALL configured Synchronisers.
O "ignorePatterns" - An Array of one or more ignore patterns.
See "ignorePatterns" property above.
O "base64" - A single ignore pattern.
See "ignorePatterns" property above.
Even though "ignorePatterns" and "base64" are defined as Optional, one
of them is required. If both of them are present eDrive will use the
"ignorePatterns" array and ignore the "base64" property.
O "name" - The name of a specific Synchroniser.
If "name" is not defined, eDrive will add the ignore pattern to ALL
configured Synchronisers.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(i) set (default-type | enable-unfiling | proxy | repository-delete
| sync-direction | sync-path | sync-seconds | toggle) {JSON param}
(i) set default-type {JSON param}
Each Synchroniser has a connection to it's own Repository. When the
Synchroniser creates (not updates) Documents and Folders in the
Repository it needs to know what the type should be. By default the
Synchroniser uses "cmis:document" and "cmis"folder" as the types to
create. However, this is not always what you want to do. For instance
You may have created new base Compay specific types in your
Repository that you want to use as the types when creating new
Folders and Documents.
In the OpenCMIS In-Memory Repository, the "cmis:document" is not
versionable so you may wish to use the "VersionableType" instead as
the default document type.
See the add mime-mapping {JSON param} command for a way to define
the Document type used based on the Documents content MIME type.
M "name" - The name of the Synchroniser this command is targeted at.
O "defaultDocumentType" - The Document type to use when creating new
Documents in the Repository if no alternative mime-mapping exists.
The default is "cmis:document".
O "defaultFolderType" - The Folder type used when creating Folders
in the Repository.
The default is "cmis:folder".
You can set either or both of these at the same time. It will ignore
missing ones.
{
"name":"My eDrive",
"defaultDocumentType":"VersionalType",
"defaultFolderType":"CustomFolderType"
}
NOTE :
eDrive will check that the Types defined actually exists in the
Repository before setting the type. It will also check that the
Type is actually decended from either the "cmis:document" or
"cmis:folder" first. If these conditions are not met you will get
an EXCEPTION response.
Returns configuration for named Synchroniser
(ii) set enable-unfiling {JSON params}
M "name" - The name of the Synchroniser this command is targeted at.
M "unfilingEnabled" - If set to true, eDrive will determine if the
Repository supports unfiling and will enable this for use instead of
deleting Documents from the repository. If set to false, eDrive will
ignore the setting if it's already set to false or disable unfiling
if currently set to true.
Returns configuration for named Synchroniser
(iii) set proxy {JSON param}
M "proxyUserName" - The name required to authenticate via your proxy.
M "proxyPassword" - The password for the proxyUserName
O "name" - The name of a specific Synchroniser.
If "name" is not defined, eDrive will add the proxy settings to ALL
configured Synchronisers.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(iv) set repository-delete {JSON param}
M "name" - The name of the Synchroniser this command is targeted at.
M "repositoryDelete" - If true Edrive will delete Documents from the
Repository. If set false eDrive will either, unfile the Documents if
"ufilingEnabled" is true of delete them if false.
Returns configuration for named Synchroniser
(v) set sync-direction {JSON param}
M "syncDirection" - See the description of the "syncDirection"
property in the add synchroniser command above.
O "name" - The name of the Synchroniser this command is targeted at.
If this is not present eDrive will change the property on ALL
configured Synchronisers.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(vi) set sync-path {JSON param}
M "name" - The name of the Synchroniser this command is targeted at.
M "path" - The relative or absolute path to a Directory on the File
System you want to set synchronisation on or off.
M "syncing" - Set to true or false to enable or diable snchronising of
this path.
Returns configuration for named Synchroniser
(vii) set sync-seconds {JSON param}
O "name" - The name of the Synchroniser this command is targeted at.
If this is not present eDrive will change the property on ALL
configured Synchronisers.
O "inboundSyncSeconds" - The number of seconds you want the minimum
sync time to be for the Inbound Processor.
O "outboundSyncSeconds" - The number of seconds you want the minimum
sync time to be for the Outbound Processor.
Even though both "inboundSyncSeconds" and "outboundSyncSeconds" are
defined as Optional, at least one of them MUST be present. If both are
present then both Inbound and Outbound sync seconds will be set.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(viii) set toggle {JSON param}
M "name" - The name of the Synchroniser this command is targeted at.
M "path" - The path you wish to toggle the current syncing value on.
Toggle will traverse the Directory structure from this point and set
ALL child paths to the value it switched "path" to, ignoring the
current syncing value of the Directory.
Returns configuration for named Synchroniser
(j) remove (mime-mapping | synchroniser | ignore-pattern) {JSON param}
(i) remove mime-mapping {JSON param}
This command will remove one or more mime type mappings from a
Configuration. When a Synchroniser creates a Document in the
Repository it has to define the base type to use for that Document.
The default document type is set to cmis:document and this is the
type that will be used for all Documents no matter what the MIME type
of the content is.
If the documentType is not already mapped then the call is ignored.
If the documentType exists then the mimeTypes will be removed from
this mapping. If there are no more mappings fro this documentType
the the documentType mapping will be removed as well.
See add mime-mapping {JSON param} for details on adding mappings.
This JSON param object can be either an Array of mime mappings or a
single mime mapping.
The following show examples of each type of JSON param :
{
"mimeMappings": [
{"documentType":"customDocument", "mimeTypes":"text/xml,text/html"},
{"documentType":"anotherType", "mimeTypes":"application/x-gzip"}
]
}
{
"name":"My EDrive",
"documentType":"D:cmiscustom:document", "mimeTypes":"video/mpeg"
}
In the first example there are 2 document types being removed and in
the second example there is only 1 document type being removed.
In the first example ALL Synchronisers will have the two mappings
removed and in the second, only the Synchroniser named "My EDrive"
will have the mappings removed.
M "documentType" - The document type to use. Must be in the Repository
M "mimeTypes" - One or more comma separated MIME types.
O "name" - The name of a specific Synchroniser.
If "name" is not defined, eDrive will add the ignore pattern to ALL
configured Synchronisers.
Returns configuration for name Synchroniser
or ALL Synchronisers if no name was provided
(ii) remove synchroniser {JSON param}
This will remove the named Synchroniser entirely from eDrive
M "name" - The name of the Synchroniser this command is targeted at.
Returns configuration for ALL remaining Sychronisers
(iii) remove ignore-pattern {JSON param}
O "name" - The name of the Synchroniser this command is targeted at.
If this is not present eDrive will change.
O "ignorePatterns" - See description of "ignorePatterns" in the add
command above.
O "base64" - See description of "ignorePatterns" in the add command
above.
Even though "ignorePatterns" and "base64" are defined as Optional, at
leaset one of them MUST be present. If both are present, only the
"ignorePatterns" will be used.
Returns configuration for named Synchroniser
or ALL Synchronisers if no name was provided
(k) checkout (JSON param)
M "name" - The name of the Synchroniser this command is targeted at.
M "path" - The path to the Document in the Repository that you want to
checkout. Only the LATEST version is supported. This can be either an
absolute path or a relative path from the "repositoryRoot" property.
NOTE : When checking out a Document, the PWC (Private Working Copy)
version will have a new name such as "file (Working Copy).ext".
You can use this name or the original name for the CheckIn or
Cancel CheckOut.
This will generate an Exception if the Document is already Checked
Out and no EVENT will be generated.
Returns configuration for named Synchroniser
(l) checkin (JSON param}
M "name" - The name of the Synchroniser this command is targeted at.
M "path" - The path to the Document in the Repository that you want to
checkin. This can be either an absolute or relative path from the
"repositoryRoot" or "fileSystemRoot" property.
O "version" - Can be "MAJOR" or "MINOR". Will checkin as a new Major or
Minir version. Will default to "MINOR".
O "comment" - This is the comment to associate with the checkin. If not
set will default to : "Version checked in by [<user>]" Where <user> is
the user connecting to the Repository for this Synchroniser.
NOTE : When checking out a Document, the PWC (Private Working Copy)
version will have a new name such as "file (Working Copy).ext".
You can use this name or the original name for the CheckIn or
Cancel CheckOut.
This will generate an Exception if the Document is already Checked
Out and no EVENT will be generated.
Returns configuration for named Synchroniser
(m) cancel-checkout (JSON param)
M "name" - The name of the Synchroniser this command is targeted at.
M "path" - The path to the Document in the Repository that you want to
checkout. Only the LATEST version is supported. This can be either an
absolute path or a relative path from the "repositoryRoot" property.
NOTE : When checking out a Document, the PWC (Private Working Copy)
version will have a new name such as "file (Working Copy).ext".
You can use this name or the original name for the CheckIn or
Cancel CheckOut.
This will generate an Exception if the Document is already Checked
Out and no EVENT will be generated.
Returns configuration for named Synchroniser
(n) shutdown
Enables a client to shut down all active Synchronisers and then eDrive
itself.
RETURNED RESULTS :
Each eDrive command will return a Result. In the case of the licence
command this will be the text of the licence file. In the case of the help
command it will be the text of this document. In the case of the quit
command it will be the string "Good by..."
ALL other commands return a JSON result containing a result and a status.
{"result":{...},"status":"<STATUS>"}
The "status" property can be one of "OK" "ERROR" or "EXCEPTION"
An "ERROR" status object will be similar to
{
"result":"Unknown method [ggd].",
"status":"ERROR"
}
An "EXCEPTION" ststus object will be similar to
{
"result":"You must specify a property inboundSyncSeconds or outboundSyncSeconds or both",
"status":"EXCEPTION"
}
An "OK" status will contain the configuration for a named Sychroniser
{
"result": {
"enabled": true,
"unfilingSupported": false,
"repositoryRoot": "/User Homes/steve",
"repositoryPassword": "P3xKgaIYr6ABxcNd2UbTWg==",
"repositoryId": "253cc3ea-9b12-492c-b9ad-26a67c2b7f20",
"outboundSyncSeconds": 20,
"syncDirection": "TO_REPOSITORY_DELETE_SOURCE",
"repositoryUserName": "steve",
"paths": [
{
"syncing": true,
"path": ""
}
],
"ignorePatterns": [],
"name": "My first sync",
"unfilingEnabled": false,
"fileSystemRoot": "/tmp/sync",
"repositoryDeleteEnabled": false,
"repositoryUrl": "http://localhost:8080/alfresco/cmisws",
"inboundSyncSeconds": 40
},
"status": "OK"
}
OR the configuration for ALL Synchronisers
{
"result":{
"edrive":[
< Array of configuration objects. See result above >
]
},
"status": "OK"
}
MULTICASER SERVER EVENTS :
The Multicast Server generates and publishes JSONObject events to the
Multicast IP Group and port defined when starting eDrive. These events are
triggered at points of interest durring the syncing process of each
configured Synchroniser and contain the following details :
{
"eventTimeMillis": 1365036717181, // The time this event was generated in milliseconds since the epoch. 1st Jan 1970
"action": "SYNC", // The action being performed. See below.
"location": "/User Homes/steve", // The File, Folder, Directory or Document involved in this event. See below.
"size": 0, // The size of Files and Documents Created or Updated. Only meaningful on "FINISHED" stage events
"direction": "INBOUND", // What direction the event occured in. Either INBOUND or OUTBOUND
"exception": null, // Any excption details if the action resulted in an Exception
"name": "My first sync", // The name of the Synchroniser this event is associated with
"stage": "STARTED" // What stage of the action this event is for. Can be one of "STARTED", "FINISHED", "CANCELLED or NONE"
}
EVENT ACTIONS :
SYNC - This represents a synchronisation event for the Synchroniser.
Synchronisation occurs for both the Inbound and Outbound Processors at
a minimum elapsed time defined by the inboundSyncSeconds and
outboundSyncSeconds configuration values.
DOCUMENT-CHECKOUT - This represents a Document being checked out from
the Repository. The event "direction" property will only ever be set
to "OUTBOUND". The "location" property identifies an absolute
Repository Path to the Document in the Repository or an absolute File
System Path in the File System or a Relaive path from either the
"repositoryRoot" or "fileSystemRoot" proprties.
DOCUMENT-CHECKOUT-CANCEL - This represents a cancellation of a Document
checkout in the Repository. The event "direction" property will only
ever be set to "OUTBOUND". The "location" property identifies an
absolute Repository Path to the Document in the Repository or an
absolute File System Path in the File System or a Relaive path from
either the "repositoryRoot" or "fileSystemRoot" proprties.
DOCUMENT-CHECKIN - This represents a Document being checked in to the
Repository. The event "direction" property will only ever be set to
"OUTBOUND". The "location" property identifies an absolute Repository
Path to the Document in the Repository or an absolute File System Path
in the File System or a Relaive path from either the "repositoryRoot"
or "fileSystemRoot" proprties.
DOCUMENT-CREATE - This represents the creation of a Document or File on
either the Repository or the File System The event "direction"
property identifies if it's INBOUND (from Repository) or
OUTBOUND (to Repository). The "location" property identifies the FULL
path to the Document or File
DOCUMENT-UPDATE - This represents the updating of an existing Document
or File in the Repository or on the File System. The event "direction"
property identifies if it's INBOUND (from Repository) or
OUTBOUND (to Repository). The "location" property identifies the FULL
path to the Document or File
DOCUMENT-DELETE - This represents the deletion of a Document from the
Repository or a File from the File System. The event "direction"
property identifies if it's INBOUND (from Repository) or
OUTBOUND (to Repository). The "location" property identifies the FULL
path to the Document or File
FOLDER-ADDED - This represents a new folder being added to monitored
folder list. If a new folder structure is created in the Repository or
Dragged 'n' Dropped onto the File System, this event fires for each
new Directory detected in the structure. For each FOLDER-ADDED event
there will be a corresponding FOLDER-SYNCING-[TRUE|FALSE] event,
see below.
FOLDER-SYNCING-[TRUE|FALSE] - These two events are fired when the state
of the syncing attribute is changed on a Directory. When a new
Directory is added to the currently monitored list of Directories on
the File System you will first get a FOLDER-ADDED event, generally
followed by a FOLDER-SYNCING-[TRUE|FALSE] event. The TRUE | FALSE is
determined by the syncing state of the Directory this new Directory is
added to. Any of the commands that change the state of the syncing
flag on a Directory, such as the "toggle" command, will generate one
of these events ONLY if the syncing state realy changes from true to
false of vis versa.
FOLDER-REMOVED - This event is fired when eDrive detects that a
Directory has been removed from the File System either as the result
of a Delete in the Repository or any other third party application
removing the Directory from the File System.
NOTE : The FOLDER-[*] events are ALWAYS defined as OUTBOUND as they only
fire on changes to the File System. They are also the ONLY events to
have a "stage" value of "NONE". The "location" property on the event
identifies the path to the Directory the event was fired for.
Copyrighted 2010 - 2013 EOSSOnline Limited (New Zealand)
www.eossonline.com
Download Latest Version
edrive-0.3.0-bin.zip (8.9 MB)
