001    /*
002     * Copyright 2011 The Kuali Foundation.
003     * 
004     * Licensed under the Educational Community License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     * 
008     * http://www.opensource.org/licenses/ecl2.php
009     * 
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.kuali.kfs.module.bc.service;
017    
018    import org.kuali.kfs.module.bc.businessobject.BudgetConstructionPosition;
019    import org.kuali.kfs.module.bc.exception.BudgetPositionAlreadyExistsException;
020    
021    /**
022     * Provides methods to retrieve and populate budget construction position records.
023     */
024    public interface BudgetConstructionPositionService {
025    
026        /**
027         * Retrieves a new position record from an external system using <code>HumanResourcesPayrollService</code> then populates the
028         * record in the budget position table.
029         * 
030         * @param universityFiscalYear budget fiscal year for the position
031         * @param positionNumber position number for the record
032         * @exception BudgetPositionAlreadyExistsException thrown when position is already in the budget table
033         * @exception PositionLockNotObtainedException thrown when the position and associated funding locks could not be obtained
034         */
035        public void pullNewPositionFromExternal(Integer universityFiscalYear, String positionNumber) throws BudgetPositionAlreadyExistsException;
036    
037        /**
038         * Refreshes a position record from an external system using <code>HumanResourcesPayrollService</code> then updates the record
039         * in the budget position table.
040         * 
041         * @param universityFiscalYear budget fiscal year for the position
042         * @param positionNumber position number for the record
043         */
044        public void refreshPositionFromExternal(Integer universityFiscalYear, String positionNumber);
045    
046        /**
047         * retrieve a Budget Construction Position object by its primary key.
048         * 
049         * @param fiscalYear the given fiscal year
050         * @param positionNumber the given position number
051         * @return a Budget Construction Position object retrived by its primary key
052         */
053        public BudgetConstructionPosition getByPrimaryId(String fiscalYear, String positionNumber);
054    
055        /**
056         * determine whether the given position is budgetable (valid, active and budgeted)
057         * 
058         * @param budgetConstructionPosition the given position
059         * @return true if the given position is budgetable; otherwise, false
060         */
061        public boolean isBudgetablePosition(BudgetConstructionPosition budgetConstructionPosition);
062    }