Ръководство на потребителя

 

Стартиране на приложението

Графичният интерфейс за извличане, търсене, филтриране и записване в XML формат на метаданни (анотации) от Java байт код може да бъде стартиран като стандартно Java приложение. Неговият главен (main) клас е client.mainframe.AnnotationToolGUI, но за улеснение стартирането може да се извърши чрез изпълнение на специално създаден за целта скрипт startAnnTool.bat, в който предварително трябва да се зададе пътя до виртуалната машина, която ще бъде използвана (JAVA_HOME). В противен случай, този път ще бъде взет от системната променлива със същото име.

След стартиране на приложението се отваря неговият главен прозорец (main frame):

Фигура 1: Главен прозорец на приложението

 

Създаване на проект

След като приложението е стартирано е необходимо да бъде създаден или зареден проект. Проектът съдържа информацията за входните файловете (jar, war, directory, class files), от чийто класове е заинтересован потребителя. След записването му, информация се съхранява под формата на XML файл.

 

Създаването на нов проект се осъществява чрез диалога New Project. Той може да бъде отворен чрез менюто File>New Project, чрез използването на бърза комбинация от клавиши CNTRL-N или чрез бутона :

 

Фигура 2: Диалогов прозорец за създаване на проект

 

След като диалога бъде отворен е необходимо да бъдат попълнени следните параметри (полета):

Project Name – името на проекта

Project Directory – директорията, в която ще бъде записан проекта.

Content – входно множество от файлове, директории или архиви, чието съдържание ще бъде анализирано.

След попълване на необходимата информация за създаване на проектa e необходимо той да бъде съхранен. Това става чрез бутона Apply. Ако всички попълнени параметри отговарят на изискванията (името на файла не трябва да съдържа недопустими символи; подадените файлове или директории, които трябва да бъдат обработени трябва да са сред допустимото множество – jar, war и т.н.), то за новосъздадения проект се генерира изходен файл с разширение .amp.

За връщане към основния прозорец се натиска бутона Cancel.

 

Модифициране на проект

Характеристиките на вече създадения проект могат да бъдат прегледани и евентуално променени чрез диалога Project Properties. След като проектът бъде избран в Projects View, диалогът може да бъде отворен чрез контекстното меню, което се появява при натискане на десен бутон на мишката, чрез менюто View>Project Properties, чрез използването на бърза комбинация от клавиши CNTRL-P или чрез бутона :

 

 

Фигура 3: Диалогов прозорец за модификация на проект

 

Може да бъде подменен всеки един от компoнентите идентифициращи проекта, в това число и входното множество от файлове чрез бутоните Add и Remove.

 

Projects View – визуализация на съдържанието на заредените проекти

Успешно заредените проекти се визуализират в дървото намиращо се в лявата част на основния прозорец на приложението. Всеки един закачен проект има за родител възела “Projects” и представя йерархичната структура на файловете от зададения content, като за корен служи името на проекта, а всяко листо е име на клас файл съдържащ се в него.

Цялостната структурата на всеки клас може да бъде разгледана като се кликне два пъти с мишката върху съответния клас възел (листо).

За всеки един от възлите на дървото са закачени контекстни менюта, които предоставят определени възможности в зависимост от типа на възела, от който се визуализира съответното меню, като възможността за търсене на анотации и записване на метаданните в XML формат притежава всеки един възел:

Фигура 4: Projects View

 

Class View – визуализация на съдържанието на клас файл

В дясната част на основния прозорец се визуализира йерархичното представяне на клас структурата във вид на дърво. За корен на дървото служи името на класа. Негови наследници са всичките му елементи – методи, конструктори, полета. Към всеки от тези основни възли, както и към параметрите на методите или конструкторите, е закачен списък съдържащ прикрепените към тях анотации:

 

 

 

 

 

 

 

Фигура 5: Class View

 

Find Annotations – търсене на анотации по определени критерии

