The 10Duke File+ Developer Guide filePlus_developer-guide.pdf

Table of Contents

Introduction

What is File+

File+ is a web application that provides file storage and conversion between different file formats. Because File+ stores files persistently it can be used as an origin service when using Content Delivery Networks (CDN). These features are provided by the File+ web based API. The File+ API can be used in many kinds of applications including server side applications, desktop applications and mobile applications.

The main source of inspiration for File+'s API are the basic command line tools for managing files in Linux / Unix type systems. These include cp, mv, ls, mkdir, rm.

Features

Creating directories Creating directories in arbitrary hierarchies is supported. Each directory can be freely named by the rules and conventions defined by File+.
Listing contents of directories List contents of a directory outputs results in similar format used by the ls command using specifier -al or -ll.
Uploading and downloading files Files can be uploaded into a directory you have created. Scenarios for file download includes:
  • downloading the file to local disk
  • displaying the file, such as an image or video, in a web page
  • serve files to a CDN application, which will further deliver files to end users
Copying files and directories You can make copies of files and directories efficiently within File+.
Renaming and moving files and directories You can rename and move files and directories from one path to another.
Deleting files and directories Files and directories can be deleted once they are not needed any longer.
Converting files from one format to other formats Files can be converted from one format to another. Such an operation uses one file as source and will produce another file as the result. Example conversions are:
  • convert a jpg image to png format
  • convert a wmv video file to a mp4 video file that is compatible with html5 video players
  • convert a Revit 3D model file to an IFC file

Who is File+ intended for

File+ provides technical services to other applications. The target audience is primarily software developers, engineers and people with roles in system design and development. Here are a couple use cases to help explain who File+ is for:

Software developers Implementing application features that deal with files, content delivery and file conversion. Ability to access files from anywhere and always delivering files in correct format for each consuming client.
System architects Integrating different storage systems and providing a unified single point of API based access to a heterogeneous storage backend.
System administrators Moving, securing (backup), migrating and managing files.

File+ Logics

The main functionality of File+ can be summarized as Input and Output (IO) as applied to data in files. The File+ IO operations can be applied in various combinations producing storage and conversion features in applications.

The operational logic of File+ is on two distinct levels:

  1. managing IO operation authorization
  2. performing requested IO operations

Security

File+ uses a hybrid authorization model, which is a combination of role based authorization and token based authorization. File+'s token-based authorization model encapsulates tokens in an object called a Ticket (think of the ticket being the vessel that carries the token).

The role based authorization is used to control the process of granting and revoking tickets. The tickets in turn are needed when requesting IO operations. Tickets allow controlling quantities, path scopes, operation scopes, etc. They are digitally signed and validated by File+.

All file IO and conversion operations are authorized using tickets. The tickets identify a file or conversion operation and the granted permissions. Tickets always apply in the context of a customer account.

For example, to rename a directory, the client needs to request a rename ticket and then request the rename operation. Authorized users may create tickets for File+ operations. One could generalize the use of the File+ API to the following programming model:

  • generating required tickets: you may generate tickets in advance and in quantities appropriate to your business logic
  • handing over tickets to actors who then call file and conversion operations (actors may be people and software components)
  • executing the file and conversion operations

File+ can be deployed to audit all operations, which allows detailed inspection of what happens and who authorized operations to execute.

Connections to File+ are secured. File+ provides by default a secure HTTPS connection as the primary choice.

REST API

The primary API that File+ provides is web-based and calls to it are done using HTTP(S).

Authentication

User name and password authentication is used as the default File+ authentication model. Establishing an authenticated session is required before performing ticket management calls to the REST API.

See also documentation about customizing File+ and how to implement alternative authentication and authorization.

Login and logout are both requested by calling an endpoint called /graph.

Login

Authentication works using a user name and password. Successful authentication responds with Set-Cookie headers back to the client. Clients should in general support using cookies in order to use File+. The cookies should be stored by the client and used in calls to the service that apply for the same user that logged in.

Request
Method POST
URL https://file.10duke.com/graph/
Login request parameters
operation Login
userName value of user name
password value of password
Request example
POST
http://de26.10duke.com/graph/

