001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.configuration2.tree;
018
019import java.util.Collection;
020import java.util.List;
021import java.util.concurrent.atomic.AtomicBoolean;
022
023/**
024 * <p>
025 * A specialized {@code NodeModel} implementation that uses a tracked node
026 * managed by an {@link InMemoryNodeModel} object as root node.
027 * </p>
028 * <p>
029 * Models of this type are useful when working on specific sub trees of a nodes
030 * structure. This is the case for instance for a {@code SubnodeConfiguration}.
031 * </p>
032 * <p>
033 * An instance of this class is constructed with an
034 * {@link InMemoryNodeModelSupport} object providing a reference to the
035 * underlying {@code InMemoryNodeModel} and the {@link NodeSelector} pointing to
036 * the tracked node acting as this model's root node. The {@code NodeModel}
037 * operations are implemented by delegating to the wrapped
038 * {@code InMemoryNodeModel} object specifying the selector to the tracked node
039 * as target root node for the update transaction. Note that the tracked node
040 * can become detached at any time. This situation is handled transparently by
041 * the implementation of {@code InMemoryNodeModel}. The reason for using an
042 * {@code InMemoryNodeModelSupport} object rather than an
043 * {@code InMemoryNodeModel} directly is that this additional layer of
044 * indirection can be used for performing special initializations on the model
045 * before it is returned to the {@code TrackedNodeModel} object. This is needed
046 * by some dynamic configuration implementations, e.g. by
047 * {@code CombinedConfiguration}.
048 * </p>
049 * <p>
050 * If the tracked node acting as root node is exclusively used by this model, it
051 * should be released when this model is no longer needed. This can be done
052 * manually by calling the {@link #close()} method. It is also possible to pass
053 * a value of <strong>true</strong> to the {@code untrackOnFinalize} argument of
054 * the constructor. This causes {@code close()} to be called automatically if
055 * this object gets claimed by the garbage collector.
056 * </p>
057 * <p>
058 * As {@code InMemoryNodeModel}, this class is thread-safe.
059 * </p>
060 *
061 * @since 2.0
062 */
063public class TrackedNodeModel implements NodeModel<ImmutableNode>
064{
065    /** Stores the underlying parent model. */
066    private final InMemoryNodeModelSupport parentModelSupport;
067
068    /** The selector for the managed tracked node. */
069    private final NodeSelector selector;
070
071    /**
072     * A flag whether the tracked not should be released when this object is
073     * finalized.
074     */
075    private final boolean releaseTrackedNodeOnFinalize;
076
077    /** A flag whether this model has already been closed. */
078    private final AtomicBoolean closed;
079
080    /**
081     * Creates a new instance of {@code TrackedNodeModel} and initializes it
082     * with the given underlying model and the selector to the root node. The
083     * boolean argument controls whether the associated tracked node should be
084     * released when this object gets finalized. This allows the underlying
085     * model to free some resources. If used as model within a
086     * {@code SubnodeConfiguration}, there is typically no way to discard the
087     * model explicitly. Therefore, it makes sense to do this automatically on
088     * finalization.
089     *
090     * @param modelSupport the underlying {@code InMemoryNodeModelSupport} (must not be
091     *        <b>null</b>)
092     * @param sel the selector to the root node of this model (must not be
093     *        <b>null</b>)
094     * @param untrackOnFinalize a flag whether the tracked node should be
095     *        released on finalization
096     * @throws IllegalArgumentException if a required parameter is missing
097     */
098    public TrackedNodeModel(final InMemoryNodeModelSupport modelSupport, final NodeSelector sel,
099            final boolean untrackOnFinalize)
100    {
101        if (modelSupport == null)
102        {
103            throw new IllegalArgumentException(
104                    "Underlying model support must not be null!");
105        }
106        if (sel == null)
107        {
108            throw new IllegalArgumentException("Selector must not be null!");
109        }
110
111        parentModelSupport = modelSupport;
112        selector = sel;
113        releaseTrackedNodeOnFinalize = untrackOnFinalize;
114        closed = new AtomicBoolean();
115    }
116
117    /**
118     * Returns the {@code InMemoryNodeModelSupport} object which is used to gain
119     * access to the underlying node model.
120     *
121     * @return the associated {@code InMemoryNodeModelSupport} object
122     */
123    public InMemoryNodeModelSupport getParentModelSupport()
124    {
125        return parentModelSupport;
126    }
127
128    /**
129     * Returns the parent model. Operations on this model are delegated to this
130     * parent model specifying the selector to the tracked node.
131     *
132     * @return the parent model
133     */
134    public InMemoryNodeModel getParentModel()
135    {
136        return getParentModelSupport().getNodeModel();
137    }
138
139    /**
140     * Returns the {@code NodeSelector} pointing to the tracked node managed by
141     * this model.
142     *
143     * @return the tracked node selector
144     */
145    public NodeSelector getSelector()
146    {
147        return selector;
148    }
149
150    /**
151     * Returns the flag whether the managed tracked node is to be released when
152     * this object gets finalized. This method returns the value of the
153     * corresponding flag passed to the constructor. If result is true, the
154     * underlying model is asked to untrack the managed node when this object is
155     * claimed by the GC.
156     *
157     * @return a flag whether the managed tracked node should be released when
158     *         this object dies
159     * @see InMemoryNodeModel#untrackNode(NodeSelector)
160     */
161    public boolean isReleaseTrackedNodeOnFinalize()
162    {
163        return releaseTrackedNodeOnFinalize;
164    }
165
166    @Override
167    public void setRootNode(final ImmutableNode newRoot)
168    {
169        getParentModel().replaceTrackedNode(getSelector(), newRoot);
170    }
171
172    @Override
173    public NodeHandler<ImmutableNode> getNodeHandler()
174    {
175        return getParentModel().getTrackedNodeHandler(getSelector());
176    }
177
178    @Override
179    public void addProperty(final String key, final Iterable<?> values,
180            final NodeKeyResolver<ImmutableNode> resolver)
181    {
182        getParentModel().addProperty(key, getSelector(), values, resolver);
183    }
184
185    @Override
186    public void addNodes(final String key, final Collection<? extends ImmutableNode> nodes,
187            final NodeKeyResolver<ImmutableNode> resolver)
188    {
189        getParentModel().addNodes(key, getSelector(), nodes, resolver);
190    }
191
192    @Override
193    public void setProperty(final String key, final Object value,
194            final NodeKeyResolver<ImmutableNode> resolver)
195    {
196        getParentModel().setProperty(key, getSelector(), value, resolver);
197    }
198
199    @Override
200    public List<QueryResult<ImmutableNode>> clearTree(final String key,
201            final NodeKeyResolver<ImmutableNode> resolver)
202    {
203        return getParentModel().clearTree(key, getSelector(), resolver);
204    }
205
206    @Override
207    public void clearProperty(final String key,
208            final NodeKeyResolver<ImmutableNode> resolver)
209    {
210        getParentModel().clearProperty(key, getSelector(), resolver);
211    }
212
213    /**
214     * {@inheritDoc} This implementation clears the sub tree spanned by the
215     * associate tracked node. This has the side effect that this in any case
216     * becomes detached.
217     *
218     * @param resolver the {@code NodeKeyResolver}.
219     */
220    @Override
221    public void clear(final NodeKeyResolver<ImmutableNode> resolver)
222    {
223        getParentModel().clearTree(null, getSelector(), resolver);
224    }
225
226    /**
227     * {@inheritDoc} This implementation returns the tracked node instance
228     * acting as root node of this model.
229     */
230    @Override
231    public ImmutableNode getInMemoryRepresentation()
232    {
233        return getNodeHandler().getRootNode();
234    }
235
236    /**
237     * Closes this model. This causes the tracked node this model is based upon
238     * to be released (i.e. {@link InMemoryNodeModel#untrackNode(NodeSelector)}
239     * is called). This method should be called when this model is no longer
240     * needed. This implementation is idempotent; it is safe to call
241     * {@code close()} multiple times - only the first invocation has an effect.
242     * After this method has been called this model can no longer be used
243     * because there is no guarantee that the node can still be accessed from
244     * the parent model.
245     */
246    public void close()
247    {
248        if (closed.compareAndSet(false, true))
249        {
250            getParentModel().untrackNode(getSelector());
251        }
252    }
253
254    /**
255     * {@inheritDoc} This implementation calls {@code close()} if the
256     * {@code untrackOnFinalize} flag was set when this instance was
257     * constructed. While this is not 100 percent reliable, it is better than
258     * keeping the tracked node hanging around. Note that it is not a problem if
259     * {@code close()} already had been invoked manually because this method is
260     * idempotent.
261     *
262     * @see #close()
263     */
264    @Override
265    protected void finalize() throws Throwable
266    {
267        if (isReleaseTrackedNodeOnFinalize())
268        {
269            close();
270        }
271        super.finalize();
272    }
273}