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.vnd.document.service;
017
018 import java.util.List;
019
020 import org.kuali.kfs.vnd.businessobject.VendorAddress;
021 import org.kuali.kfs.vnd.businessobject.VendorContract;
022 import org.kuali.kfs.vnd.businessobject.VendorDetail;
023 import org.kuali.kfs.vnd.businessobject.VendorHeader;
024 import org.kuali.kfs.vnd.businessobject.VendorRoutingComparable;
025 import org.kuali.rice.kns.util.KualiDecimal;
026
027 public interface VendorService {
028
029 public void saveVendorHeader(VendorDetail vendorDetail);
030
031 /**
032 * get the vendor detail with the given vendor number
033 * @param vendorNumber the given vendor number
034 * @return the vendor detail with the given vendor number if the vendor exists, otherwise, return null
035 */
036 public VendorDetail getByVendorNumber(String vendorNumber);
037
038 public VendorDetail getVendorDetail(String vendorNumber);
039
040 public VendorDetail getVendorDetail(Integer headerId, Integer detailId);
041
042 /**
043 * Retrieves the VendorDetail which is the parent vendor with the given headerId. This is the method to use when working
044 * backward from a division vendor to its parent vendor. This method throws RuntimeExceptions if there are found to be no parent
045 * vendor or more than one parent vendor for the associated corporate structure.
046 *
047 * @param vendorHeaderGeneratedIdentifier The Header Id in Integer form
048 * @return The VendorDetail of the parent vendor associated with the corporate structure indicated by the given Header Id, or
049 * null if there are no vendors associated with it.
050 */
051 public VendorDetail getParentVendor(Integer vendorHeaderGeneratedIdentifier);
052
053 /**
054 * Retrieves the VendorDetail using its vendorDunsNumber.
055 * @param vendorDunsNumber the vendor's DUN number.
056 * @return
057 */
058 public VendorDetail getVendorByDunsNumber(String vendorDunsNumber);
059
060 /**
061 * Gets the apo limit for the given parameters using the following logic:<br>
062 * <br>
063 * First it checks to see if an existing {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} object exists for the
064 * associated parameters. If one exists and it is not excluded (see
065 * {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization#isVendorContractExcludeIndicator()}) this will return the value
066 * of {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization#getVendorContractPurchaseOrderLimitAmount()}.<br>
067 * <br>
068 * If an associated {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} object cannot be found then a valid
069 * {@link org.kuali.kfs.vnd.businessobject.VendorContract} object will be sought. If one is found this method will return the value of
070 * {@link org.kuali.kfs.vnd.businessobject.VendorContract#getOrganizationAutomaticPurchaseOrderLimit()}.<br>
071 * <br>
072 * If no valid {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} or
073 * {@link org.kuali.kfs.vnd.businessobject.VendorContract} objects can be found for the given parameters this method will return null.
074 *
075 * @param contractId id used to find {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} object and
076 * {@link org.kuali.kfs.vnd.businessobject.VendorContract} object
077 * @param chart chart code for use in finding {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} object
078 * @param org org code for use in finding {@link org.kuali.kfs.vnd.businessobject.VendorContractOrganization} object
079 * @return the automatic purchase order limit amount from the contract found using the parameters. If parameters do not find
080 * valid vendor contract objects then null is returned.
081 */
082 public KualiDecimal getApoLimitFromContract(Integer contractId, String chart, String org);
083
084 /**
085 * Finds the addresses for the given vendor and then calls the method to determine the default address from this list.
086 *
087 * @param vendorHeaderId Integer - Header ID of vendor.
088 * @param vendorDetailId Integer - Detail ID of vendor.
089 * @param addressType String - Address type of desired default.
090 * @param campus String - Campus of desired default.
091 * @return VendorAddress Desired default address; return null is possible if no defaults set.
092 */
093 public VendorAddress getVendorDefaultAddress(Integer vendorHeaderId, Integer vendorDetailId, String addressType, String campus);
094
095 /**
096 * Finds the default address for the given addressType and campus from the address list passed in based on the following logic:
097 * 1) The allDefaultAddress is defined by defaultAddressIndicator on VendorAddress. 2) If campus passed in is null, return
098 * allDefaultAddress if found. 3) If campus passed in is not null, look in campus lists of addresses to see if given campus is
099 * found for the given address type. If match found, return address. If no match found, return allDefaultAddress.
100 *
101 * @param addresses List of addresses for a vendor.
102 * @param addressType String - Address type of the desired default sought.
103 * @param campus String - Campus of the desired default sought.
104 * @return VendorAddress Desired default address; return null is possible if no defaults set.
105 */
106 public VendorAddress getVendorDefaultAddress(List<VendorAddress> addresses, String addressType, String campus);
107
108 /**
109 * Checks to see if a the Vendor Document associated with the given document ID should route to the route path branch in
110 * workflow where the document will stop for approvals.
111 *
112 * @param documentId
113 * @return true if the vendor should be take the approval patch... false if the vendor can be 'auto approved'
114 */
115 public boolean shouldVendorRouteForApproval(String documentId);
116
117 /**
118 * Compares lists which have an isEqualForRouting method by using that method. An Equals() method would be wrong for the purpose
119 * of comparing these because we want to compare only using certain specified attributes, which is what our isEqualForRouting
120 * methods will do.
121 *
122 * @param list_a A List which implements VendorRoutingComparable (specifies isEqualForRouting)
123 * @param list_b Another such list
124 * @return True if all the member objects in the given lists are equal (as far as routing is concerned) at the same locations in
125 * the lists.
126 */
127 public boolean equalMemberLists(List<? extends VendorRoutingComparable> list_a, List<? extends VendorRoutingComparable> list_b);
128
129 /**
130 * This method is the place to put the calls to equality checks that are needed when deciding whether to route a vendor for
131 * approval or directly to final status on the basis of what has changed. This method has been split out from
132 * shouldVendorRouteForApproval for the convenience of unit testing, but might be useful for other purposes.
133 *
134 * @param newVDtl A VendorDetail object representing the state of the proposed change
135 * @param newVHdr A VendorHeader object representing the state of the proposed change
136 * @param oldVDtl A VendorDetail object from before the change
137 * @param oldVHdr A VendorHeader object from before the change
138 * @return True if no route-significant change occurred
139 */
140 public boolean noRouteSignificantChangeOccurred(VendorDetail newVDtl, VendorHeader newVHdr, VendorDetail oldVDtl, VendorHeader oldVHdr);
141
142 /**
143 * Indicates whether the vendor identified by the given <code>vendorHeaderGeneratedIdentifier</code> is an employee of the
144 * institution. The vendor must have a valid tax id and it must be of type SSN (see
145 * {@link org.kuali.kfs.vnd.VendorConstants#TAX_TYPE_SSN}).
146 *
147 * @param vendorHeaderGeneratedIdentifier The Header Id in Integer form
148 * @return true if the vendor identified by the <code>vendorHeaderGeneratedIdentifier</code> given is an employee of the
149 * institution
150 */
151 public boolean isVendorInstitutionEmployee(Integer vendorHeaderGeneratedIdentifier);
152
153 /**
154 * Indicates whether the vendor identified by the given <code>vendorHeaderGeneratedIdentifier</code> is a non-resident alien
155 * by checking the value of {@link org.kuali.kfs.vnd.businessobject.VendorHeader#getVendorForeignIndicator()}.
156 *
157 * @param vendorHeaderGeneratedIdentifier The Header Id in Integer form
158 * @return true if the vendor identified by the <code>vendorHeaderGeneratedIdentifier</code> given is valid and is marked as a
159 * foreign vendor
160 */
161 public boolean isVendorForeign(Integer vendorHeaderGeneratedIdentifier);
162
163 /**
164 * Indicates whether the vendor identified by the given <code>vendorHeaderGeneratedIdentifier</code> is a subject payment vendor
165 * by checking the value of {@link org.kuali.kfs.vnd.businessobject.VendorHeader#getVendorTypeCode()} to see if it equals "SP".
166 *
167 * @param vendorHeaderGeneratedIdentifier The Header Id in Integer form
168 * @return true if the vendor identified by the <code>vendorHeaderGeneratedIdentifier</code> given is valid and has a vendor type code of "SP"
169 */
170 public boolean isSubjectPaymentVendor(Integer vendorHeaderGeneratedIdentifier);
171
172 /**
173 * Indicates whether the vendor identified by the given <code>vendorHeaderGeneratedIdentifier</code> is a revolving fund code vendor
174 * by checking the value of {@link org.kuali.kfs.vnd.businessobject.VendorHeader#getVendorTypeCode()} to see if it equals "RF".
175 *
176 * @param vendorHeaderGeneratedIdentifier The Header Id in Integer form
177 * @return true if the vendor identified by the <code>vendorHeaderGeneratedIdentifier</code> given is valid and has a vendor type code of "RF"
178 */
179 public boolean isRevolvingFundCodeVendor(Integer vendorHeaderGeneratedIdentifier);
180
181 /**
182 * This method retrieves the B2B Contract for the given Vendor (see method in VendorDao for criteria).
183 *
184 * @param vendorDetail Vendor info
185 * @param campus Campus
186 * @return VendorContract B2B Contract for given vendor
187 */
188 public VendorContract getVendorB2BContract(VendorDetail vendorDetail, String campus);
189
190 }