Request parameters:
operation=Login&userName=test@10duke.com&password=secret
Response example
Headers:
Content-Type:application/json; charset=utf-8
Set-Cookie:djsuid=06bdb143-3add-4fb7-8d18-0c52737c9364;Path=/
Set-Cookie:djvu=1431170479332;Path=/
Set-Cookie:djsv=WdtfJaUixOweoRsml3W5xLgGKa4;Path=/

Response body:
{
  "__objType": "LoginResult",
  "resultCode": "Success",
  "_loginName": "test@10duke.com"
}

Logout

Ends the session for the logged in user.

Request
Method GET or POST
URL https://file.10duke.com/graph/
Logout request parameters
operation Logout
Request example
POST
http://de26.10duke.com/graph/

Request parameters:
operation=Logout
Response example
Headers:
Content-Type:application/json; charset=utf-8
Set-Cookie:djsuid=;Path=/;Expires=Thu, 01-Jan-1970 00:00:00 GMT
Set-Cookie:djsv=;Path=/;Expires=Thu, 01-Jan-1970 00:00:00 GMT
Set-Cookie:djvu=;Path=/;Expires=Thu, 01-Jan-1970 00:00:00 GMT

Response body:
{
  "__objType": "LogoutResult",
  "resultCode": "Success"
}

IO requests

Introduction

IO requests represent the main features and functions that File+ provides. IO is a common acronym in computer science and refers to Input and Output of information in various ways. IO in File+ means data input and output that is related to handling files and conversions of files.

The process of making IO requests to the service involves 3 technical steps, which are depicted in diagram 1. The generic sequence is:

  1. ensure you have a valid ticket related to your IO request
  2. make the IO request using the appropriate ticket
  3. process response

Diagram 1 Diagram 1: Making IO requests

A simple example flow as HTTP calls look like this:

POST: https://file.10duke.com/ticket/mkdir?path=/videos
--> responds ticket as a JSON object
POST: https://file.10duke.com/mkdir/?ticket=myTicket&path=/videos
--> responds result for creating directory /videos

IO response format

The service responds with JSON as content type. Exceptions to the rule, for obvious reasons, are file downloads.

Response object structure

Ticket and IO operation responses have a two level JSON object structure. The first level maps to the request and the second level maps to the requested operation's result.

The first level provides information if the service understood the request and was able to call the requested operation.

The second level in the response object provides information about the operation result.

The following pseudo response object sample shows and explains the high level response structure:

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "Name of operation class",
        "resultCode": "Operation result code"
    },
    "resultCode": "Service request result code"
}

Note how the root level JSON object has a field called "resultCode". Values in this field indicate success or failure on request level.

The "processingResult" field is a complex object and it's contents depend on what operation was requested. It will always have the fields: "resultCode" and "__objType". The "resultCode" field will provide the information if the operation was successful or failed.

Result codes
Request level ("resultCode": "request result code value")
"Success" Service understood the request and executed an operation.
"NotSupported" Unsupported operation (Service did not understood what the caller requested)
"Failed" Failed IO operations will induce this result code on request level.
HTTP 500: server error This HTTP response code indicates that the service threw an exception. This will happen e.g. for unauthenticated Ticket requests.
Operation level ("resultCode": "operation result code value")
"Success" The requested operation was successful
"ticketConsumptionFailed" Result code for communicating an error in consuming the ticket that would authorize the requested IO operation.
"fileAlreadyExists" Result code to indicate operation error for trying to produce a file where it already exists. Applies to e.g. create (upload), convert, move, and copy operations.
"noSuchFileOrDirectory" Result code to indicate operation error for trying to access a file that does not exist. Applies to e.g. download, list, move, and copy operations.
"receivingFileFailed" Indicates error in receiving file. Applies to upload operation.
"BadOrMissingArguments" Indicates operation call with incorrect arguments.
"InternalOperationError" Result code for an internal error in the requested operation. This is a code for an error that the caller can not fix.
"ticketNotFound" This error is produced when the caller refers to a ticket that does not exist.
"unknownTicketType" This error is produced when the caller requests an unknown ticket type.
"licenseQuotaExceeded" Error code reserved for situation where an IO request tries to consume a ticket that has been fully consumed previously.
"PartiallyFailed" Result code that indicates partial failure of an operation.

Ticket requests

