云计算仿真工具中文注释CloudInformationService.java

/*
 * Title:        CloudSim Toolkit
 * Description:  CloudSim (Cloud Simulation) Toolkit for Modeling and Simulation of Clouds
 * Licence:      GPL - http://www.gnu.org/copyleft/gpl.html
 *
 * Copyright (c) 2009-2010, The University of Melbourne, Australia
 */

package org.cloudbus.cloudsim.core;

import java.util.Calendar;
import java.util.Collection;
import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;

import org.cloudbus.cloudsim.Log;

/**
 * 一个云信息中心是一个实体，继承实体类，实体允许网格资源注册，标记和发现服务。
 * 其他实体如资源代理可以联系这个类用于发现是否可以服务，CIS会返回一系列的注册资源的ID
 * 总之，它扮演的是黄页服务
 * 这个类在cloudsim初始化是创建，cloudsim.init()中创建，因此不用担心创建这个类。
 * 这个类在cloudsim初始化是创建，cloudsim.init()中创建，因此不用担心创建这个类。
 * 方法总结：
 * 实体启动，任何实体都必须覆盖的方法
 * 事件处理，任何实体都必须覆盖的方法
 * CIS关闭
 * 检查某个ID实体是否在Advanced Reservations
 * 实体ID是否存在
 * 向列表中各个实体发送END_OF_SIMULATION消息,该消息延迟时间为0
 * A Cloud Information Service (GIS) is an entity that provides grid
 * resource registration, indexing and discovery services. The Cloud hostList
 * tell their readiness to process Cloudlets by registering themselves with
 * this entity, done via {@link gridsim.CloudResource#startEntity()} method.
 * <p>
 * Other entities such as the resource broker can contact
 * this class for resource discovery service, which returns a list of
 * registered resource IDs. In summary, it acts like a yellow page service.
 * <p>
 * This class will be created by CloudSim upon initialisation of the simulation,
 * i.e. done via {@link gridsim.CloudSim#init(int, Calendar, boolean)} method.
 * Hence, do not need to worry about creating an object of this class.
 * <p>
 * @author		Manzur Murshed
 * @author		Rajkumar Buyya
 * @since		CloudSim Toolkit 1.0
 */
public class CloudInformationService extends SimEntity {

    /** For all types of hostList. */
    private final List<Integer> resList;

    /** Only for AR hostList. */
    private final List<Integer> arList;

    /** List of all regional GIS. */
    private final List<Integer> gisList;

    /**
     * Allocates a new CloudInformationService object.
     * @param name       the name to be associated with this entity (as
     * required by SimEntity class)
     * @throws Exception This happens when creating this entity before
     * initialising CloudSim package or this entity name is
     * <tt>null</tt> or empty
     * @see gridsim.CloudSim#init(int, Calendar, boolean)
     * @see yoursim.SimEntity
     * @pre name != null
     * @post $none
     */
	public CloudInformationService(String name) throws Exception {
		super(name);
		resList = new LinkedList<Integer>();
		arList = new LinkedList<Integer>();
		gisList = new LinkedList<Integer>();
	}

    /**
     * 实体启动，任何实体都必须覆盖的方法
     * Starts the CloudInformationService entity.
     */
    @Override
	public void startEntity() { }

    /**
     * 事件处理，任何实体都必须覆盖的方法
     * Processes events scheduled for this entity.
     *
     * @param ev the event to be handled.
     *
     * @see SimEntity#processEvent(SimEvent)
     */
    @Override
	public void processEvent(SimEvent ev) {
    	int id = -1;  // requester id
        switch ( ev.getTag() )
        {
                // storing regional GIS id
            case CloudSimTags.REGISTER_REGIONAL_GIS:
                gisList.add( (Integer) ev.getData() );
                break;

                // request for all regional GIS list
            case CloudSimTags.REQUEST_REGIONAL_GIS:

                // Get ID of an entity that send this event
                id = ( (Integer) ev.getData() ).intValue();

                // Send the regional GIS list back to sender
                super.send(id, 0L, ev.getTag(), gisList);
                break;

                // A resource is requesting to register.
            case CloudSimTags.REGISTER_RESOURCE:
                resList.add( (Integer) ev.getData() );
                break;

                // A resource that can support Advance Reservation
            case CloudSimTags.REGISTER_RESOURCE_AR:
                resList.add( (Integer) ev.getData() );
                arList.add( (Integer) ev.getData() );
                break;

                // A Broker is requesting for a list of all hostList.
            case CloudSimTags.RESOURCE_LIST:

                // Get ID of an entity that send this event
                id = ( (Integer) ev.getData() ).intValue();

                // Send the resource list back to the sender
                super.send(id, 0L, ev.getTag(), resList);
                break;

                // A Broker is requesting for a list of all hostList.
            case CloudSimTags.RESOURCE_AR_LIST:

                // Get ID of an entity that send this event
                id = ( (Integer) ev.getData() ).intValue();

                // Send the resource AR list back to the sender
                super.send(id, 0L, ev.getTag(), arList);
                break;

            default:
                processOtherEvent(ev);
                break;
        }
    }

    /**
     * CIS关闭
     * Shutdowns the CloudInformationService.
     */
    @Override
	public void shutdownEntity() {
    	notifyAllEntity();
    }

