# orion.core.file

The `orion.core.file` service is used to provide file system contents for the Orion workspace. For example a plug-in can use this service to include content from one server into a workspace on another server. Each file service is displayed as a root element in the Orion Navigator page.

The code snippet below demonstrates a use of this service:

    provider.registerServiceProvider("orion.core.file", service, {Name: 'Sample File System'});

The above code will contribute a top level node to the Navigator named "Sample File System". The parameter "service" in the API above must provide the functions specified by the Orion file client API. Refer to `orion.fileClient.FileClient` in the client API reference for further details. For more information on client-server interaction, see Orion File Server API. For an complete file system example, see the sample file plugin in the Orion Git repository.

The file client API methods are as follows:

fetchChildren (location) — returns Array of File.
  Obtains the children of a remote resource.
  Among other places, this function is used in the Orion navigator to display the file system contents in a tree view.
createWorkspace (name)
  Creates a new workspace with the given name.
  TODO -- this is never called by the Orion IDE.
loadWorkspaces ( ) — returns an Array of File.
  Loads all the user's workspaces.
  TODO -- this is never called by the Orion IDE.
loadWorkspace (location) — returns a File.
  Loads the workspace with the given id and sets it to be the current workspace for the IDE. The workspace is created if none already exists.
  Called by the Orion navigator when navigating to the root of the file system.
  NOTE: The returned file object should have a zero-length 'Parents' array to designate it as the root of the filesystem (see bug 392374).
createProject (url, projectName, serverPath, create)
  Adds a project to a workspace.
  TODO -- the Orion IDE never calls this function for third-party file systems.
createFolder (parentLocation, folderName)
  Creates a folder.
  Invoked when using the New Folder command in the Orion navigator.
createFile (parentLocation, fileName)
  Create a new file in a specified location.
  Invoked when using the New File command in the Orion navigator.
deleteFile (location)
  Deletes a file, directory, or project.
  Invoked when using the Delete command in the Orion navigator.
moveFile (sourceLocation, targetLocation, name)
  Moves a file or directory.
  Invoked when using the Move and Cut..Paste commands in the Orion navigator.
copyFile (sourceLocation, targetLocation)
  Copies a file or directory.
  Invoked when using the Copy..Paste commands in the Orion navigator.
read (location, isMetadata) — returns String (contents) or File (metadata).
  Returns the contents or metadata of the file at the given location.
  Invoked by the Orion editor to open a file for editing, and to retrieve metadata about the file being edited.
write (location, contents, args)
  Writes the contents or metadata of the file at the given location.
  Invoked by the Orion editor to save a file being edited.
remoteImport (targetLocation, options)
  Imports file and directory contents from another server.
remoteExport (sourceLocation, options)
  Exports file and directory contents to another server.
search (location, query) — returns Array of File.
  Performs a search with the given query.
  Invoked by various search widgets that appear in the Orion UI.

This API is asynchronous: in other words, every API method is expected to return a promise that eventually resolves with the result object, or rejects if an error occurred.