001 /*
002 * JBoss DNA (http://www.jboss.org/dna)
003 * See the COPYRIGHT.txt file distributed with this work for information
004 * regarding copyright ownership. Some portions may be licensed
005 * to Red Hat, Inc. under one or more contributor license agreements.
006 * See the AUTHORS.txt file in the distribution for a full listing of
007 * individual contributors.
008 *
009 * Unless otherwise indicated, all code in JBoss DNA is licensed
010 * to you under the terms of the GNU Lesser General Public License as
011 * published by the Free Software Foundation; either version 2.1 of
012 * the License, or (at your option) any later version.
013 *
014 * JBoss DNA is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this software; if not, write to the Free
021 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
022 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
023 */
024 package org.jboss.dna.jcr.cache;
025
026 import java.util.UUID;
027 import net.jcip.annotations.Immutable;
028 import org.jboss.dna.graph.property.Name;
029 import org.jboss.dna.graph.property.Path;
030
031 /**
032 * The representation of a child node. This is an immutable representation of a child node within the collection of its siblings
033 * as the collection appeared at some point in time. This should be used as a guide to determine how long to hold onto references.
034 * <p>
035 * For example, adding and removing children may affect the {@link #getSnsIndex() same-name-sibling index} of the children, so
036 * these kinds of operations will result in the replacement of old ChildObject instances. Therefore, clients should generally find
037 * the ChildNode instances in a {@link Children} container, use the ChildNode objects quickly, then discard their references.
038 * </p>
039 * <p>
040 * There may be times when a client does wish to keep a representation of a ChildNode as it appeared at some moment in time, and
041 * so it may want to hold onto references to ChildNode objects for longer durations. This is fine, as long as it is understood
042 * that at some point the referenced ChildNode may no longer represent the current state.
043 * </p>
044 */
045 @Immutable
046 public final class ChildNode {
047
048 private final UUID uuid;
049 private final Path.Segment segment;
050
051 public ChildNode( UUID uuid,
052 Path.Segment segment ) {
053 assert uuid != null;
054 assert segment != null;
055 this.uuid = uuid;
056 this.segment = segment;
057 }
058
059 /**
060 * Get the UUID of the node.
061 *
062 * @return the node's UUID; never null
063 */
064 public UUID getUuid() {
065 return uuid;
066 }
067
068 /**
069 * Get the path segment for this node.
070 *
071 * @return the path segment; never null
072 */
073 public Path.Segment getSegment() {
074 return segment;
075 }
076
077 /**
078 * Get the name of the node.
079 *
080 * @return the node's current name; never null
081 */
082 public Name getName() {
083 return segment.getName();
084 }
085
086 /**
087 * Get the same-name-sibling index of the node.
088 *
089 * @return the node's SNS index; always positive
090 */
091 public int getSnsIndex() {
092 return segment.getIndex();
093 }
094
095 /**
096 * {@inheritDoc}
097 *
098 * @see java.lang.Object#hashCode()
099 */
100 @Override
101 public int hashCode() {
102 return uuid.hashCode();
103 }
104
105 /**
106 * {@inheritDoc}
107 *
108 * @see java.lang.Object#equals(java.lang.Object)
109 */
110 @Override
111 public boolean equals( Object obj ) {
112 if (obj == this) return true;
113 if (obj instanceof ChildNode) {
114 return this.uuid.equals(((ChildNode)obj).uuid);
115 }
116 return false;
117 }
118
119 /**
120 * {@inheritDoc}
121 *
122 * @see java.lang.Object#toString()
123 */
124 @Override
125 public String toString() {
126 return uuid.toString() + " ( " + getSegment() + " )";
127 }
128
129 /**
130 * Obtain a new instance that uses the same {@link #getUuid() UUID} but the supplied path segment.
131 *
132 * @param newSegment the new segment; may not be null
133 * @return the new instance; never null
134 */
135 public ChildNode with( Path.Segment newSegment ) {
136 return new ChildNode(uuid, newSegment);
137 }
138
139 }