giraph-core/src/main/java/org/apache/giraph/graph/Vertex.java

/*
 * 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.giraph.graph;

import org.apache.giraph.conf.ImmutableClassesGiraphConfigurable;
import org.apache.giraph.edge.Edge;
import org.apache.giraph.edge.MutableEdge;
import org.apache.hadoop.io.Writable;
import org.apache.hadoop.io.WritableComparable;

/**
 * Class which holds vertex id, data and edges.
 *
 * @param <I> Vertex id
 * @param <V> Vertex data
 * @param <E> Edge data
 */
public interface Vertex<I extends WritableComparable,
    V extends Writable, E extends Writable> extends
    ImmutableClassesGiraphConfigurable<I, V, E> {
  /**
   * Initialize id, value, and edges.
   * This method (or the alternative form initialize(id, value)) must be called
   * after instantiation, unless readFields() is called.
   *
   * @param id Vertex id
   * @param value Vertex value
   * @param edges Iterable of edges
   */
  void initialize(I id, V value, Iterable<Edge<I, E>> edges);

  /**
   * Initialize id and value. Vertex edges will be empty.
   * This method (or the alternative form initialize(id, value, edges))
   * must be called after instantiation, unless readFields() is called.
   *
   * @param id Vertex id
   * @param value Vertex value
   */
  void initialize(I id, V value);

  /**
   * Get the vertex id.
   *
   * @return My vertex id.
   */
  I getId();

  /**
   * Get the vertex value (data stored with vertex)
   *
   * @return Vertex value
   */
  V getValue();

  /**
   * Set the vertex data (immediately visible in the computation)
   *
   * @param value Vertex data to be set
   */
  void setValue(V value);

  /**
   * After this is called, the compute() code will no longer be called for
   * this vertex unless a message is sent to it.  Then the compute() code
   * will be called once again until this function is called.  The
   * application finishes only when all vertices vote to halt.
   */
  void voteToHalt();

  /**
   * Get the number of outgoing edges on this vertex.
   *
   * @return the total number of outbound edges from this vertex
   */
  int getNumEdges();

  /**
   * Get a read-only view of the out-edges of this vertex.
   * Note: edge objects returned by this iterable may be invalidated as soon
   * as the next element is requested. Thus, keeping a reference to an edge
   * almost always leads to undesired behavior.
   * Accessing the edges with other methods (e.g., addEdge()) during iteration
   * leads to undefined behavior.
   *
   * @return the out edges (sort order determined by subclass implementation).
   */
  Iterable<Edge<I, E>> getEdges();

  /**
   * Set the outgoing edges for this vertex.
   *
   * @param edges Iterable of edges
   */
  void setEdges(Iterable<Edge<I, E>> edges);

  /**
   * Get an iterable of out-edges that can be modified in-place.
   * This can mean changing the current edge value or removing the current edge
   * (by using the iterator version).
   * Note: accessing the edges with other methods (e.g., addEdge()) during
   * iteration leads to undefined behavior.
   *
   * @return An iterable of mutable out-edges
   */
  Iterable<MutableEdge<I, E>> getMutableEdges();

  /**
   * Return the value of the first edge with the given target vertex id,
   * or null if there is no such edge.
   * Note: edge value objects returned by this method may be invalidated by
   * the next call. Thus, keeping a reference to an edge value almost always
   * leads to undesired behavior.
   *
   * @param targetVertexId Target vertex id
   * @return Edge value (or null if missing)
   */
  E getEdgeValue(I targetVertexId);

  /**
   * If an edge to the target vertex exists, set it to the given edge value.
   * This only makes sense with strict graphs.
   *
   * @param targetVertexId Target vertex id
   * @param edgeValue Edge value
   */
  void setEdgeValue(I targetVertexId, E edgeValue);

  /**
   * Get an iterable over the values of all edges with the given target
   * vertex id. This only makes sense for multigraphs (i.e. graphs with
   * parallel edges).
   * Note: edge value objects returned by this method may be invalidated as
   * soon as the next element is requested. Thus, keeping a reference to an
   * edge value almost always leads to undesired behavior.
   *
   * @param targetVertexId Target vertex id
   * @return Iterable of edge values
   */
  Iterable<E> getAllEdgeValues(final I targetVertexId);

  /**
   * Add an edge for this vertex (happens immediately)
   *
   * @param edge Edge to add
   */
  void addEdge(Edge<I, E> edge);

  /**
   * Removes all edges pointing to the given vertex id.
   *
   * @param targetVertexId the target vertex id
   */
  void removeEdges(I targetVertexId);

  /**
   * If a {@link org.apache.giraph.edge.MutableEdgesWrapper} was used to
   * provide a mutable iterator, copy any remaining edges to the new
   * {@link org.apache.giraph.edge.OutEdges} data structure and keep a direct
   * reference to it (thus discarding the wrapper).
   * Called by the Giraph infrastructure after computation.
   */
  void unwrapMutableEdges();

  /**
   * Re-activate vertex if halted.
   */
  void wakeUp();

  /**
   * Is this vertex done?
   *
   * @return True if halted, false otherwise.
   */
  boolean isHalted();
}