This project has retired. For details please refer to its Attic page.
Vertex xref
View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.apache.giraph.graph;
20  
21  import org.apache.giraph.conf.ImmutableClassesGiraphConfigurable;
22  import org.apache.giraph.edge.Edge;
23  import org.apache.giraph.edge.MutableEdge;
24  import org.apache.hadoop.io.Writable;
25  import org.apache.hadoop.io.WritableComparable;
26  
27  /**
28   * Class which holds vertex id, data and edges.
29   *
30   * @param <I> Vertex id
31   * @param <V> Vertex data
32   * @param <E> Edge data
33   */
34  public interface Vertex<I extends WritableComparable,
35      V extends Writable, E extends Writable> extends
36      ImmutableClassesGiraphConfigurable<I, V, E> {
37    /**
38     * Initialize id, value, and edges.
39     * This method (or the alternative form initialize(id, value)) must be called
40     * after instantiation, unless readFields() is called.
41     *
42     * @param id Vertex id
43     * @param value Vertex value
44     * @param edges Iterable of edges
45     */
46    void initialize(I id, V value, Iterable<Edge<I, E>> edges);
47  
48    /**
49     * Initialize id and value. Vertex edges will be empty.
50     * This method (or the alternative form initialize(id, value, edges))
51     * must be called after instantiation, unless readFields() is called.
52     *
53     * @param id Vertex id
54     * @param value Vertex value
55     */
56    void initialize(I id, V value);
57  
58    /**
59     * Get the vertex id.
60     *
61     * @return My vertex id.
62     */
63    I getId();
64  
65    /**
66     * Get the vertex value (data stored with vertex)
67     *
68     * @return Vertex value
69     */
70    V getValue();
71  
72    /**
73     * Set the vertex data (immediately visible in the computation)
74     *
75     * @param value Vertex data to be set
76     */
77    void setValue(V value);
78  
79    /**
80     * After this is called, the compute() code will no longer be called for
81     * this vertex unless a message is sent to it.  Then the compute() code
82     * will be called once again until this function is called.  The
83     * application finishes only when all vertices vote to halt.
84     */
85    void voteToHalt();
86  
87    /**
88     * Get the number of outgoing edges on this vertex.
89     *
90     * @return the total number of outbound edges from this vertex
91     */
92    int getNumEdges();
93  
94    /**
95     * Get a read-only view of the out-edges of this vertex.
96     * Note: edge objects returned by this iterable may be invalidated as soon
97     * as the next element is requested. Thus, keeping a reference to an edge
98     * almost always leads to undesired behavior.
99     * Accessing the edges with other methods (e.g., addEdge()) during iteration
100    * leads to undefined behavior.
101    *
102    * @return the out edges (sort order determined by subclass implementation).
103    */
104   Iterable<Edge<I, E>> getEdges();
105 
106   /**
107    * Set the outgoing edges for this vertex.
108    *
109    * @param edges Iterable of edges
110    */
111   void setEdges(Iterable<Edge<I, E>> edges);
112 
113   /**
114    * Get an iterable of out-edges that can be modified in-place.
115    * This can mean changing the current edge value or removing the current edge
116    * (by using the iterator version).
117    * Note: accessing the edges with other methods (e.g., addEdge()) during
118    * iteration leads to undefined behavior.
119    *
120    * @return An iterable of mutable out-edges
121    */
122   Iterable<MutableEdge<I, E>> getMutableEdges();
123 
124   /**
125    * Return the value of the first edge with the given target vertex id,
126    * or null if there is no such edge.
127    * Note: edge value objects returned by this method may be invalidated by
128    * the next call. Thus, keeping a reference to an edge value almost always
129    * leads to undesired behavior.
130    *
131    * @param targetVertexId Target vertex id
132    * @return Edge value (or null if missing)
133    */
134   E getEdgeValue(I targetVertexId);
135 
136   /**
137    * If an edge to the target vertex exists, set it to the given edge value.
138    * This only makes sense with strict graphs.
139    *
140    * @param targetVertexId Target vertex id
141    * @param edgeValue Edge value
142    */
143   void setEdgeValue(I targetVertexId, E edgeValue);
144 
145   /**
146    * Get an iterable over the values of all edges with the given target
147    * vertex id. This only makes sense for multigraphs (i.e. graphs with
148    * parallel edges).
149    * Note: edge value objects returned by this method may be invalidated as
150    * soon as the next element is requested. Thus, keeping a reference to an
151    * edge value almost always leads to undesired behavior.
152    *
153    * @param targetVertexId Target vertex id
154    * @return Iterable of edge values
155    */
156   Iterable<E> getAllEdgeValues(final I targetVertexId);
157 
158   /**
159    * Add an edge for this vertex (happens immediately)
160    *
161    * @param edge Edge to add
162    */
163   void addEdge(Edge<I, E> edge);
164 
165   /**
166    * Removes all edges pointing to the given vertex id.
167    *
168    * @param targetVertexId the target vertex id
169    */
170   void removeEdges(I targetVertexId);
171 
172   /**
173    * If a {@link org.apache.giraph.edge.MutableEdgesWrapper} was used to
174    * provide a mutable iterator, copy any remaining edges to the new
175    * {@link org.apache.giraph.edge.OutEdges} data structure and keep a direct
176    * reference to it (thus discarding the wrapper).
177    * Called by the Giraph infrastructure after computation.
178    */
179   void unwrapMutableEdges();
180 
181   /**
182    * Re-activate vertex if halted.
183    */
184   void wakeUp();
185 
186   /**
187    * Is this vertex done?
188    *
189    * @return True if halted, false otherwise.
190    */
191   boolean isHalted();
192 }
193