The client must possess a ticket for token based authorization before making actual IO requests. Ticket requests are:

Get Copy Ticket (cp)

Gets a new ticket to authorize copying a file.

Request
METHOD POST
URL https://file.10duke.com/ticket/cp
Parameters
path1 source path to copy from
path2 target path to copy to
Request example
POST
http://de26.10duke.com/ticket/cp

Request parameters:
path1=/test-1&path2=/test-2
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetCpTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get List Ticket (ls)

Gets a new ticket to authorize listing content from a directory.

Request
METHOD POST
URL https://file.10duke.com/ticket/ls
Parameters
path source path to list content from
Request example
POST
http://de26.10duke.com/ticket/ls

Request parameters:
path=/test
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetLsTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get Make Directory Ticket (mkdir)

Gets a new ticket to authorize creating a new directory.

Request
METHOD POST
URL https://file.10duke.com/ticket/mkdir
Parameters
path path for new directory
Request example
POST
http://de26.10duke.com/ticket/mkdir

Request parameters:
path=/test
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetMkdirTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get Move Ticket (mv)

Gets a new ticket to authorize moving a file or directory.

Request
METHOD POST
URL https://file.10duke.com/ticket/mv
Parameters
path1 source path to move
path2 target path to move to
Request example
POST
http://de26.10duke.com/ticket/mv

Request parameters:
path1=/test-1&path2=/test-2
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetMvTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get Remove Ticket (rm)

Gets a new ticket to authorize removing a file or directory.

Request
METHOD POST
URL https://file.10duke.com/ticket/rm
Parameters
path path to remove
Request example
POST
http://de26.10duke.com/ticket/rm

Request parameters:
path=/test/video.mp4
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetRmTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get Download Ticket (download)

Gets a new ticket to authorize downloading a file.

Request
METHOD POST
URL https://file.10duke.com/ticket/download
Parameters
path path to file that download is authorized for
Request example
POST
http://de26.10duke.com/ticket/download

Request parameters:
path=/test/video.mp4
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetDownloadTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Get Upload Ticket (upload)

Gets a new ticket to authorize uploading a file.

Request
METHOD POST
URL https://file.10duke.com/ticket/upload
Parameters
path path to create for uploaded file
Request example
POST
http://de26.10duke.com/ticket/upload

Request parameters:
path=/test/video.mp4
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "GetUploadTicketResult",
        "ticketKey": "ticket data...",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
Revoke Ticket (revoke)

Revokes a ticket.

Request
METHOD POST
URL https://file.10duke.com/ticket/revoke/ticket_key_here
Request example
POST
http://de26.10duke.com/ticket/revoke/WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "RevokeTicketResult",
        "resultCode": "Success"
    },
    "resultCode": "Success"
}

IO requests

ls

Lists contents of a directory.

Request
METHOD GET
URL (example) https://file.10duke.com/ls/?ticket=key&path1=/videos/new/
Parameters
ticket takes the value of a ls ticket key granted previously by the service
path1 denotes the path to list content from
Request example
POST
http://de26.10duke.com/ls/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path=/
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "LsResult",
        "contents": {
            "__objType": "ArrayList",
            "elementData": {
                "__objType": "Object[]",
                "elementType": "jl:Object",
                "size": 3,
                "Items": [
                    {
                        "__objType": "String",
                        "value": "d 2014-03-01T14:05:00.000Z ."
                    },
                    {
                        "__objType": "String",
                        "value": "d 2014-03-01T14:05:00.000Z test-1"
                    },
                    {
                        "__objType": "String",
                        "value": "d 2014-03-01T14:05:10.000Z test-2"
                    },
                    {
                        "__objType": "String",
                        "value": "d 2014-03-01T14:05:11.000Z test-3"
                    }
                ]
            },
            "size": 3,
            "modCount": 3
        },
        "path": "/"
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
mkdir

Creates a new directory

Request
METHOD POST
URL (example) https://file.10duke.com/mkdir/?ticket=key&path1=/videos/new/
Parameters
ticket takes the value of a mkdir ticket key granted previously by the service
path1 denotes the directory path to create
Request example
POST
http://de26.10duke.com/mkdir/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path=/test
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "MkdirResult",
        "path": "/test"
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
cp

