Программный интерфейс
Прецедент – спецификация последовательностей действий (варианты последовательностей и ошибочные последовательности), которые может осуществлять система, подсистема или класс, взаимодействуя с внешними акторами.
Прецеденты заполняют разрыв между конечным пользователем и требованиями к системе. Они также позволяют наметить путь от функциональных требований к реализации.
Прецедент описывает некоторый целостный фрагмент поведения системы, не вдаваясь при этом в особенности внутренней структуры субъекта. Определение прецедента содержит все свойственные ему виды поведения: основную последовательность, различные варианты стандартного поведения и различные исключительные ситуации с указанием ответной реакции на них. С точки зрения пользователя некоторые из видов поведения выглядят как ошибочные. Однако для системы ошибочная ситуация является одним из вариантов поведения, который должен быть описан и обработан.
На рисунке 1 приведена диаграмма прецендентов, которая демонстрирует доступные пользователю возможности.
Рисунок 1 – Диаграмма прецендента.
Прецедент остается текстовым описанием и поэтому допускает различные интерпретации. Для того чтобы выразить прецедент более точными, техническими средствами, используются диаграммы последовательностей. Для этого прецедент изображается как взаимодействие между исполнителем и системой. На рисунке 2 приведена диаграмма последовательностей.
Рисунок 2 – Диаграмма последовательностей
Разработанный проект включает в себя шесть классов, содержащих константы и методы для обработки информации, в том числе один контроллер. Классы распределены по пакетам для удобства использования.
Начнём рассмотрение с пакета by.gsu.asoi5.beans. В данном пакете располагается разработанныеbean-класс Contract. Данный класс представляет собой модель всех поддерживаемых системой договоров и предназначен для взаимодействия с формой, в которую сотрудники будут вводить свои данные. Если быть точнее, то в объект данного класса будут заноситься все данные, введённые пользователем в форму, располагающуюся на странице с интересующим договором. А затем такой объект будет передаваться другим методам, которые, в свою очередь, будут проводить над этим объектом необходимые действия. Так как этот класс является одним из самых главных в разрабатываемой системе, то стоит детально рассмотреть его поля и некоторые из методов.
String FIO– поле для хранения фамилии, имя, отчества пользователя, заполняющего договор.
String dateStart– дата начала работы сотрудника.
String dateEnd– дата окончания работы.
String departmentAndFacul– название кафедры и факультета, на котором работает сотрудник.
String numberOfHours– количество часов.
String passportSer– серия паспорта.
String passportNumber– номер паспорта.
String passportDate– дата выдачи паспорта.
String passportPrivateNum– личный номер паспорта.
String homeAdds– домашний адрес сотрудника.
String insuranceNum– страховой номер.
String phoneWorkNum– номер рабочего телефона.
String phoneHomeNum– номер домашнего телефона.
String phoneMobNum– номер мобильного телефона.
String work– место основной работы.
String post– должность сотрудника.
String degree – научная степень.
String academicTitle– учёное звание.
String pensioner– орган, выплачивающий пенсию, если заполняющий договор сотрудник пенсионер или получает пенсию, например, по инвалидности.
String organPass– орган, выдавший паспорт.
String citizen– поле хранит то же значение, что и полеFIO, но необходимо из-за того, что для данных значений в файле отводится разное количество места. Поэтому для более корректного выравнивания в выходном файле и было введено данное поле.
Также данный класс содержит два конструктора:
public Contract() {super();}– конструктор по умолчанию.
public Contract(String fIO, String dateStart, String dateEnd,String departmentAndFacul, String numberOfHours, String passportSer,String passportNumber, String passportDate,String passportPrivateNum, String homeAdds, String insuranceNum,String phoneWorkNum, String phoneHomeNum, String phoneMobNum,String work, String post, String degree, String academicTitle,String pensioner, String organPass, String citizen) {…} – конструктор с полями, который не только создаёт новый объект типа Contract, но и заполняет его значениями, указанными в качестве параметров конструктора.
А также для каждого поля и созданы методы «получения» и «установки», перечислять которые нет смысла, так как они все однообразные, поэтому просто приведу пример на основании поля FIO:
public String getFIO() {return FIO;}– данный метод возвращает ФИО сотрудника.
public void setFIO(String FIO) {this.FIO = FIO;}– метод устанавливает ФИО сотрудника, получаемое в качестве параметра.
Стоит отметить, что все поля имеют тип Stringдля того, чтобы затем не производить преобразование типов при выравнивании значений.
Следующий класс, который мы рассмотрим, находится в пакете by.gsu.asoi5.filters– класс SetCharacterEncodingFilter. Так как использование разрабатываемой системы будет осуществляться русскоговорящими пользователями, то необходимо, чтобы система понимала русский язык. Для этого и предназначен данный класс. А так как он носит только служебное назначение, и никак не влияет на принцип функционирования самой системы, то его рассмотрение не представляет никакого интереса в рамках данного проекта.
В пакете by.gsu.asoi5.serviceнаходится четыре класса, которые обеспечивают работу с шаблонами: Constants, Spaces, SearchReplace, TransformDate. Каждый из данных классов имеет своё назначение, но стоит отметить, что основную работу с шаблонами обеспечивает последний из перечисленных классов. Рассмотрим каждый из данных классов по отдельности.
Начнём рассмотрение с класса Constants. В данный класс было решено вынести все используемые в программе константы. В качестве констант, же, было решено использовать все значения, которые, как предполагается, могут меняться чаще других. Поэтому разумно было вынести их в отдельный класс, что существенно упрощает процесс изменения какого-нибудь параметра, например, «ключа» для домашнего адреса сотрудника. Достаточно просто изменить требуемое значение в данном классе, вместо того, чтобы искать заменяемое значение во всех классах. Это не только упрощает процесс сопровождения программы, но и уменьшает вероятность возникновения ошибок, так как существует вероятность, что с первого раза будут заменены не все значения. Так каждому полю класса Contract соответствует константа, хранящая значение соответствующее данному полю «ключа», например: public static final String CITIZEN= "citizen".
Также было решено использовать следующие константы:
public static final String EXTRABUD_ORDER = "/БЛАНК ДОГОВОРА внебюджет"– название входного файла договора за счёт внебюджетных средств.
public static final String EXTRABUD_OUTPUT_FILE = "/ExtraBudContract.rtf"– название заполненного договора за счёт внебюджетных средств.
public static final String BUD_ORDER = "/БЛАНК ДОГОВОРА госбюджет 10-11"– название шаблона договора за счёт средств республиканского бюджета.
public static final String BUD_OUTPUT_FILE = "/BudgetContract.rtf"– выходной договор за счёт средств республиканского бюджета.
public static final String IPK_ORDER = "/dogovor-kucherov-2011"– название шаблона договора, который заключается с институтом повышения квалификации.
public static final String IPK_OUTPUT_FILE = "/IPKContract.rtf"– название заполненного договора с институтом повышения квалификации.
public static final String AKT_ORDER = "/АКТ о выполн пед раб"– название входного документа для акта о выполнении педагогической работы за счёт средств республиканского бюджета.
public static final String AKT_OUTPUT_FILE = "/AKTContract.rtf"– название заполненного акта о выполнении педагогической работы за счёт бюджета.
public static final String AKT_PRIV_ORDER = "/АКТ о выполн пед раб1" – название шаблона акта о выполнении педагогической работы за счёт средств заказчика.
public static final String AKT_PRIV_OUTPUT_FILE = "/AKTPrivContract.rtf"– заполненный акт о выполнении педагогической работы за счёт средств заказчика.
Также в пакете by.gsu.asoi5.serviceнаходится, как было сказано выше, класс TransformDate. Который пока разрабатываемой системой не используется, так как пока, некритично преобразовывать дату из вида «01.01.2012» в «1 января 2012». Но так как это может понадобиться в любой момент, то было решено разработать данный класс. Этот класс содержит только один метод:public String convertMonth(String date), который принимает в качестве параметра дату, затем из переданной даты метод извлекает месяц, после чего по номеру месяца ищется его название на русском языке. И это найденное название месяца передаётся методу, вызвавшему данный метод.
Класс Spaces, возможно, следовало расположить в одном пакете с классом Contract, так как данный класс имеет практически тоже назначение. Классы имеют одинаковое название полей, различия заключаются лишь в том, что все поля класса Spaces имеют тип double, в то время как все поля класса Contract – тип String. Данный класс используется для создания объекта, хранящего расстояние, выраженное в числе пробелов, которое отведено каждому полю в шаблоне заполняемого договора. Затем такой объект используется другим методом для выравнивания в выходном файле. Об этом чуть ниже.
Наибольший интерес представляет класс SearchReplace, который осуществляет практически весь функционал разрабатываемой системы, поэтому рассмотрим каждый из его метод подробно. Как можно понять из названия класс что-то ищет и заменяет.
Для создания объекта класса SearchReplaceсоздан конструктор по умолчанию без полей:
public SearchReplace() {
super();
}
Следующий метод, который мы рассмотрим это метод public void searchAndReplace(String inputFile, String outputFile, Contract contract, String fileWithSPace). Как видно метод получает 4 параметра:
String inputFile– путь к исходному файлу шаблона, который соответствует выбранному пользователем договору. Именно этот файл затем заполняется программой.
String outputFile– имя файла заполненного договор, который передаётся пользователю, заполняющему форму. Также данная переменная содержит путь, который указывает, где заполненный файл хранится на сервер. И именно это полное имя файла используется для передачи договора пользователю.
Contract contract – объект типа Contract. Данный объект создаётся на основании введённых в форму пользователем данных и служит для их хранения.
String fileWithSPace– путь к вспомогательному файлу, который хранит размер места, выделяемого в исходном файле для конкретного поля. Такой размер в файле хранится в виде числа пробелов, которое соответствует отведённому пространству.
Данный метод заменяет в исходном файле ключевые слова на соответствующие им пользовательские значения и формирует выходной файл. Первоначально метод создаёт две переменных типа BufferedReader, одна из которых соответствует входному файлу, а вторая – выходному. Затем метод поочерёдно считывает входной файл по строкам и ищет в каждой строке ключевые слова. Если он находит такое слово, то он заменяет его необходимым значением и продолжает поиск дальше. После того, как поиск в текущей строке завершён, эта строка записывается в выходной файл, а новая строка считывается из входного файла. И так до тех пор, пока не будет прочитан весь файл. Стоит отметить, что данный метод заменяет ключевое слово не просто на значение, введённое пользователем в форму, а на несколько изменённое значение. Эти изменения проводит метод, описанный в следующем абзаце.
Для того чтобы выходной файл смотрелся красиво: чтобы каждое значение находилось на своём месте, и подчёркивание продолжалось до нужной позиции, предназначен метод public Contract alignContract (Contract contract, Spaces space). Данный метод получает в качестве параметра объект типа Contract и объект типа Spaces. Затем при помощи «сеттеров» данный метод устанавливает объекту типа Контракт новые значения, которые получаются в результате выполнения методаaddSpaceToPhrase, описанного ниже.
Метод public String addSpaceToPhrase (String phrase, double lengthOfSpace), как можно судить из названия добавляет пробелы к фразе. Метод получает два параметра:
String phrase– стринговая переменная, которая хранит какое-то из введённых пользователем значений.
double lengthOfSpace– переменная, хранящая число пробелов, которые соответствуют пространству в договоре, которое отводится для конкретного значения в файле шаблона.
Затем данный метод отнимает от числа пробелов, которые отводятся для значения, количество пробелов, которые соответствуют пространству, которое занимает введённое пользователем значение. И при необходимости добавляет в конец фразы недостающее число пробелов, а также символ точки, так как если не указать точку, или какой-нибудь другой символ после пробелов, то в выходном файле пробелы не будут подчёркнуты. А, следовательно, не будет видно выполненного выравнивания.
Преобразование фразы в число пробелов осуществляет метод public double CalcSpace (String phrase), который получает в качестве параметра фразу, которую нужно перевести в пробелы. Затем метод, на основании составленной мною статистики, которая указывает, какому числу пробелов соответствует каждая буква русского алфавита (как строчная, так и прописная) или цифра, переводит фразу в число пробелов, постепенно перебирая все символы во фразе. Так как пользователь, может указать при вводе не только буквы русского алфавита (по ошибке или специально), то в таких случаях каждый «неизвестный» символ считается равным трём пробелам, так как тройка является, примерно, средним значением числа пробелов для заглавных букв. То есть в таком случае, скорее в выходном файле не хватит нескольких пробелов, чем будет с излишком. А так как первый вариант является предпочтительным, то было решено его использовать. Как развитие системы можно подсчитать статистику и для других символов, но это несколько ухудшит быстродействие разрабатываемого проекта, так как придётся проводить большее число проверок для каждого символа.
Также в данном классе описан ещё один метод: public Spaces readFileWithSpaces (String fileName). Который вызывается в методеsearchAndReplace(). В качестве параметра этот метод получает абсолютное имя вспомогательного файла, который содержит число пробелов для выравнивания в выходном файле. Такой файл имеет следующую структуру: имя поля, количество пробелов. Данный метод построчно считывает строку из текстового файла, обрезает пробелы от строки, если таковые имеются. Затем проверяет, равно ли имя поля, указанное в файле какой-нибудь из констант, предназначенных для хранения ключевых значений. Если имя поля совпадает с константой, то указанное количество пробелов присваивается соответствующему полю объекта классаSpaces.
Для лучшего понимания того, как происходит управление системой, на рисунке 3 приведена диаграмма классов, на которой представлены связи класса-контроллера.
Рисунок 3 – Диаграмма классов
За управление системой и вызов нужных методов отвечает сервлет MainController. Данный класс содержит два метода с аннотацией@Autowired, которая необходима для того, чтобы эти метода выполнялись сразу при запуске приложения. Эти методы имеют следующее назначение:
public void init(ServletConfig config)– инициализирует «конфиг» сервлета для того, чтобы затем можно было указывать путь к файлам договоров относительно контекста приложения, а, не указывая абсолютный путь в системе, что привело бы к необходимости каждый раз изменять его при изменении местоположения файлов.
public void setM()– метод устанавливает в модель объект типаContract, что необходимо для его использования в форме, в которую пользователи вводят свои данные.
Также в сервлете описано два метода для навигации по приложению:
public ModelAndView showMain (ModelMap model)– метод, который устанавливает в модель объект типа «Контракт» и перенаправляет пользователя на главную страницу.
public String navigation (ModelMap model, @RequestParam("link") String link) – метод необходимый для навигации по приложению. В качестве параметра метод получает название страницы, на которую нужно перенаправить пользователя, устанавливает в модель объект и перенаправляет пользователя на запрашиваемую им страницу.
Следующие методы очень похожи по назначению и отвечают за заполнение договоров. Отличия между ними заключается лишь в том, какие файлы используют данные методы для своей работы. Вот список этих методов:
public void fillextraBudgetary (@ModelAttribute("contract") Contract contract, HttpServletRequest request, HttpServletResponse response) – метод для заполнения договора за счёт внебюджетных средств.
public void fillBudget (@ModelAttribute("contract") Contract contract, HttpServletRequest request, HttpServletResponse response)– метод для заполнения договора за счёт средств республиканского бюджета.
public void fillIPK (@ModelAttribute("contract") Contract contract, HttpServletRequest request, HttpServletResponse response)– метод для заполнения договора с институтом повышения квалификации.
public void fillAct (@ModelAttribute("contract") Contract contract, HttpServletRequest request, HttpServletResponse response)– метод для заполнения акта на выполнение педагогической работы за счёт средств бюджета.
public void fillActPriv (@ModelAttribute("contract") Contract contract, HttpServletRequest request, HttpServletResponse response) – заполнение акта за счёт средств заказчика.
Выше несколько раз упоминалось о создании шаблона и о вспомогательном файле с пробелами. Стоит отметить, что этим занимается макрос, написанный на VBA. Процесс его выполнения можно представить следующим образом:
Выводим пользователю сообщение о начале работы макроса.
Создаём текстовый файл с таким же именем, что и входной «вордовский» файл.
Так как требования к заполнению акта и договора несколько различные (в акте меньше полей, и некоторые поля несколько отличаются процессом формирования), то макросу нужно определить: создаёт он шаблон договора или акта. Для этого он ищет в документе строку «Исполнитель, в лице», которая имеется только в актах. Если такая строчка найдено, то работаем с актом, если же нет – с договором.
Ищем по некоторым уникальным словосочетаниям позицию, в которую нужно будет вставить текст.
Определяем, сколько места выделено для данного значения.
Заменяем отведённое под значение место на ключевое значение.
Записываем в текстовый файл имя поля и число пробелов.
Ищем следующее ключевое словосочетание.
Закрываем текстовый файл.
Выдаём пользователю сообщение о том, что создание шаблона завершено.