You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@jackrabbit.apache.org by ju...@apache.org on 2012/03/06 17:04:28 UTC
svn commit: r1297546 - in
/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree:
./ ChildNodeEntry.java NodeState.java PropertyState.java
Author: jukka
Date: Tue Mar 6 16:04:27 2012
New Revision: 1297546
URL: http://svn.apache.org/viewvc?rev=1297546&view=rev
Log:
OAK-3: Internal tree model
Add draft interfaces
Added:
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java (with props)
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java (with props)
jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java (with props)
Added: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java?rev=1297546&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java (added)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java Tue Mar 6 16:04:27 2012
@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+package org.apache.jackrabbit.oak.tree;
+
+/**
+ * TODO: document
+ */
+public interface ChildNodeEntry {
+
+ /**
+ * TODO: document
+ */
+ String getName();
+
+ /**
+ * TODO: document
+ */
+ NodeState getNode();
+
+}
Propchange: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/ChildNodeEntry.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java?rev=1297546&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java (added)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java Tue Mar 6 16:04:27 2012
@@ -0,0 +1,148 @@
+/*
+ * 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.
+ */
+package org.apache.jackrabbit.oak.tree;
+
+/**
+ * A content tree consists of nodes and properties, each of which
+ * evolves through different states during its lifecycle. This interface
+ * represents a specific, immutable state of a node in a content tree.
+ * A node consists of an unordered set of name -> item mappings, where
+ * each item is either a property or a child node.
+ * <p>
+ * Depending on context, a NodeState instance can be interpreted as
+ * representing the state of just that node, of the subtree starting at
+ * that node, or of an entire tree in case it's a root node.
+ * <p>
+ * The crucial difference between this interface and the similarly named
+ * class in Jackrabbit 2.x is that this interface represents a specific,
+ * immutable state of a node, whereas the Jackrabbit 2.x class represented
+ * the <em>current</em> state of a node.
+ *
+ * <h2>Immutability and thread-safety</h2>
+ * <p>
+ * As mentioned above, all node and property states are always immutable.
+ * Thus repeating a method call is always guaranteed to produce the same
+ * result as before unless some internal error occurs (see below). This
+ * immutability only applies to a specific state instance. Different states
+ * of a node can obviously be different, and in some cases even different
+ * instances of the same state may behave slightly differently. For example
+ * due to performance optimization or other similar changes the iteration
+ * order of properties or child nodes may be different for two instances
+ * of the same state.
+ * <p>
+ * In addition to being immutable, a specific state instance guaranteed to
+ * be fully thread-safe. Possible caching or other internal changes need to
+ * be properly synchronized so that any number of concurrent clients can
+ * safely access a state instance.
+ *
+ * <h2>Persistence and error-handling</h2>
+ * <p>
+ * A node state can be (and often is) backed by local files or network
+ * resources. All IO operations or related concerns like caching should be
+ * handled transparently below this interface. Potential IO problems and
+ * recovery attempts like retrying a timed-out network access need to be
+ * handled below this interface, and only hard errors should be thrown up
+ * as {@link RuntimeException unchecked exceptions} that higher level code
+ * is not expected to be able to recover from.
+ * <p>
+ * Since this interface exposes no higher level constructs like access
+ * controls, locking, node types or even path parsing, there's no way
+ * for content access to fail because of such concerns. Such functionality
+ * and related checked exceptions or other control flow constructs should
+ * be implemented on a higher level above this interface.
+ *
+ * <h2>Decoration and virtual content</h2>
+ * <p>
+ * Not all content exposed by this interface needs to be backed by actual
+ * persisted data. An implementation may want to provide derived data,
+ * like for example the aggregate size of the entire subtree as an
+ * extra virtual property. A virtualization, sharding or caching layer
+ * could provide a composite view over multiple underlying content trees.
+ * Or a basic access control layer could decide to hide certain content
+ * based on specific rules. All such features need to be implemented
+ * according to the API contract of this interface. A separate higher level
+ * interface needs to be used if an implementation can't for example
+ * guarantee immutability of exposed content as discussed above.
+ */
+public interface NodeState {
+
+ /**
+ * Returns the named property. The name is an opaque string and
+ * is not parsed or otherwise interpreted by this method.
+ * <p>
+ * The namespace of properties and child nodes is shared, so if
+ * this method returns a non-<code>null</code> value for a given
+ * name, then {@link #getChildNode(String)} is guaranteed to return
+ * <code>null</code> for the same name.
+ *
+ * @param name name of the property to return
+ * @return named property, or <code>null</code> if not found
+ */
+ PropertyState getProperty(String name);
+
+ /**
+ * Returns the number of properties of this node.
+ *
+ * @return number of properties
+ */
+ long getPropertyCount();
+
+ /**
+ * Returns an iterable of the properties of this node. Multiple
+ * iterations are guaranteed to return the properties in the same
+ * order, but the specific order used is implementation-dependent
+ * and may change across different states of the same node.
+ *
+ * @return properties in some stable order
+ */
+ Iterable<PropertyState> getProperties();
+
+ /**
+ * Returns the named child node. The name is an opaque string and
+ * is not parsed or otherwise interpreted by this method.
+ * <p>
+ * The namespace of properties and child nodes is shared, so if
+ * this method returns a non-<code>null</code> value for a given
+ * name, then {@link #getProperty(String)} is guaranteed to return
+ * <code>null</code> for the same name.
+ *
+ * @param name name of the child node to return
+ * @return named child node, or <code>null</code> if not found
+ */
+ NodeState getChildNode(String name);
+
+ /**
+ * Returns the number of child nodes of this node.
+ *
+ * @return number of child nodes
+ */
+ long getChildNodeCount();
+
+ /**
+ * Returns an iterable of the child node entries starting from the
+ * given offset. Multiple iterations are guaranteed to return the
+ * child nodes in the same order, but the specific order used is
+ * implementation-dependent and may change across different states
+ * of the same node. An empty iterable is returned if the given
+ * offset is greater than the offset of the last child node entry.
+ *
+ * @param offset zero-based offset of the first entry to return
+ * @return requested child node entries in some stable order
+ */
+ Iterable<ChildNodeEntry> getChildNodeEntries(long offset);
+
+}
Propchange: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/NodeState.java
------------------------------------------------------------------------------
svn:eol-style = native
Added: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java?rev=1297546&view=auto
==============================================================================
--- jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java (added)
+++ jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java Tue Mar 6 16:04:27 2012
@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+package org.apache.jackrabbit.oak.tree;
+
+/**
+ * TODO: document
+ */
+public interface PropertyState {
+
+ /**
+ * TODO: document
+ */
+ String getName();
+
+ /**
+ * FIXME: replace with type-specific accessors
+ */
+ String getEncodedValue();
+
+}
Propchange: jackrabbit/oak/trunk/oak-core/src/main/java/org/apache/jackrabbit/oak/tree/PropertyState.java
------------------------------------------------------------------------------
svn:eol-style = native