Copies a file or a directory and it's content recursive

Request
METHOD POST
URL https://file.10duke.com/cp/
Parameters
ticket takes the value of a cp ticket key granted previously by the service
path1 denotes the source path to copy from
path2 denotes the target path to copy to
Request example
POST
http://de26.10duke.com/cp/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path1=/test-1&path2=/test-2
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "CpResult",
        "sourcePath": "/test-1"
        "targetPath": "/test-2"
        "resultCode": "Success"
    },
    "resultCode": "Success"
}
mv

Moves / renames a file or a directory and it's content recursive

Request
METHOD POST
URL https://file.10duke.com/mv/
Parameters
ticket takes the value of a mv ticket key granted previously by the service
path1 denotes the source path to move from
path2 denotes the target path to move to
Request example
POST
http://de26.10duke.com/mv/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path1=/test-1&path2=/test-2
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "MvResult",
        "sourcePath": "/test-1",
        "targetPath": "/test-2",
        "resultCode": "Success"
    }
}
rm

Removes a file or directory (recursively)

Request
METHOD POST or DELETE
URL (example) https://file.10duke.com/rm/?ticket=key&path1=/videos/new/
Parameters
ticket takes the value of a rm ticket key granted previously by the service
path1 denotes the source path to remove
Request example
POST
http://de26.10duke.com/rm/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path=/test-3
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult":
    {
        "__objType": "RmResult",
        "resultCode": "Success",
        "path": "/test-3"
    },
    "resultCode": "Success"
}
download

Downloads a file to the client

Request
METHOD GET
URL https://file.10duke.com/download/
Parameters
ticket takes the value of a download ticket key granted previously by the service
path1 denotes the file to download
Request example
POST
http://de26.10duke.com/download/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path=/test/video.mp4
Response example
Headers:
Content-Type: THIS HEADER IS SET ACCORDING TO FILE's MIME TYPE, e.g. image/jpg

Response body:
- in success case raw file content will be the response body as such
Response example (failure)
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
  "__objType": "FilePlusResult",
  "resultCode": "Failed",
  "errorTechnical": "Path: /test did not pass validation"
}
upload

Uploads a file to the service

Request
METHOD POST or PUT
URL https://file.10duke.com/upload/
Parameters
ticket takes the value of a upload ticket key granted previously by the service
path1 denotes the path to create for the uploaded file
md5sum (Optional) MD-5 checksum computed from file's content. If this parameter is provided by the caller it will be used to verify the integrity of the file.
sha1sum (Optional) SHA-1 checksum computed from file's content. If this parameter is provided by the caller it will be used to verify the integrity of the file.
Request example
POST
http://de26.10duke.com/upload/

Request headers:
Content-Type: multipart/form-data; boundary=----------------------------b3973b4ec42d
FilePlus-sha1sum: ... SHA-1 sum of file content... (optional)
FilePlus-md5sum: ... MD5 sum of file content... (optional)

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
file=CONTENT OF FILE THAT IS UPLOADED
sha1sum=... SHA-1 sum of file content... (optional)
md5sum=... MD5 sum of file content... (optional)
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "UploadResult",
        "path": "/test/img2.jpg",
        "resultCode": "Success",
        "createdEntry": {
            "__objType": "RegularFile",
            "edited": "2015-01-01T15:43:10.503Z",
            "regularFile": true,
            "status": "success",
            "authorId": "b2a0c2c5-081a-4aba-a5e4-815b6368dcb6",
            "size": 189739,
            "id": "81db2e51-01de-4e9b-8156-b74db063ef07",
            "authored": "2015-01-01T15:43:10.471Z",
            "editorId": "b2a0c2c5-081a-4aba-a5e4-815b6368dcb6",
            "name": "img2.jpg",
            "path": "/test/img2.jpg",
            "referenceFields": {
                "__objType": "HashMap",
                "Entries": [
                    {
                        "__objType": "KeyValue",
                        "key": {
                            "__objType": "String",
                            "value": "ref_Directory_id"
                        }
                    }
                ]
            },
            "lastAccessed": "2015-01-01T15:43:10.471Z",
            "rel_Relations": []
        }
    },
    "resultCode": "Success"
}
Response example (failure)
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
  "__objType": "FilePlusResult",
  "processingResult":
    {
      "__objType": "UploadResult",
      "resultCode": "BadOrMissingArguments",
      "errorTechnical": "File exists"
    },
  "resultCode": "Failed",
  "errorTechnical": "Path: /test/img.jpg did not pass validation"
}

