/*

  * 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.partition;

 import org.apache.giraph.conf.ImmutableClassesGiraphConfigurable;

 import org.apache.giraph.graph.Vertex;

 import org.apache.giraph.utils.VertexIterator;

 import org.apache.hadoop.io.Writable;

 import org.apache.hadoop.io.WritableComparable;

 import org.apache.hadoop.util.Progressable;

 /**

  * A generic container that stores vertices.  Vertex ids will map to exactly

  * one partition.

  *

  * @param <I> Vertex id

  * @param <V> Vertex data

  * @param <E> Edge data

  */

 @SuppressWarnings("rawtypes")

 public interface Partition<I extends WritableComparable,

     V extends Writable, E extends Writable>

     extends Writable, ImmutableClassesGiraphConfigurable<I, V, E>,

     Iterable<Vertex<I, V, E>> {

   /**

    * Initialize the partition.  Guaranteed to be called before used.

    *

    * @param partitionId Partition id

    * @param progressable Progressable to call progress

    */

   void initialize(int partitionId, Progressable progressable);

   /**

    * Get the vertex for this vertex index.

    *

    * @param vertexIndex Vertex index to search for

    * @return Vertex if it exists, null otherwise

    */

   Vertex<I, V, E> getVertex(I vertexIndex);

   /**

    * Put a vertex into the Partition

    *

    * @param vertex Vertex to put in the Partition

    * @return old vertex value (i.e. null if none existed prior)

    */

   Vertex<I, V, E> putVertex(Vertex<I, V, E> vertex);

   /**

    * Remove a vertex from the Partition

    *

    * @param vertexIndex Vertex index to remove

    * @return The removed vertex.

    */

   Vertex<I, V, E> removeVertex(I vertexIndex);

   /**

    * Add a partition's vertices.  If a vertex to be added doesn't exist,

    * add it.  If the vertex already exists, use the

    * VertexValueCombiner to combine them.

    *

    * @param partition Partition to add

    */

   void addPartition(Partition<I, V, E> partition);

   /**

    * Put this vertex or combine it

    *

    * @param vertex Vertex to put or combine

    * @return True if the vertex was put (hint to release object)

    */

   boolean putOrCombine(Vertex<I, V, E> vertex);

   /**

    * Add vertices to a partition.  If a vertex to be added doesn't exist,

    * add it.  If the vertex already exists, use the

    * VertexValueCombiner to combine them.

    *

    * @param vertexIterator Vertices to add

    */

   void addPartitionVertices(VertexIterator<I, V, E> vertexIterator);

   /**

    * Get the number of vertices in this partition

    *

    * @return Number of vertices

    */

   long getVertexCount();

   /**

    * Get the number of edges in this partition.

    *

    * @return Number of edges.

    */

   long getEdgeCount();

   /**

    * Get the partition id.

    *

    * @return Id of this partition.

    */

   int getId();

   /**

    * Set the partition id.

    *

    * @param id Id of this partition

    */

   void setId(int id);

   /**

    * Report progress.

    */

   void progress();

   /**

    * Set the context.

    *

    * @param progressable Progressable

    */

   void setProgressable(Progressable progressable);

   /**

    * Save potentially modified vertex back to the partition.

    *

    * @param vertex Vertex to save

    */

   void saveVertex(Vertex<I, V, E> vertex);

 }