    /**
     * Gets the list of all CloudResource IDs, including hostList that support
     * Advance Reservation.
     *
     * @return LinkedList containing resource IDs. Each ID is represented by
     * an Integer object.
     *
     * @pre $none
     * @post $none
     */
    public List<Integer> getList() {
        return resList;
    }

    /**
     * Gets the list of CloudResource IDs that <b>only</b> support
     * Advanced Reservation.
     *
     * @return LinkedList containing resource IDs. Each ID is represented by
     * an Integer object.
     *
     * @pre $none
     * @post $none
     */
    public List<Integer> getAdvReservList() {
        return arList;
    }

    /**
     * 检查某个ID实体是否在Advanced Reservations
     * Checks whether a given resource ID supports Advanced Reservations or not.
     *
     * @param id  a resource ID
     *
     * @return <tt>true</tt> if this resource supports Advanced Reservations,
     * <tt>false</tt> otherwise
     *
     * @pre id != null
     * @post $none
     */
	public boolean resourceSupportAR(Integer id) {
		if (id == null) {
			return false;
		}

		return resourceSupportAR(id.intValue());
	}

    /**
     * 检查某个ID实体是否在Advanced Reservations
     * Checks whether a given resource ID supports Advanced Reservations or not.
     *
     * @param id  a resource ID
     *
     * @return <tt>true</tt> if this resource supports Advanced Reservations,
     * <tt>false</tt> otherwise
     *
     * @pre id >= 0
     * @post $none
     */
	public boolean resourceSupportAR(int id) {
		boolean flag = false;
		if (id < 0) {
			flag = false;
		} else {
			flag = checkResource(arList, id);
		}

		return flag;
	}

    /**
     * 实体ID是否存在
     * Checks whether the given CloudResource ID exists or not.
     *
     * @param id    a CloudResource id
     *
     * @return <tt>true</tt> if the given ID exists, <tt>false</tt> otherwise
     *
     * @pre id >= 0
     * @post $none
     */
    public boolean resourceExist(int id) {
        boolean flag = false;
        if (id < 0) {
            flag = false;
        } else {
            flag = checkResource(resList, id);
        }

        return flag;
    }

    /**
     * Checks whether the given CloudResource ID exists or not.
     *
     * @param id    a CloudResource id
     *
     * @return <tt>true</tt> if the given ID exists, <tt>false</tt> otherwise
     *
     * @pre id != null
     * @post $none
     */
    public boolean resourceExist(Integer id) {
        if (id == null) {
            return false;
        }
        return resourceExist( id.intValue() );
    }

    // PROTECTED METHODS 

    /**
     * 处理其他事件
     * This method needs to override by a child class for processing
     * other events.
     * These events are based on tags that are not mentioned in
     * {@link #body()} method.
     *
     * @param ev   a Sim_event object
     *
     * @pre ev != null
     * @post $none
     */
    protected void processOtherEvent(SimEvent ev) {
        if (ev == null) {
            Log.printLine("CloudInformationService.processOtherEvent(): " +
                    "Unable to handle a request since the event is null.");
            return;
        }

        Log.printLine("CloudInformationSevice.processOtherEvent(): " +
                "Unable to handle a request from " +
                CloudSim.getEntityName( ev.getSource() ) +
                " with event tag = " + ev.getTag() );
    }

    /**
     * Notifies the registered entities about the end of simulation.
     * This method should be overridden by the child class
     */
    protected void processEndSimulation() {
        // this should be overridden by the child class
    }


     End of PROTECTED METHODS ///

    /**
     * 检查某个ID实体是否在列表中
     * Checks for a list for a particular resource id.
     *
     * @param list   list of hostList
     * @param id     a resource ID
     *
     * @return true if a resource is in the list, otherwise false
     *
     * @pre list != null
     * @pre id > 0
     * @post $none
     */
    private boolean checkResource(Collection<Integer> list, int id) {
        boolean flag = false;
        if (list == null || id < 0) {
            return flag;
        }

        Integer obj = null;
        Iterator<Integer> it = list.iterator();

        // a loop to find the match the resource id in a list
        while ( it.hasNext() )
        {
            obj = it.next();
            if (obj.intValue() == id)
            {
                flag = true;
                break;
            }
        }

        return flag;
    }

    /**
     * shutdownEntity方法调用，CIS关闭表示仿真结束，通知其他实体
     * Tells all registered entities the end of simulation.
     *
     * @pre $none
     * @post $none
     */
    private void notifyAllEntity() {
        Log.printLine(super.getName() +
                ": Notify all CloudSim entities for shutting down.");

        signalShutdown(resList);
        signalShutdown(gisList);

        // reset the values
        resList.clear();
        gisList.clear();
    }

    /**
     * 向列表中各个实体发送END_OF_SIMULATION消息,该消息延迟时间为0
     * Sends a signal to all entity IDs mentioned in the given list.
     *
     * @param list  List storing entity IDs
     *
     * @pre list != null
     * @post $none
     */
    protected void signalShutdown(Collection<Integer> list) {
        // checks whether a list is empty or not
        if (list == null) {
            return;
        }

        Iterator<Integer> it = list.iterator();
        Integer obj = null;
        int id = 0;     // entity ID

        // Send END_OF_SIMULATION event to all entities in the list
        while (it.hasNext()) {
            obj = it.next();
            id = obj.intValue();
            super.send(id, 0L, CloudSimTags.END_OF_SIMULATION);
        }
    }

} // end class