Convert requests

Introduction

Convert requests are used to transcode (convert) a file from one format to another. Conversion will keep the source file in its original state and always output the result in a new file.

The process of making Convert requests to the service involves 4 technical steps, which are depicted in diagram "Making Convert requests". The generic sequence is:

  • ensure you have a valid ticket related to your Convert request
  • make the Convert request using the appropriate ticket
  • process the immediate response, storing reference to the issued conversion task identifier
  • check conversion progress using the reference that File+ provided to the issued task

Diagram 2 Diagram 2: Making Convert requests

A simple example flow as HTTP calls look like this:

POST: https://file.10duke.com/ticket/convert/?path1=/inbox/*&path2=/gallery/*
  * responds ticket as a JSON object allowing convert operations beneath inbox and gallery
POST: https://file.10duke.com/convert/?ticket=myTicket&path1=/inbox/test.mp4&path2=/gallery/html5.mp4
  * responds result for issuing the convert task

Convert requests

convert

Produces a conversion of a file.

Request
METHOD POST
URL (example) https://file.10duke.com/convert/?ticket=key&path1=/new/pic.png&path2=/gallery/pic.jpg
or similarly for a webm video:
https://file.10duke.com/convert/?ticket=key&path1=/new/test.mp4&path2=/gallery/html5.webm
Parameters
ticket takes the value of a convert ticket key granted previously by the service
path1 denotes the path to use as input data
path2 denotes the path to use for storing the conversion result
Optional parameters

Optional parameters depend on what conversion is requested. E.g. converting images allows the caller to specify the width and height of the output image. Each File+ deployment may have its unique conversion capability and for that reason also its unique list of optional parameters. The next listing provides defaults, which apply for converting images using an out-of-the-box File+ deployment.

w Required width of output image (in pixels). Specifying only width and omitting the height parameter will preserve image aspect ratio while respecting the required width value. Omitting both width and height will preserve original dimensions.
h Required height of output image (in pixels). Specifying only height and omitting the width parameter will preserve image aspect ratio while respecting the required width value. Omitting both width and height will preserve original dimensions.
Request example
POST
http://de26.10duke.com/convert/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
path1=/test/img.png
path2=/test/img.jpg
w=240
h=120
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "ConvertResult",
        "resultCode": "Success",
        "sourcePath": "/test/img.png",
        "targetPath": "/test/img.jpg",
        "convertStatus": {
            "__objType": "ConvertStatus",
            "targetFilePath": "/test/img.jpg",
            "submitted": "2015-10-23T09:11:25.608Z",
            "id": "c87bbce8-0ffb-43e5-b64d-d7e591eb3be6",
            "statusCode": "pending"
        }
    },
    "resultCode": "Success"
}
convertstatus

Checks the status of a conversion task

Request
METHOD POST
URL (example) https://file.10duke.com/convertstatus/?ticket=key&id=the_job_uuid&path1=/new/test.mp4&path2=/gallery/html5.webm
Parameters
ticket takes the value of a convertstatus ticket key granted previously by the service
taskId Task reference identifier
path1 Path of the input file
path2 Path of the output file
Request example
POST
http://de26.10duke.com/convertstatus/

Request parameters:
ticket=WVJjSmhzN2tUYnVDVHV2b2lBckNzZy5M...
id=c87bbce8-0ffb-43e5-b64d-d7e591eb3be6
path1=/test/img.png
path2=/test/img.jpg
Response example
Headers:
Content-Type:application/json; charset=utf-8

Response body:
{
    "__objType": "FilePlusResult",
    "processingResult": {
        "__objType": "ConvertStatusResult",
        "resultCode": "Success",
        "convertStatus": {
            "__objType": "ConvertStatus",
            "started": "2015-10-23T09:25:50.125Z",
            "completed": "2015-10-23T09:25:50.239Z",
            "targetFilePath": "/test/img12.jpg",
            "submitted": "2015-10-23T09:25:50.095Z",
            "id": "c87bbce8-0ffb-43e5-b64d-d7e591eb3be6",
            "statusCode": "allReady"
        },
        "statusCode": "allReady"
    },
    "resultCode": "Success"
}

