netbeans.apache.org/src/content/wiki/DevFaqDotShadowFiles.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.
//

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

=== What are `*.shadow` files?

`*.shadow` files are mainly used in the link:DevFaqSystemFilesystem.asciidoc[system filesystem]
for configuration data.
They are the functional equivalent of Unix symbolic links -
a `*.shadow` file is a pointer to another file whose
behavior in every respect except its path and file name is the same as the original.

`*.shadow` files are commonly used where only a single instance of an object is needed,
but it must be registered in multiple folders.
For example, a general `Action` is declared in the `Actions/` folder of the
system filesystem.
But the action also needs to appear in menus and toolbars, possibly other places.
So, rather than create multiple instances of an action, one [[DevFaqInstanceDataObject|`*.instance` file]]
is created in the link:DevFaqModulesLayerFile.asciidoc[module's layer file], in the `Actions/` folder.
Then `*.shadow` files are created in all of the other places the `*.instance` file would be needed,
pointing to the original file.

Declaring a .shadow file in the system filesystem looks like this:

[source,xml]
----

<folder name="A">
  <file name="com-foo-mymodule-MyClass.instance"/>
</folder>
<folder name="B">
  <file name="Shadow1.shadow">
    <attr name="originalFile" stringvalue="A/com-foo-mymodule- MyClass.instance"/>
  </file>
</folder>
<folder name="C">
  <file name="anotherShadow.shadow">
    <attr name="originalFile" stringvalue="A/com-foo-mymodule-MyClass.instance"/>
  </file>
</folder>
----

Shadow files can also point to real files on disk.
For example, the Favorites tab in the NetBeans IDE
uses shadow files to link to real directories on disk.

===== Creating Shadow Files Programmatically

If you need to create `.shadow` files programmatically, use [link:http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataShadow.html#create(org.openide.loaders.DataFolder,%20java.lang.String,%20org.openide.loaders.DataObject[http://bits.netbeans.org/dev/javadoc/org-openide-loaders/org/openide/loaders/DataShadow.html#create(org.openide.loaders.DataFolder,%20java.lang.String,%20org.openide.loaders.DataObject]) `DataShadow.create()`] &mdash; do not write `FileObject`s and try to set attributes on them.  In an XML layer, a `DataShadow`'s original file is pointed to by a file attribute.  On disk, that is accomplished via the _file's content_ instead.  To reliably create `DataShadow`s, let the infrastructure do it for you - do not make assumptions about how the original file is pointed to.

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


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