content: /*
   * 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 com.aliyun.odps.graph;
  
  import java.io.IOException;
  
  import com.aliyun.odps.io.Writable;
  import com.aliyun.odps.io.WritableComparable;
  
  /**
   * ComputeContext 继承自 {@link WorkerContext}，传给
   * {@link Vertex#compute(ComputeContext, Iterable)} 方法的上下文.
   *
   * <p>
   * 在 {@link WorkerContext} 基础上，ComputeContext 提供了一些新功能，这些功能只能在
   * {@link Vertex#compute(ComputeContext, Iterable)} 方法中使用.
   *
   * @param <VERTEX_ID>
   *     Vertex ID 类型
   * @param <VERTEX_VALUE>
   *     Vertex Value 类型
   * @param <EDGE_VALUE>
   *     Edge Value 类型
   * @param <MESSAGE>
   *     Message 类型
   */
  @SuppressWarnings("rawtypes")
  public abstract class ComputeContext<VERTEX_ID extends WritableComparable, VERTEX_VALUE extends Writable, EDGE_VALUE extends Writable, MESSAGE extends Writable>
      extends WorkerContext<VERTEX_ID, VERTEX_VALUE, EDGE_VALUE, MESSAGE>
      implements MutationContext<VERTEX_ID, VERTEX_VALUE, EDGE_VALUE, MESSAGE> {
  
    /**
     * 发送消息到目标点，在下一个超步中会传给目标点的 {@link Vertex#compute(ComputeContext, Iterable)} 方法进行处理.
     *
     * @param destVertexID
     *     目标点 ID
     * @param msg
     *     待发送的消息
     * @throws IOException
     */
    public abstract void sendMessage(VERTEX_ID destVertexID, MESSAGE msg)
        throws IOException;
  
    /**
     * 发送一条消息到多个点。
     * 如果使用{@link GraphJob#setBroadcastMessageEnable(true)}开启广播优化，则msg参数
     * 不能在多次调用中复用。
     *
     * @param destVertexIDs
     *     目标点的集合
     * @param msg
     *     待发送的消息
     * @throws IOException
     */
    public abstract void sendMessage(Iterable<VERTEX_ID> destVertexIDs, MESSAGE msg)
        throws IOException;
  
    /**
     * 发送消息到给定点的所有邻接点，在下一个超步中会传给这些邻接点的
     * {@link Vertex#compute(ComputeContext, Iterable)} 方法进行处理.
     *
     * @param vertex
     *     目标点
     * @param msg
     *     待发送的消息
     * @throws IOException
     */
    public abstract void sendMessageToNeighbors(
        Vertex<VERTEX_ID, VERTEX_VALUE, EDGE_VALUE, MESSAGE> vertex, MESSAGE msg)
        throws IOException;
  
    /**
     * 聚合函数，item 对象传给所有的 Aggregators 进行聚合，通常在
     * {@link Vertex#compute(ComputeContext, Iterable)} 方法中调用.
     *
     * <p>
     * 如果 item 对象需要传给某一个 Aggregator 进行聚合，请使用 {@link #aggregate(int, Object)}.
     * </p>
     *
     * @param item
     *     待聚合对象
     * @throws IOException
     * @see Aggregator#aggregate(Writable, Object)
     * @see GraphJob#setAggregatorClass(Class...)
     * @see Vertex#compute(ComputeContext, Iterable)
     */
    public abstract void aggregate(Object item) throws IOException;
  
    /**
     * 聚合函数，item 对象传给给定编号（起始为 0）的 Aggregator 进行聚合，通常在
     * {@link Vertex#compute(ComputeContext, Iterable)} 方法中调用.
     *
     * <p>
     * 如果 item 对象需要传给所有 Aggregators 进行聚合，请使用 {@link #aggregate(Object)}.
     * </p>
     *
     * @param aggregatorIndex
     *     Aggregator编号，起始为 0
     * @param item
     *     待聚合对象
     * @throws IOException
     * @see Aggregator#aggregate(Writable, Object)
     * @see GraphJob#setAggregatorClass(Class...)
     * @see Vertex#compute(ComputeContext, Iterable)
     */
    public abstract void aggregate(int aggregatorIndex, Object item)
        throws IOException;
  }
  