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.gl.document.service;
017
018 import java.io.IOException;
019 import java.io.OutputStream;
020 import java.sql.Date;
021 import java.util.Collection;
022 import java.util.Iterator;
023 import java.util.List;
024
025 import org.kuali.kfs.gl.businessobject.CorrectionChangeGroup;
026 import org.kuali.kfs.gl.businessobject.OriginEntryFull;
027 import org.kuali.kfs.gl.document.GeneralLedgerCorrectionProcessDocument;
028 import org.kuali.kfs.gl.document.CorrectionDocumentUtils;
029 import org.kuali.kfs.gl.document.web.CorrectionDocumentEntryMetadata;
030 import org.kuali.rice.kns.web.ui.Column;
031
032 /**
033 * An interface declaring methods needed by the GLCP to function
034 */
035 public interface CorrectionDocumentService {
036 public final static String CORRECTION_TYPE_MANUAL = "M";
037 public final static String CORRECTION_TYPE_CRITERIA = "C";
038 public final static String CORRECTION_TYPE_REMOVE_GROUP_FROM_PROCESSING = "R";
039
040 public final static String SYSTEM_DATABASE = "D";
041 public final static String SYSTEM_UPLOAD = "U";
042
043 /**
044 * When passed into {@link #retrievePersistedInputOriginEntries(CorrectionDocument, int)} and
045 * {@link #retrievePersistedOutputOriginEntries(CorrectionDocument, int)} as the int parameter, this will signify that there is
046 * no abort threshold (i.e. the methods should return all of the persisted rows, regardless of number of rows.
047 */
048 public final static int UNLIMITED_ABORT_THRESHOLD = CorrectionDocumentUtils.RECORD_COUNT_FUNCTIONALITY_LIMIT_IS_UNLIMITED;
049
050 /**
051 * Returns a specific correction change group for a GLCP document
052 *
053 * @param docId the document id of a GLCP document
054 * @param i the number of the correction group within the document
055 * @return a CorrectionChangeGroup
056 */
057 public CorrectionChangeGroup findByDocumentNumberAndCorrectionChangeGroupNumber(String docId, int i);
058
059 /**
060 * Finds CollectionChange records associated with a given document id and correction change group
061 *
062 * @param docId the document id of a GLCP document
063 * @param i the number of the correction group within the document
064 * @return a List of qualifying CorrectionChange records
065 */
066 public List findByDocumentHeaderIdAndCorrectionGroupNumber(String docId, int i);
067
068 /**
069 * Finds Collection Criteria associated with the given GLCP document and group
070 *
071 * @param docId the document id of a GLCP document
072 * @param i the number of the correction group within the document
073 * @return a List of qualifying CorrectionCriteria
074 */
075 public List findByDocumentNumberAndCorrectionGroupNumber(String docId, int i);
076
077 /**
078 * Retrieves a correction document by the document id
079 *
080 * @param docId the document id of the GLCP to find
081 * @return a CorrectionDocument if found
082 */
083 public GeneralLedgerCorrectionProcessDocument findByCorrectionDocumentHeaderId(String docId);
084
085 /**
086 * Returns metadata to help render columns in the GLCP. Do not modify this list or the contents in this list.
087 *
088 * @param docId the document id of a GLCP document
089 * @return a List of Columns to render
090 */
091 public List<Column> getTableRenderColumnMetadata(String docId);
092
093 /**
094 * This method persists an Iterator of input origin entries for a document that is in the initiated or saved state
095 *
096 * @param document an initiated or saved document
097 * @param entries an Iterator of origin entries
098 */
099 public void persistInputOriginEntriesForInitiatedOrSavedDocument(GeneralLedgerCorrectionProcessDocument document, Iterator<OriginEntryFull> entries);
100
101 /**
102 * Removes input origin entries that were saved to the database associated with the given document
103 *
104 * @param document a GLCP document
105 */
106 public void removePersistedInputOriginEntries(GeneralLedgerCorrectionProcessDocument document);
107
108 /**
109 * Removes input origin entries that were saved to the database associated with the given document
110 *
111 * @param docId the document id of a GLCP document
112 */
113 public void removePersistedInputOriginEntries(String docId);
114
115 /**
116 * Retrieves input origin entries that have been persisted for this document
117 *
118 * @param document the document
119 * @param abortThreshold if the file exceeds this number of rows, then null is returned. {@link UNLIMITED_ABORT_THRESHOLD}
120 * signifies that there is no limit
121 * @return the list, or null if there are too many origin entries
122 * @throws RuntimeException several reasons, primarily relating to underlying persistence layer problems
123 */
124 public List<OriginEntryFull> retrievePersistedInputOriginEntries(GeneralLedgerCorrectionProcessDocument document, int abortThreshold);
125
126 /**
127 * Returns true if the system is storing input origin entries for this class. Note that this does not mean that there's at least
128 * one input origin entry record persisted for this document, but merely returns true if and only if the underlying persistence
129 * mechanism has a record of this document's origin entries. See the docs for the implementations of this method for more
130 * implementation specific details.
131 *
132 * @param document a GLCP document
133 * @return Returns true if system should store origin entries, false otherwise
134 */
135 public boolean areInputOriginEntriesPersisted(GeneralLedgerCorrectionProcessDocument document);
136
137 /**
138 * Writes out the persisted input origin entries in an {@link OutputStream} in a flat file format
139 *
140 * @param document a GLCP document
141 * @param out an open and ready output stream
142 * @throws IOException thrown if errors were encountered writing to the Stream
143 * @throws RuntimeException several reasons, including if the entries are not persisted
144 */
145 public void writePersistedInputOriginEntriesToStream(GeneralLedgerCorrectionProcessDocument document, OutputStream out) throws IOException;
146
147 /**
148 * This method persists an Iterator of input origin entries for a document that is in the initiated or saved state
149 *
150 * @param document an initiated or saved document
151 * @param entries an Iterator of OriginEntries to persist
152 */
153 public void persistOutputOriginEntriesForInitiatedOrSavedDocument(GeneralLedgerCorrectionProcessDocument document, Iterator<OriginEntryFull> entries);
154
155 /**
156 * Removes all output origin entries persisted in the database created by the given document
157 *
158 * @param document a GLCP document
159 */
160 public void removePersistedOutputOriginEntries(GeneralLedgerCorrectionProcessDocument document);
161
162 /**
163 * Removes all output origin entries persisted in the database created by the given document
164 *
165 * @param docId the document id of a GLCP document
166 */
167 public void removePersistedOutputOriginEntries(String docId);
168
169 /**
170 * Retrieves output origin entries that have been persisted for this document
171 *
172 * @param document the document
173 * @param abortThreshold if the file exceeds this number of rows, then null is returned. {@link UNLIMITED_ABORT_THRESHOLD}
174 * signifies that there is no limit
175 * @return the list, or null if there are too many origin entries
176 * @throws RuntimeException several reasons, primarily relating to underlying persistence layer problems
177 */
178 public List<OriginEntryFull> retrievePersistedOutputOriginEntries(GeneralLedgerCorrectionProcessDocument document, int abortThreshold);
179
180 /**
181 * Retrieves input origin entries that have been persisted for this document in an iterator. Implementations of this method may
182 * choose to implement this method in a way that consumes very little memory.
183 *
184 * @param document the document
185 * @return the iterator
186 * @throws RuntimeException several reasons, primarily relating to underlying persistence layer problems
187 */
188 public Iterator<OriginEntryFull> retrievePersistedInputOriginEntriesAsIterator(GeneralLedgerCorrectionProcessDocument document);
189
190 /**
191 * Retrieves output origin entries that have been persisted for this document in an iterator. Implementations of this method may
192 * choose to implement this method in a way that consumes very little memory.
193 *
194 * @param document the document
195 * @return the iterator
196 * @throws RuntimeException several reasons, primarily relating to underlying persistence layer problems
197 */
198 public Iterator<OriginEntryFull> retrievePersistedOutputOriginEntriesAsIterator(GeneralLedgerCorrectionProcessDocument document);
199
200 /**
201 * Returns true if the system is storing output origin entries for this class. Note that this does not mean that there's at
202 * least one output origin entry record persisted for this document, but merely returns true if and only if the underlying
203 * persistence mechanism has a record of this document's origin entries. See the docs for the implementations of this method for
204 * more implementation specific details.
205 *
206 * @param document a GLCP document to query
207 * @return true if origin entries are stored to the system, false otherwise
208 */
209 public boolean areOutputOriginEntriesPersisted(GeneralLedgerCorrectionProcessDocument document);
210
211 /**
212 * Writes out the persisted output origin entries in an {@link OutputStream} in a flat file format\
213 *
214 * @param document a GLCP document
215 * @param out axn open and ready output stream
216 * @throws IOException thrown if IOExceptions occurred in writing the persisted origin entries
217 * @throws RuntimeException several reasons, including if the entries are not persisted
218 */
219 public void writePersistedOutputOriginEntriesToStream(GeneralLedgerCorrectionProcessDocument document, OutputStream out) throws IOException;
220
221 /**
222 * Saves the input and output origin entry groups for a document prior to saving the document
223 *
224 * @param document a GLCP document
225 * @param correctionDocumentEntryMetadata metadata about this GLCP document
226 */
227 public void persistOriginEntryGroupsForDocumentSave(GeneralLedgerCorrectionProcessDocument document, CorrectionDocumentEntryMetadata correctionDocumentEntryMetadata);
228
229 /**
230 * Retrieves all of the documents that were finalized on a certain date
231 *
232 * @param date the date to find GLCP documents finalized on
233 * @return a collection of documents
234 */
235 public Collection<GeneralLedgerCorrectionProcessDocument> getCorrectionDocumentsFinalizedOn(Date date);
236
237 public String generateOutputOriginEntryFileName(String docId);
238
239 public String createOutputFileForProcessing(String docId, java.util.Date today);
240
241 public String getBatchFileDirectoryName();
242
243 public String getGlcpDirectoryName();
244
245 /**
246 * Generate a text report for the given correction document
247 *
248 * @param document GLCP document to report on
249 */
250 public void generateCorrectionReport(GeneralLedgerCorrectionProcessDocument document);
251
252 public void aggregateCorrectionDocumentReports(GeneralLedgerCorrectionProcessDocument document);
253
254 /**
255 * Finds any existing output files for the given document. Used to prevent double-processing.
256 *
257 * @param documentNumber
258 * @return
259 */
260 public String[] findExistingCorrectionOutputFilesForDocument( String documentNumber );
261 }