| // |
| // 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. |
| // |
| |
| = DevFaqSysFsLookupRegistration |
| :jbake-type: wiki |
| :jbake-tags: wiki, devfaq, needsreview |
| :jbake-status: published |
| :keywords: Apache NetBeans wiki DevFaqSysFsLookupRegistration |
| :description: Apache NetBeans wiki DevFaqSysFsLookupRegistration |
| :toc: left |
| :toc-title: |
| :syntax: true |
| |
| === How can I register services into the default lookup using the system filesystem? |
| |
| In short, you probably do not want to. |
| The typical way of registering services is via `META-INF/services` registration: link:DevFaqLookupDefault.asciidoc[DevFaqLookupDefault]. |
| That method is easier to use and offers compatibility with non-platform applications via the Java Extension Mechanism. |
| |
| But there are some special cases when registration via the system filesystem is needed. |
| One example might be when you want to dynamically change or unregister services, |
| since the system filesystem is writable at runtime. |
| Again such needs are rare and you should probably avoid doing this unless there is no alternative. |
| (Usually the service interface should be defined so that the service itself is a singleton, |
| but it can create other objects on demand and signal certain events.) |
| Another minor use case is to register several services with the same implementation class but different parameters; |
| `META-INF/services` registrations require a zero-argument constructor, |
| meaning you need a different implementation class for each distinct service. |
| |
| As an example, assume that Module 1 defines an interface `com.tomwheeler.example.intf.SampleInterface` which is exported to other modules. |
| Module 2 depends on Module 1 and provides an implementation of that interface named `com.tomwheeler.example.impl.SampleImplementation`. |
| Module 1 does not need anything in its layer file (or even need a layer file at all), |
| but Module 2 can register the service like this: |
| |
| [source,xml] |
| ---- |
| |
| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE filesystem PUBLIC "-//NetBeans//DTD Filesystem 1.2//EN" |
| "http://www.netbeans.org/dtds/filesystem-1_2.dtd"> |
| <filesystem> |
| <folder name="Services"> |
| <folder name="wheeler-sample"> |
| <file name="com-tomwheeler-example-this-name-is-Irrelevant.instance"> |
| <attr name="instanceClass" |
| stringvalue="com.tomwheeler.example.impl.SampleImplementation"/> |
| <attr name="instanceOf" |
| stringvalue="com.tomwheeler.example.intf.SampleInterface"/> |
| </file> |
| </folder> |
| </folder> |
| </filesystem> |
| |
| ---- |
| |
| The name of the file is arbitrary but must end with `.instance`. |
| The value of the `instanceClass` attribute needs to define the implementation class being registered, |
| while `instanceOf` defines the interface (or abstract class) being implemented. |
| |
| If you want to create the implementation using a factory method rather than calling a zero-argument constructor, |
| replace `instanceClass` with `instanceCreate`, e.g.: |
| |
| [source,xml] |
| ---- |
| |
| <attr name="instanceCreate" |
| methodvalue="com.tomwheeler.example.impl.SampleImplementations.make"/> |
| |
| ---- |
| |
| It is also possible to pass parameters to the factory method; |
| see link:http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/doc-files/api.html#instances[API documentation] for details. |
| |
| Client code is unaware of the registration mechanism, so the code used to look up a registered implementation of the interface would be the same as always; for example: |
| |
| [source,java] |
| ---- |
| |
| SampleInterface intf = Lookup.getDefault().lookup(SampleInterface.class); |
| // now do something with intf... |
| |
| ---- |
| |
| === 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/DevFaqSysFsLookupRegistration[http://wiki.netbeans.org/DevFaqSysFsLookupRegistration] , |
| that was last modified by NetBeans user Silhanek |
| on 2011-01-28T21:16:34Z. |
| |
| |
| *NOTE:* This document was automatically converted to the AsciiDoc format on 2018-02-07, and needs to be reviewed. |