source: xssim/src/schedframe/scheduling/plugin/grid/ReservationManager.java @ 104

package schedframe.scheduling.plugin.grid;

import java.util.List;


import schedframe.exceptions.ModuleException;
import schedframe.exceptions.NotAuthorizedException;
import schedframe.exceptions.PermanentException;
import schedframe.exceptions.ReservationException;
import schedframe.resources.ResourceProvider;
import schedframe.scheduling.AbstractResourceRequirements;
import schedframe.scheduling.AbstractTimeRequirements;
import schedframe.scheduling.Offer;
import schedframe.scheduling.Reservation;
import schedframe.scheduling.ResourceUsage;
import schedframe.scheduling.SecurityContextInterface;
import schedframe.scheduling.TimeResourceAllocation;


/**
 * This interface contains functionality needed to negotiate, create, and manage resource reservations
 * @author Ariel
 * @author Marcin Krystek
 *
 */
public interface ReservationManager extends Module {
           
        
        /* Methods related to getting information about available resources and negotiating offers of resource providers */

        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Gets offers from all resource providers according to the time and resource requirements
         * @param timeRequirements
         * @param resourceRequirements
         * @return list of offers from all resource providers
         * @throws 
         */
        public List<Offer> getOffer(AbstractTimeRequirements<?> timeRequirements, 
                                                                 AbstractResourceRequirements<?> resourceRequirements,
                                                                 SecurityContextInterface securityContext) 
                                                                 throws ReservationException, NotAuthorizedException, PermanentException;
        
        
        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Gets offer from a given resource provider according to the time and resource requirements
         * @param provider description of the specific provider
         * @param timeRequirements time constraints
         * @param resourceRequirements resource requirements
         * @return Offer proposed by provider
         * @throws
         */
        public Offer getOffer(ResourceProvider provider, 
                                                        AbstractTimeRequirements<?> timeRequirements, 
                                                        AbstractResourceRequirements<?> resourceRequirements,
                                                         SecurityContextInterface securityContext) 
                                                        throws ReservationException, NotAuthorizedException, PermanentException;
                
        
        /* Methods related to managing reservations */


        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Creates reservation according to the time and resource requirements for all providers
         * @param timeRequirements time constraints
         * @param resourceRequirements resource requirements
         * @return Depends on the implementation of local system, this may be list of
         * final reservations which are ready to be used or list of initial reservations 
         * which must by committed to reach final status.  
         * @throws
         */
        public List<Reservation> createReservation(AbstractTimeRequirements<?> timeRequirements,
                                                                                                AbstractResourceRequirements<?> resourceRequirements,
                                                                                                 SecurityContextInterface securityContext)
                                                                                                throws ReservationException, NotAuthorizedException, PermanentException;

        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Creates reservation according to the time and resource requirements
         * only for given resource provider
         * @param provider
         * @param timeRequirements time constraints
         * @param resourceRequirements resource requirements
         * @return Depends on the implementation of local system, this may be
         * final reservation which is ready to be used or initial reservation 
         * which must by committed to reach final status.  
         * @throws
         */
        public Reservation createReservation(ResourceProvider provider,
                                                                                AbstractTimeRequirements<?> timeRequirements,
                                                                                AbstractResourceRequirements<?> resourceRequirements,
                                                                                List<String> hostCandidates,
                                                                                SecurityContextInterface securityContext)
                                                                                throws ReservationException, NotAuthorizedException, PermanentException;
        
        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Create reservation according to the resource usage description. Resource usage may contain
         * more then one time interval, so for each time interval different reservation must be created.
         * 
         * @param resourceUsage description of resource units which should be reserved
         * The Offer returned by getOffers() method may be used as an argument.
         * @return Depends on implementation of local system, list of reservations may contain final reservations 
         * which are ready to be used or initial reservations which must by committed to reach final status.
         * @throws
         */
        public List<Reservation> createReservation(ResourceUsage resourceUsage,
                                                                                        SecurityContextInterface securityContext) 
                                                                                throws ReservationException, NotAuthorizedException, PermanentException;
        
        
        /**
         * Requests a provider to commit a reservation.
         * @param reservation
         * @return reservation if the reservation has been accepted
         * @throws NotAuthorizedException TODO
         * @throws PermanentException TODO
         * @throws Exception if the reservation can not be committed. The exception should
         * explain detail cause of commit failure.
         */
        public Reservation commitReservation(Reservation reservation,
                                                                                SecurityContextInterface securityContext) 
                                                                                throws ReservationException, NotAuthorizedException, PermanentException;

        /**
         * Requests a provider to commit a reservation for a part of initially reserved resources.
         * @param reservation - initial reservation
         * @param resourceUsage - resources and time interval. This express modification of the 
         * reservation which must be performed before reservation commit.
         * @return reservation if the reservation has been accepted by a provider
         * @throws NotAuthorizedException TODO
         * @throws PermanentException TODO
         * @throws Execption if the reservation can not be committed. The exception should
         * explain detail cause of commit failure.
         */
        public Reservation commitReservation(Reservation reservation, 
                                                                                TimeResourceAllocation resourceUsage,
                                                                                 SecurityContextInterface securityContext)
                                                                                throws ReservationException, NotAuthorizedException, PermanentException;
          
        /**
         * Requests a provider to modify a reservation
         * @param reservation
         * @param resourceUsage - resource and time interval to be reserved. This express 
         * expected modifications of the reserved resource.
         * @throws NotAuthorizedException TODO
         * @throws PermanentException TODO
         * @throws Exception if modification of the reservation was not possible. The exception
         * should describe detail cause of the modification failure.
         */
        public void modifyReservation(Reservation reservation, 
                                                                TimeResourceAllocation resourceUsage,
                                                                 SecurityContextInterface securityContext)
                                                                throws ReservationException, NotAuthorizedException, PermanentException;

        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Cancels reservation
         * @param provider - provider which holds the reservation
         * @param reservID - reservation identifier 
         * @throws
         */
        public void cancelReservation(Reservation reservation,
                                                                SecurityContextInterface securityContext) 
                                                                throws ReservationException, NotAuthorizedException, PermanentException;

        /**
         * @throws PermanentException TODO
         * @throws NotAuthorizedException TODO
         * Returns status of reservation
         * @param reservation 
         * @return a reservation status ({@link schedframe.implementation.Reservation})
         * @throws
         */
        public int checkStatus(Reservation reservation,
                                                        SecurityContextInterface securityContext)
                                                throws ReservationException, NotAuthorizedException, PermanentException;
        
        /**
         * Verifies if this reservation manager can accomplish its functionality
         * with resource provider.
         * @param provider to be verified
         * @return true if reservation manager support this provider, false otherwise  
         */
        public boolean supportProvider(ResourceProvider provider) throws ModuleException;
        
}