Copyrighted (c) 2010 - 2013 EOSSOnline Limited (New Zealand)
www.eossonline.com
INTRODUCTION :
See the changes.txt file for details of changes to this releases.
See the roadmap.txt file for details of what we are working on for future 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 1.0 or 1.1 enabled Repositories.
eDrive can manage zero or more Synchronisers, each of which can Synchronise one
directory structure on a File System to one Folder structure in a CMIS Repository.
Each Synchroniser can connect to a different Repository.
eDrive is highly configurable, and should be able to cater for any use case you
have regarding Synchronisation. It is however important to point out that eDrive
is NOT designed as a utility for Bulk Import from File Systems into CMIS enabled
Content Repository.
eDrive has been tested with only a few CMIS Repositories such as 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 compatible 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 at shutdown and restores this state on next startup.
This results in much less load on the machine running eDrive, which
means it's 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 suite your needs. eDrive is not very memory
hungry 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 around 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 uses to load and save configurations. 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 on.
You can use telnet as a client and we generally use telnet with the
rlwrap utility for command history with the 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 the first
available port to listen on which is reported in the log file at log
level INFO. In general, it's best to set this value so that you can
connect to it in the future on a known port with a dedicated client.
If there are any Errors while initialising the Command Server it will NOT
be available. You will see these in the log.
Multiple Clients can connect 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 the eDrive 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 to you, 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 you can run separately
to view and monitor the eDrive generated Events. Run :
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
the classpath instead, the 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 creation will take longer and
require more resources. After this, it should settle down for subsequent
Sync Cycles as the processor will only be interested in the differences
between snapshots taken between Sync Cycles. 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 creation will take longer and
require more resources. After this it should settle down for subsequent
Sync Cycles as the processor will only be interested in the differences
between snapshots taken between Sync Cycles. 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 and proxyUserName properties as
encrypted values.
This property identifies a file on the File System that contains a
Pass Phase used to encode these passwords. 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 characters. eDrive uses the bouncy castle library for encryption.
If either password element is stored in clear text in the JSON file it will
be stored encrypted internally and will be displayed and stored encrypted
when a Synchronisers Configuration is requested or stored to disk.
If this property is not set, eDrive will try to locate a default file at
"user.home"/eDrive.pass
(j) -Dedrive.retry.seconds=<seconds>
If eDrive is unable to start a Synchroniser for any reason i.e. the
Repository is unavailable at startup time, it will determine if this
Synchroniser was previously functional and if it was, it will queue
the Synchroniser to be re-tried in this number of seconds. The
Synchroniser will stay on the Queue until it starts or eDrive is shut
down.
This does not affect Synchronisers that eDrive considers NEW. New
Synchronisers that fail to start are just reported in the log and you
will have to check the connection details by hand, then make sure
eDrive has connected at least once, using these settings, for future
failures to be considered for queueing in the re-try queue.
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 based 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.
For testing, and playing around with the server, we generally use Telnet
with the Linux Read Line wrapper utility rlwrap, which provides command
history through the up and down arrow keys as well as enabling editing of
commands prior to sending the requests to Telnet. Without the use of rlwrap
Telnet would be a difficult utility to use as ALL key strokes are interpreted
as command characters and neither editing not command history would be
possible without implementing this directly in the Command Server.
rlwrap telnet <host | IP> <port>
The eDrive Command Server accepts either 1 or 2 word commands, of which either
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, you 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 of a named Synchroniser, or ALL Synchronisers 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 and other will be ignored if they do not apply.
NOTE : Unless otherwise stated, Commands will return either the JSON
configuration for the named Synchroniser, OR a JSON Array containing
ALL of the Synchroniser configurations managed by eDrive unless
either an ERROR or EXCEPTION is thrown.
EXAMPLE RETURNED RESULTS :
Each eDrive command returns a string. 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" status object will be similar to
{
"result":"You must specify a property inboundSyncSeconds or outboundSyncSeconds or both",
"status":"EXCEPTION"
}
An "OK" status may 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"
}
(a) help
Returns this README document.
(b) licence
returns the Apache 2.0 LICENCE file
(c) quit
Terminate the client connection returning the text "Good by...".
This string can be used by clients to identify a connection closed.
Returns "Good by..."
(d) save
Save's the current internal representation of ALL of the configured
Synchronisers to the file identified by the
-Dedrive.config.file=<file path> 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 explicitly, eDrive will NOT override
the current JSON configuration file if there is one. This also means it
will not store any configuration changes you may have made.
Returns the configuration for ALL Synchronisers
(e) disable [JSON param]
If no JSON parameter is provided this 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"}
Like ALL other commands that take a JSON param object, this Command will
ignore all other non mandatory and optional parameters in the JSON param,
but if it does not contain a name property it will disable ALL currently
enabled Synchronisers.
disable
disable {"name","My Sync"}
Returns the configuration for the named 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 disabled 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 the configuration for the named Synchroniser or
ALL Synchronisers if no name was provided.
(g) test connection {JSON param}
This command can be 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 to make sure you can connect.
The following JSON parameters are acceptable
M "repositoryUrl" - This is the URL to the WEB Services end point.
You do NOT provide the RepositoryService part of the URL i.e.
http://localhost:8080/alfresco/cmisws
http://localhost:9090/chemistry/services
e.g. "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. For instance, the
Chemistry InMemory Repository will not let you checkout Documents
unless you provide a user name and password. Any values are
acceptable to Chemistry.
"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. See above.
"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 each Repository in the CMS or just for the
Repository identified by the "repositoryId" property.
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 or is set to false, eDrive will NOT
navigate the Folder trees of the Repositories.
The returned results can be used by Clients to provide lists of
available Sync Folders to the user for selection.
BEWARE : If your Repository contains a lot of Folders, this call will
take some time.
"getFolders":true
O "startFolder" - Tell eDrive where it 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.
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.
e.g. "startFolder":"\\User Homes"
O "proxyUserName" - If connecting to a Repository through a proxy, you
can provide the name of the proxy user to authenticate as.
O "proxyPassword" - If connecting to a Repository through a proxy, this
is the password of the proxy user used to authenticate.
O "acceptAllCerts" - If connecting via SSL https, you can set this to
true to accept all certificates even if you have not imported them
into your client keystore.
The request below shows this property used with an https connection.
A complete JSON string for this call could be :
{
"acceptAllCerts": true,
"repositoryUrl": "https://localhost:9090/alfresco/cmisws",
"repositoryUserName": "steve",
"repositoryPassword": "steve",
"getFolders": true,
"startFolder": "/User Homes"
}
And a result might 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 adds 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 of the Document to use.
The default document type is set to cmis:document and this is the
type that will be used for all Documents created no matter what the
MIME type of the content is.
Using this command you can override the default type used for content
creation of specific MIME types.
If mappings already exist for a documentType, this will append the
new mimeTypes to the existing mappings. Otherwise, it will create
a new mapping.
This JSON param object can be either an Array of mime mappings or a
single mime mapping.
The following shows examples of each type of JSON param :
{
"mimeMappings": [
{"documentType":"customDocument", "mimeTypes":"text/xml,text/html"},
{"documentType":"anotherType", "mimeTypes":"application/x-gzip"}
]
}
or
{
"name":"My EDrive",
"documentType":"D:cmiscustom:document", "mimeTypes":"video/mpeg"
}
In the first example there are 2 document types being set that will
be applied ay ALL Synchronisers. In the second example there is only
1 document type being set on the Synchroniser identified by "My EDrive"
only.
Once a mapping is set, any content created in the Repository where the
MIME type matches these, the Synchroniser will use the type specified
instead of the default "cmis:document".
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 it. It also checks that the Type is
actually a descendant of the "cmis:document" first.
If these conditions are not met you will get an EXCEPTION response.
eDrive does NOT check that the MIME types are valid.
If they are invalid, they will never match and the documentType
will not be used.
Returns the configuration for the named Synchroniser or
ALL Synchronisers if no name was provided.
(ii) add synchroniser {JSON param}
This adds a new Synchroniser to eDrive.
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 encrypt this internally and only the encrypted
version will be returned when displaying or saving the
configurations.
M "name" - The name of the Synchroniser. This MUST be unique among
Synchronisers for this eDrive instance.
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 a JSON 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 a JSON ERROR
will be returned.
NOTE : To avoid issues with Synchronisation race conditions, 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 when started or if it detects that this Directory has been
deleted while running. If eDrive is unable to create the Directory for
some reason i.e. a regular file with this name exists already, eDrive
will return a JSON EXCEPTION.
O "enabled" - Is Synchroniser enabled or disabled. Defaults to true.
O "outboundSyncSecond" - The minimum time between sync cycles from
the File System to the Repository. Defaults to 20.
O "inboundSyncSeconds" - The minimum time between syncs cycles from
the Repository to the File System. Defaults to 20.
O "acceptAllCerts" - If connecting to your Repository using SSL,
setting this to true will enable you to accept ALL certificates
even if you have not imported your server certificates into your
keystore on the client.
NOTE :
You should use this ONLY for DEVELOPMENT. For production use,
you should export your server certificates and import them
into a keystore on your client and then configure the following
JVM settings accordingly.
-Djavax.net.ssl.keyStore
-Djavax.net.ssl.keyStorePassword
-Djavax.net.ssl.keyStoreType
-Djavax.net.ssl.trustStore
-Djavax.net.ssl.trustStorePassword
-Djavax.net.ssl.trustStoreType
For detailed information on creating and configuring keystores see :
http://goo.gl/Ety2l
The Configuration of key and trust stores are beyond the scope
of this document, so you will need to aquire this information on
your own.
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 set to true and the Repository supports
unfiling of Documents, eDrive will unfile Documents instead of
Deleting them. If unfiling is not supported by the Repository,
eDrive will ignore this value and set it to false anyway.
O "repositoryDeleteEnabled" - If set to false eDrive will not
Delete or Unfile (if supported) any content from the Repository.
The down side of this setting is that any files deleted from the
File System will be recreated if the syncDirection is set to
BI_DIRECTIONAL either at the next Sync Cycle or on restarting
eDrive. Defaults to true.
O "repositoryId" - If 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 want to modify this ignorePattern to include any Folder or
Directory ending with \.svn or /.svn as well.
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 only (not it's sub Directories). An example of a "paths"
property could be :
"paths": [
{
"syncing": true,
"path": ""
},
{
"syncing": true,
"path": "some docs"
},
{
"syncing": true,
"path": "some docs/sso_auth"
},
{
"syncing": false,
"path": "some docs/sso_auth/sso_test"
},
{
"syncing": true,
"path": "some docs/sso_auth/sso_test/Debug"
}
]
In this example we are explicitly telling the OutboundProcessor to
NOT synchronise the path "some docs\\sso_auth\\sso_test"
under the "fileSystemRoot". The other 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"
}
]
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.
O "proxyUserName" - If connecting to a Repository through a proxy, you
can provide the name of the proxy user to authenticate as.
O "proxyPassword" - If connecting to a Repository through a proxy, this
is the password of the proxy user used to authenticate.
Returns the configuration for the named Synchroniser after adding.
(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 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 the configuration for the named 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 the configuration for the 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 the configuration for the named 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 the configuration for the 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 the configuration for the named 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 the configuration for the 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 the configuration for the named 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 the configuration for the 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 the configuration for the named 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 the configuration for the 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 the configuration for the 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 the configuration for the 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 the configuration for the named Synchroniser
(n) shutdown
Enables a client to shut down all active Synchronisers and then eDrive
itself.
Return no response.
(o) get ( configuration | defaults | document | thumb-nails | version-history) {JSON Params}
(i) get configuration {JSON Params}
O "name" - The name of the Synchroniser this command is targeted at.
Returns the configuration for the named Synchroniser or
ALL Synchronisers if no name was provided.
(ii) get defaults
Returns the Defaults used when configuring Synchronisers unless the
values are overriden when adding a new Synchroniser.
(iii) get document [JSON Params]
This returns the actual content of the document and is intended
for retrieving the data for thumb nails. However, it can be used
to get the data of ANY document in the Repository and that can
potentially mean a large amount of data is passed to your client.
See the 'get thumb-nails' command below
M "name" - The name of the Synchroniser managing the Document you
want to get the document from.
M "id" - The id of the Document in the Repository.
Returns the document data. Example below for a thumb nail image, the
data has been truncated here for brevity. The data is a Base64
encode string and after unencoding your data lemgth should match
the "contentLength" property. The "mimeType" property can be used
to create an actual image of that type from the decoded data.
{
"result":{
"id":"workspace:\/\/SpacesStore\/db8de0d2-ff7a-4be4-8c21-28718b1610b3",
"name":"doclib",
"dataBase64":"iVBORw0KGgoAAAANSUhEUgAAAE0AAABkEAYAAACTOmENAAAJ...",
"contentLength":34061,
"mimeType":"image\/png"
},
"status":"OK"
}
Returns an EXCEPTION response if the id is not a document.
(iv) get thumb-nails [JSON Params]
Get an array containing details of all available thumb nails for a
document if any. If there are no thumb nails available you will get
an EXCEPTION Response.
M "name" - The name of the Synchroniser managing the Document you
want to get the list of thum nails for.
M "path" - The absolute or relative path of a File or Directory
on the File System or a Document or Folder in the Repository.
Return an array of one or more thumb nails for the requested path.
The following example returns an array of 1 available thumb nail
for the file Alfresco-3-Web-Services-eBook24022011_1066354.pdf
which is present in the sync root. If more thumb nails were
available they would normally differ in width and height. Your
client can use the "id" property with the 'get document'
command, listed above, to retieve the actual data as a base64
encoded string.
{
"result":{
"thumbNails":[
{
"title":"doclib",
"height":100,
"width":100,
"length":34061,
"id":"workspace:\/\/SpacesStore\/db8de0d2-ff7a-4be4-8c21-28718b1610b3",
"mimeType":"image\/png"
}
],
"fileSystemPath":"\/tmp\/sync\/Alfresco-3-Web-Services-eBook24022011_1066354.pdf",
"repositoryPath":"\/User Homes\/steve\/sync\/Alfresco-3-Web-Services-eBook24022011_1066354.pdf"
},
"status":"OK"
}
(v) get version-history [JSON Params]
M "name" - The name of the Synchroniser managing the Document you
want the version history for.
M "path" - The absolute or relative path of a File or Directory
on the File System or a Document or Folder in the Repository.
Returns the details of the requested object.
In the case of a Directory or Folder, return the following :
{
"result": {
"versions": [
{
"id": "workspace://SpacesStore/6b00f243-d532-497e-b6f0-1833dda2e93e",
"name": "sso_auth",
"lastModifiedBy": "steve",
"type": "cmis:folder",
"lastModificationDate": "2013-04-24 10:02:41 NZST"
}
],
"repositoryPath": "\\User Homes\\steve\\sync\\some docs\\sso_auth"
},
"status": "OK"
}
In the case of a NON Versionable Document or File, return the following :
{
"result":{
"versions":[
{
"id":"111",
"name":"My_Document-2-0",
"lastModifiedBy":"unknown",
"type":"ComplexType",
"lastModificationDate":"2013-04-26 14:31:16 NZST",
"contentLength":34475,
"mimeType":"text\/plain"
}
],
"repositoryPath":"\\My_Folder-0-0\\My_Folder-1-1\\My_Document-2-0"
},
"status":"OK"
}
In the case of a Versionable Document or file, the versions are
returned in order. If there was a PWC version, i.e. the Document
was currently checked out, this would be at the top of the list.
Versionable documents return the following :
{
"result":{
"versions":[
{
"checkedOutId":null,
"latestMajorVersion":true,
"majorVersion":false,
"checkinComment":"hhhhh",
"versionLabel":"1.2",
"checkedOutBy":null,
"versionSeriesId":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac",
"type":"cmis:document",
"id":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac;1.2",
"latestVersion":true,
"name":"activiti.mssql.create.identity.sql",
"lastModifiedBy":"admin",
"contentStreamFileName":"activiti.mssql.create.identity.sql",
"lastModificationDate":"2013-04-24 10:02:40 NZST",
"contentLength":189,
"mimeType":"application\/x-sh"
},
{
"checkedOutId":null,
"latestMajorVersion":false,
"majorVersion":false,
"checkinComment":"",
"versionLabel":"1.1",
"checkedOutBy":null,
"versionSeriesId":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac",
"type":"cmis:document",
"id":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac;1.1",
"latestVersion":false,
"name":"activiti.mssql.create.identity.sql",
"lastModifiedBy":"admin",
"contentStreamFileName":"activiti.mssql.create.identity.sql",
"lastModificationDate":"2013-04-22 23:31:48 NZST",
"contentLength":1454,
"mimeType":"application\/x-sh"
},
{
"checkedOutId":null,
"latestMajorVersion":true,
"majorVersion":true,
"checkinComment":"Initial Version",
"versionLabel":"1.0",
"checkedOutBy":null,
"versionSeriesId":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac",
"type":"cmis:document",
"id":"workspace:\/\/SpacesStore\/7bcb8543-4bd8-49f1-9118-4a2c4f5d5fac;1.0",
"latestVersion":false,
"name":"activiti.mssql.create.identity.sql",
"lastModifiedBy":"steve",
"contentStreamFileName":"activiti.mssql.create.identity.sql",
"lastModificationDate":"2013-04-22 18:05:23 NZST",
"contentLength":1039,
"mimeType":"text\/x-sql"
}
],
"repositoryPath":"\\User Homes\\steve\\sync\\some docs\\sso_auth\\activiti.mssql.create.identity.sql"
},
"status":"OK"
}
NOTE :
Alfresco cmis:document type Documents are considered Versionable
even if the Versionable Aspect has been removed from the Document.
We would consider this a defect in the Alfresco CMIS implementation.
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 (c) 2010 - 2013 EOSSOnline Limited (New Zealand)
www.eossonline.com
Download Latest Version
edrive-0.3.0-bin.zip (8.9 MB)
