| // |
| // 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. |
| // |
| |
| = DevFaqRegisterObjectsViaInstanceOrSettingsFiles |
| :jbake-type: wiki |
| :jbake-tags: wiki, devfaq, needsreview |
| :jbake-status: published |
| :keywords: Apache NetBeans wiki DevFaqRegisterObjectsViaInstanceOrSettingsFiles |
| :description: Apache NetBeans wiki DevFaqRegisterObjectsViaInstanceOrSettingsFiles |
| :toc: left |
| :toc-title: |
| :syntax: true |
| |
| == Should I register an object in my layer file using .instance or .settings files? What about .shadow files or serialization? |
| |
| There are a number of kinds of files which are treated (and can be transformed into) instances of objects. |
| |
| |=== |
| |What |When to Use It |How |
| |
| |`.instance` files |Almost all the time |Create a file whose name is the fully qualified name of the class you want to register, with the . characters replaced with - characters and the extension `.instance` - e.g. `<file name="com-foo-mymodule-MyStatusBarElementProvider.instance"/>`. You can also give the file a different name and instead declare the type using a link:DevFaqFileAttributes.asciidoc[FileObject attribute], e.g. <blockquote>`<file name="x.instance"> |
| <attr name="instanceClass" stringvalue="com.foo.mymodule.MyStatusBarElementProvider"/> |
| </file> `</blockquote> |
| [source,xml] |
| ---- |
| |
| If you want to use a factory method and set up some configuration of the object using your own link:DevFaqFileAttributes.asciidoc[FileObject attributes], you can instead <ul><li>Create a public static method on some class, which takes a `link:http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileObject.html[FileObject]` as an argument, e.g.<blockquote>`<file name="x.instance"> <attr name="instanceClass" stringvalue="com.foo.mymodule.MyStatusBarElementProvider"/> <attr name="instanceCreate" methodvalue="com.foo.mymodule.MyStatusBarElementProvider.factoryMethod"/> attr name="yourCustomAttribute" stringvalue="someValueYouCareAbout"/></file>`</blockquote> |
| ---- |
| |
| |
| |`.settings` files |In specialized situations when the object may be saved back to disk with changed state at runtime and you cannot simply use `NbPreferences` |Create an XML file in your module for your settings file, populated as described in link:DevFaqDotSettingsFiles.asciidoc[the .settings file FAQ]. Register that file in some folder by specifying the XML file as the URL of the `<file>` entry in your layer, e.g. `<file name="MyObject.settings" url="theActualFile.xml"/>` (in this case, the layer.xml file and the settings file are in the same Java package in your sources). |
| |
| |`.shadow` files |If you want your object to be a pseudo-singleton, but it will be registered in multiple folders, or the user may delete the shadow file and you need to provide a way for the user to recover it (i.e. a way to create a new `.shadow` file) |`link:DevFaqDotShadowFiles.asciidoc[.shadow]` files are like unix symbolic links - they point to another file somewhere else in the link:DevFaqSystemFilesystem.asciidoc[system filesystem] or on disk, and behave as if they were really that file. Use one of the other registration mechanisms described here to register your object in some folder. Then create a shadow file as link:DevFaqDotShadowFiles.asciidoc[described here] which points to it. |
| An example of this is Menu and Toolbar actions — all actions are registered in subfolders of the `Actions/` folder in the system filesystem. The user might manually delete or rearrange them; the UI that allows this can also show all available actions, so that the user can replace accidentally deleted actions. |
| |
| |`.ser` (serialized object) files |Basically never |Write a serialized object out to disk in a file with the extension `.ser`, either on the fly at runtime into some folder under `link:http://bits.netbeans.org/dev/javadoc/org-openide-filesystems/org/openide/filesystems/FileUtil.html#getConfigFile(java.lang.String)[FileUtil.getConfigFile()]`, or serialize an object ahead of time somehow, copy it into your module sources, and register something like `<file name="foo.ser" url="relative/path/in/module/sources/from/layer/dot/xml/to/foo.ser"/>`. Remember that if you use serialization, _any_ change to the class you serialized is likely to break loading of existing `.ser` files - this is almost never a good idea. |
| |
| |Your own file type |Basically never |Any link:DevFaqDataObject.asciidoc[DataObject] type which contains an `link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/cookies/InstanceCookie.html[InstanceCookie]` (and ideally also an `link:http://bits.netbeans.org/dev/javadoc/org-openide-nodes/org/openide/cookies/InstanceCookie.Of.html[InstanceCookie.Of]`) can be registered in some folder. If this is done ` link:http://bits.netbeans.org/dev/javadoc/org-openide-util-lookup/org/openide/util/lookup/Lookups.html#forPath(java.lang.String)[Lookups.forPath(&quot;path/to/parent/folder&quot;)] ` can be used to find it and any other objects registered in that folder (whatever their file type). So you could create your own file type which provides these objects. |
| Unless you are doing something very, very unusual, one of the existing registration mechanisms will almost always be sufficient. |
| This mechanism may be useful if you have existing code which reads and writes files in some format, and you cannot change that code. |
| |=== |
| |
| === 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/DevFaqRegisterObjectsViaInstanceOrSettingsFiles[http://wiki.netbeans.org/DevFaqRegisterObjectsViaInstanceOrSettingsFiles] , |
| that was last modified by NetBeans user Jglick |
| on 2010-06-14T22:30:44Z. |
| |
| |
| *NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed. |