Customizing File+

This chapter explains the internals of File+ with the aspect of extending or changing the web application for custom requirements. Such needs may include:

  • integration to proprietary storage systems
  • special customer account logic
  • integration with billing and other enterprise IT systems
  • custom authorization and entitlement management
  • auditing and logging extensions

Technical Concept of Customization

File+ is built using the 10Duke SDK. The main concept of customizing File+ is based on providing an alternative implementation for one or more internal File+ services and replacing the default implementation of the service(s). Replacing File+ internal services is done by using the Service Locator mechanism defined by the 10Duke SDK. Service locator is a pattern in category Inversion of Control (IoC). The internal services which may be replaced by custom implementation are:

AccountStorageConfiguration resolves a customer account's storage configuration.
ConvertEngine defines how files are converted from one format to another.
FileEngine defines how files and directories are accessed.
PermissionGrantResolver defines how permission grants are resolved for the calling actor.
TicketEngine defines how operation tickets (authorization tokens) are managed and accessed.

Java API

Customizing File+ is done using the File+ Java API. Some parts of the File+ API consists of the 10Duke SDK API. JDK7 or a newer version of Java is required to implement extensions and customizations to File+.

File+ Internal Architecture

Component Architecture

Diagram 3 Diagram 3: Component Architecture

Services and Service Locator

FileEngine, TicketEngine and ConvertEngine instances are always request specific and have state. They are created using the corresponding factories, which are accessed using ServiceLocator.

File+ implements its own servlet context lifecycle manager, in which it registers services with ServiceLocator. Customizations of File+ must to extend File+'s default servlet context lifecycle manager in order to change the factories and other internal application services with custom ones. To activate the custom lifecycle manager it must be set in the standard deployment description web.xml like this:

<listener>
    <description>
        A ServletContextListener that listens to servlet context initialization
        and destruction, and notifies observers of lifecycle phase changes.
        ServletContextLifecycleManager should only be configured on one context.
    </description>
    <listener-class>com.tenduke.fileplus.servlet.WebappLifecycleManager</listener-class>
</listener>

Note that the example uses the default lifecycle manager that comes with File+.

File+'s lifecycle manager uses DefaultServices class as the utility to register its default internal services.

Diagram 4 Diagram 4: Services registered with ServiceLocator

AccountStorageConfiguration

AccountStorageConfiguration resolves a customer account's storage configuration. The responsibility includes the ability to answer questions about quota, what the root path in storage is for the customer account, etc.

The default implementation in File+ is: DefaultAccountStorageInformation

ConvertEngine

ConvertEngine is the interface that File+ uses to process file conversion requests internally. A dedicated instance of convert engine is reserved for each request. Convert engine instances are provided by ConvertEngineFactory, which is accessed using ServiceLocator.

The default implementation in File+ is: DefaultConvertEngine

FileEngine

FileEngine is the interface that File+ uses to process IO (storage) requests internally. A dedicated instance of file engine is reserved for each request. File engine instances are provided by FileEngineFactory, which is accessed using ServiceLocator.

Convert engine requires file engine to store conversion results in File+.

The default implementation in File+ is: DefaultFileEngine

PermissionGrantResolver

PermissionGrantResolver is the standard application service for resolving permission grants for an actor.

File+ implements its own permission grant resolver, which is capable of producing permission grants from tickets at runtime. Tickets are authorization tokens, which are passed in as arguments in IO and convert requests.

TicketEngine

TicketEngine is the interface that File+ uses to manage tickets. The default implementation in File+ is: DefaultTicketEngine

Servlet endpoints

Ticket requests are served by TicketServlet.

Diagram 5 Diagram 5: Ticket Servlet

File IO requests are served by classes that extend IOServlet.

Diagram 6 Diagram 6: IO Servlets

File conversion requests are served by ConvertServlet.

Diagram 7 Diagram 7: Convert Servlet

API and examples

Navigate to File+ API reference here.

You can also download our Curl examples implemented in shell script. Please choose the appropriate file format: