// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you under the Apache License, Version 2.0 (the
//     "License"); you may not use this file except in compliance
//     with the License.  You may obtain a copy of the License at
// 
//       http://www.apache.org/licenses/LICENSE-2.0
// 
//     Unless required by applicable law or agreed to in writing,
//     software distributed under the License is distributed on an
//     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
//     KIND, either express or implied.  See the License for the
//     specific language governing permissions and limitations
//     under the License.
//

= DevFaqSystemFilesystem
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:jbake-status: published
:keywords: Apache NetBeans wiki DevFaqSystemFilesystem
:description: Apache NetBeans wiki DevFaqSystemFilesystem
:toc: left
:toc-title:
:syntax: true

== What is the System Filesystem?

The system filesystem is the central repository for configuration data in NetBeans.
It is composed at runtime of a stack of XML layers (link:DevFaqModulesLayerFile.asciidoc[DevFaqModulesLayerFile])
supplied by modules in the system.
Modules use folders in the system filesystem to define _extension points_ -
a module can define a folder and document what files or objects
(typically instance files: link:DevFaqInstanceDataObject.asciidoc[DevFaqInstanceDataObject])
other modules can put there, and then, at runtime, scan the
contents and do something with the result.

The top layer of the System Filesystem is the `config/` subfolder of the user directory.
(link:DevFaqUserDir.asciidoc[DevFaqUserDir])
That is what makes the System Filesystem read-write -
diffs are written there,
and there are semantics for programmatically deleting files
by creating an empty file called, e.g., `TheFile.instance_hidden`.

Any type of file can be put into the System Filesystem;
what is done with those files is a contract between the module that defines a folder
and documents what can be put there, and the modules that put things there.
You can use `FileUtil.getConfigFile` to access entries at runtime.

The same mechanism for file recognition that recognizes user files on disk
recognizes files in the system filesystem -
so you can put a `.java` file in the system filesystem,
and it can be opened in the editor and edited just as a file on disk can
(if saved, it will be written to the user dir on disk,
and the newly written file will then be the actual content.
In fact, this is why file templates in the IDE can be edited.

Some folders have special meaning to the system,
because they are defined by modules that are part of the NetBeans Platform.
Some of them are:

* `Actions/` - A global repository for actions in the system, it contains subfolders which categorize actions into ad-hoc categories.  This folder supplies raw actions for the Key Bindings part of the Options dialog. If you install actions, the typical pattern is to put an `*.instance` files here.
* `Menu` - The contents of the menu bar in the main window - it has a folder for each menu;  subfolders of these represent submenus, and `*.instance` files represent `Action`s to be shown on the menus.
* `Loaders` - Contains subfolders that define mime types (e.g. `Loaders/text/x-java`) which are used to define various attributes such as popup menu items that should appear when the user right clicks on a file of a given MIME type.

There are several things which affect how objects are used, all or some of which may be specified by a module's API:

* The location of a file - a module may define a folder that modules put objects directly into, or request that client modules create subfolders in that folder in cases where the entire path to the file has semantic meaning (see below).
* The type of the file - very often you will install `*.instance` files that represent Java objects; typically the module will specify what classes or interfaces objects in a folder should be assignable from.
* File attributes (link:DevFaqFileAttributes.asciidoc[DevFaqFileAttributes]) - for cases where additional information is required to describe what to do with the files that client modules add to the folder, some optional or mandatory key/value attributes may be specified.

=== Available documentation on System Filesystem contents

link:http://bits.netbeans.org/dev/javadoc/layers.html[List of files and folders in the system filesystem]
in NetBeans API Javadoc lists some locations.
Feel free to file documentation bugs for modules you know read other locations
but which fail to list them in their `arch.xml` file.


Applies to: NetBeans 6.5 and newer

== Apache Migration Information

The content in this page was kindly donated by Oracle Corp. to the
Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/DevFaqSystemFilesystem[http://wiki.netbeans.org/DevFaqSystemFilesystem] , 
that was last modified by NetBeans user Jglick 
on 2009-12-03T13:51:54Z.


*NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed.