netbeans.apache.org/src/content/wiki/DevFaqDotSettingsFiles.asciidoc

// 
//     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.
//

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

=== What are .settings files?

`.settings` files are similar to [[DevFaqInstanceDataObject| `.instance` files]],
with the difference that they are XML format, and can contain serialized data rather than just default instances.

Since the introduction of [link:http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/NbPreferences.html[http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/NbPreferences.html] `NbPreferences`] to replace [link:http://bits.netbeans.org/dev/javadoc/org-openide-options/org/openide/options/SystemOption.html[http://bits.netbeans.org/dev/javadoc/org-openide-options/org/openide/options/SystemOption.html] `SystemOption`],
very little new code uses these files, and they should be considered semi-deprecated.  They are difficult and error-prone to use, and have a fair amount of overhead.  The Window System still requires them to be used to persist the state of opened windows/tabs (caret position, what file is opened, or other state that should be restored when reopening a [link:http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html[http://bits.netbeans.org/dev/javadoc/org-openide-windows/org/openide/windows/TopComponent.html] `TopComponent`] after a restart) across application runs.

A `.settings` file can encode the entire parent class and interface hierarchy of the object it represents, so that a query about _whether an object of a given type is present_ (such as using `link:http://bits.netbeans.org/dev/javadoc/org-openide-util-lookup/org/openide/util/lookup/Lookups.html#forPath(java.lang.String)[Lookups.forPath]("path/to/folder").allItems()`) can be answered without actually creating an instance of the object.  

Settings files are also useful if you are declaring some objects in a layer file (see link:DevFaqModulesLayerFile.asciidoc[DevFaqModulesLayerFile]) _and intend to write them back out to disk after they have been modified in-memory_ (note this involves writing ugly and inefficient hexadecimal-encoded serialized data into XML files - if the object is a singleton, using `link:http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/NbPreferences.html[NbPreferences]` will be both more efficient and more readable).

==== Example

[source,xml]
----

<?xml version="1.0"?>
<!DOCTYPE settings PUBLIC "-//NetBeans//DTD Session settings 1.0//EN"
                          "link:http://www.netbeans.org/dtds/sessionsettings-1_0.dtd[http://www.netbeans.org/dtds/sessionsettings-1_0.dtd]">
<settings version="1.0">
    <module name="org.netbeans.core.io.ui/1" spec="1.6"/>
    <instanceof class="org.openide.windows.TopComponent"/>
    <instanceof class="org.netbeans.core.io.ui.IOWindow$IOWindowImpl"/>
    <serialdata class="org.netbeans.core.io.ui.IOWindow$IOWindowImpl">
        ACED0005737200296F72672E6F70656E6964652E7...
    </serialdata>
</settings>
----

=== 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/DevFaqDotSettingsFiles[http://wiki.netbeans.org/DevFaqDotSettingsFiles] , 
that was last modified by NetBeans user Jglick 
on 2010-06-14T21:40:32Z.


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