Търсене на анотации в определен възел от Projects View може да бъде стартирано чрез контекстното меню, чрез бърз клавиш CTRL-F или бутон , след като възела бъде избран. Ако в конкретния възел и неговите наследници не се съдържат анотации, то системата уведомява за това. В противен случай, се визуализира диалога Find Annotations за търсене на анотации по зададени критерии (виж. Фигура 6.1).

 

В горната част на този диалог се визуализират името на проекта и content файла,  в който ще бъде осъществено търсено. Те служат за информация и отговарят на пътя до възела, от който е извикан диалоговия прозорец. Ако този възел е корена на дървото, то търсенето ще бъде осъществено във всички проекти. Списъкът с наличните пакети в избраните проект и content дава възможност търсенето да бъде ограничено до определен пакет (намиращ се в съответните проект и content). Списъкът с пакетите е неактивен, ако текущия възел, от който е стартиран диалоговия прозорец е пакетен възел. Тогава търсенето ще бъде точно в този пакет:

Фигура 6.1: Диалогов прозорец Find Annotations

 

В секцията Create Annotation Filter се съставят критериите за търсене, наречени филтър. Всеки филтър съдържа информация за тип на търсене, целева анотация и ниво на търсене. Целевата анотация може да бъде специфицирана от списъка с наличните анотации. Ако от списъка бъде избран *, то всички налични анотации в списъка стават целеви. Типа на търсене дефинира филтъра като позитивен и негативен, което определя наличието или отсъствието в изходното множество, на класа съдържащ целевата анотация от филтъра. Нивото на търсене редуцира изходното множество от класове до такива, в които целевата анотация  е прикрепена към елементи на тези класове от съответното ниво.

 

Пример 1:

Параметри:

Позитивен (Отрицателен) филтър

Цeлева анотация – javax.ejb.EJB

Ниво на търсене – метод, поле

В резултат, ще бъдат визуализирани всички класове, в които  цeлевата анотация – javax.ejb.EJB е (не е) прикрепена към метод(и) и/или поле(та) на тези класове.

След като даден филтър бъде изграден може да бъде добавен чрез бутона Add To Filter към общото множество от филтри – главен филтър. Ако даден филтър се сметне за неуместен може да бъде изваден от главния филтър (наличното множество от филтри). Това става като бъде маркиран и след това отстранен с бутона Remove From Filter. Заявката за търсене се образува от текущото сформирано множество от филтри в главния филтър, като се натисне бутона Search.

 

 

Фигура 6.2: Диалогов прозорец Find Annotations с добавени филтри

 

Search View – визуализация на резултата от търсенето

Списъкът с намереното множество от класове отговарящи на критериите на търсенето се визуализира в долната част на главния прозорец. Като за всеки нов резултат от търсене се отваря отделен Search View таб. Резултатното множество се представя във вид на дърво, разделено по нивата на търсене зададени във филтъра. Възел представящ дадено ниво, съдържа в себе си само класовете имащи анотации прикрепени към елементите им от съответното ниво (виж. Фигура 7.1).

 

Пример 2: Ако използваме горния пример (Пример 1), то на ниво methods ще се съдържат само класовете, които съдържат (не съдържат) целевата анотация - javax.ejb.EJB, която е прикрепена, към който и да е от техните методи:

 

Фигура 7.1: Search View

Структурата на всеки един изходен клас файл от резултантното множество може да бъде разгледана във вече споменатото Class View дърво. В допълнение, след визуализация в Class View, пътят до намерените анотации, в резултат на търсенето, се оцветява в червено, за да могат да бъдат открити по-лесно анотираните с тях елементи на класа:

 

Фигура 7.2: Search View – визуализирана информация за клас

 

Диалогов прозорец за запис на метаданните в XML формат

Метаданните за класовете, които се съдържат пряко или косвено в произволен възел на Projects View или Search View, могат да бъдат записани като XML файл. Това може да бъде направено чрез контекстното меню, чрез бърз клавиш CTRL-E или бутон , след като възела бъде избран. За целта се отваря диалогов прозорец Export to XML:

 

Фигура 8: Диалогов прозорец Export to XML

 

Метаданните се записват в специфицирания XML файл, като се използва XSD схемата по подразбиране – ./res/amp.xsd.