PROJECT: Recruit Me

Overview

Recruit Me is a Java Desktop GUI application that is specifically designed for a recruiting agency for their processes about the candidates in their storage.

Summary of contributions

  • Major enhancement: added filtering command

    • What it does:

      • Filters the persons according to their every single aspect (Name, Phone, Email, Skills, …​)

      • Can manage multiple filtering at the same time and also the filter can be cleared in any time the user wants.

      • Filtering command has 4 different branches in itself: AND, OR, REVERSE, CLEAR (For detailed explanation, please read filtering part in UserGuide).

    • Justification: This feature improves the usability of the product significantly, because it can eliminate all the candidates that are not fitting for the wanted job positions. Makes classification and searching easier.

    • Highlights: This new feature affects all the commands already implemented and all other commands that will be implemented in the future. Thus, the interaction of this command with other commands are strongly investigated and minor changes for other commands are also made to make the other commands compatible with filtering.

    • Related Pull Requests for This Feature:

  • Minor enhancement:

    • added CV representation for selected persons. Shows the matching CV for selected person, if there is an available CV in the storage for that person

    • Some minor changes are made for the methods in AddressBook, ModelManager and VersionedAddressBook classes that AddCommand, DeleteCommand and EditCommand uses for the compatibility with filtering process.

    • Fixed almost all failing system tests / GUI related tests / Edit Command tests in every update process of the process:

    • Travis Checkstyle errors are fixed mostly by me:

    • Coveralls and Codacy is implemented for the repository:

Contributions to the User Guide:

  • About multiple person addition (planned for v2.0) a new section is added.

  • Filtering process is added to the User guide as a new section: UserGuide → Features → Filtering Recruit Me: filter

  • For the newly implemented CV showing process, a section is added (Not linked below, you can check from the User Guide): UserGuide → Features → Showing and Updating the CV for a Person

  • Updated Add Command / List Command / Select Command Sections.

Filtering Recruit Me: filter

  • It filters the current applicant pool regarding the existing entities of every single person (name, phone, email, address, gpa, education (school), degree level, position, endorsement count or skills).

  • Format: filter or/and [name<NAME>name] [phone<PHONE>phone] [email<EMAIL>email] [gpa<GPA>gpa] [edu<EDUCATION>edu] [deg<DEGREE-LEVEL>deg] [addr<ADDRESS>addr] [skill<SKILL1, SKILL2, …​ >skill][pos<POSITION1, POSITION2, …​ >pos] [end<ENDORSEMENT>end]

For every field, using < or > can cause false results. Please do not use them in filtering criterion texts. All the fields are optional but at least one field should be used.

Definition of Some Keywords for the Filter Guide:

  • Prefix: basically the beginning part of every field in the command e.g. name< for NAME field, deg< for DEGREE-LEVEL.

  • Reverse Prefix: the ending part of every field in the command e.g. >name for NAME field, >deg for DEGREE-LEVEL.

  • Condition: The text between every Prefix and Reverse Prefix couple.

Different Types of Filtering Processes:

  • OR Usage: According to the conditions written, if at least one of them passes with the regarding person in the applicant pool, the person is included in the filtered version.

  • AND Usage: According to the conditions written, if every single one of them passes with the regarding person in the applicant pool, the person is included in the filtered version.

Special Input Conditions for Fields:

  • For all the non-mentioned fields below, the default input format should be applied for the filtering field. Default input formats can be checked from Adding a person: add - User Guide

  • For PHONE, any number of integers more than 0 can be entered.

  • For EMAIL and ADDRESS, any number of ASCII characters (also take the TIP into attention for correct results) more than 0 can be used.

  • For GPA, it prints the persons who have higher or equal amount of GPA from the given input

  • For ENDORSEMENT, a positive integer value is wanted, it prints the persons who have that much or higher amount of endorsements.

  • For SKILLS and POSITIONS, if more than one specification are added to the filter, they should be separated by ','

  • For DEGREE-LEVEL, there are 2 input type options: text and number. For the text format, the search is case-insensitive. So, any uppercase or lowercase type of the text is accepted. If filtering is applied for this criteria, the persons with the same or higher education levels are shown. There 5 different levels for the input:

    • Number: 0 and Text: highschool / Number: 1 and Text: associates (2-year-university) / Number: 2 and Text: bachelors / Number: 3 and Text: masters / Number: 4 and Text: phd

About the Running Process of Filtering Command:

  • The filtering is case insensitive. e.g hans will match Hans.

  • Filtering does not check if the written condition passes totally. It only checks, if the written condition is contained in the person properties. e.g if there is someone named Alex, in the filtering conditions n/ale/n or n/le/n or n/lex/n, Alex will be included.

  • All the people that are included in the filtering will be returned.

  • ADD operation clears the existing filters automatically.

  • After one filtering, the filtered address book can be filtered again.

  • For every single criteria between the filtering prefixes, input check for the validity is made.

  • When filtering is active, adding a person also clears the filter along the addition. But addition takes place.

Examples:

  • filter or phone<91234567>phone email<mail@ex>email skill<C++, Java>skill end<2>end deg<4>deg

    • Returns the people, whose numbers include 91234567 or whose email includes mail@ex or who has (contains) at least C++ or Java in the skills or has at least 2 endorsements or has at least Master’s degree.

  • filter and name<ale>name addr<street>addr gpa<3.1>gpa pos<Manager, Developer>pos deg<bachelors>deg

    • Returns the people, whose name contains ale (in any uppercase and lowercase format) and whose address contains street and who is interested in Manager and Developer positions,has a GPA higher than or equal to 3.1 and has at least Bachelor’s degree.

Clearing the filter in Recruit Me: filter clear

It clears all the filters in the applicant pool.
Format: filter clear

Reversing the filter in Recruit Me: filter reverse

It reverses all the filtering conditions and shows the eliminated ones.
Format: filter reverse

Contributions to the Developer Guide:

  • A new section for filtering is added to the developer guide,iImplementation of the whole process including testing is explained in detail:
    DeveloperGuide → Implementation → Filter or/and/clear/reverse feature (In the document below, basic explanation of the command types and valid input format of the related fields are excluded. Please look at the beginning part of the DeveloperGuide or read UserGuide section about filtering process to have a better understanding of the process) :

Current Implementation of Filter Command

Implementation Details:

  • Class Diagram of the Filtering Command:

class diagram filter

  • Sequence Diagram of the Filtering Command:

sequence diagram filter

  • Filtering is parsed in FilterCommandParser class, directed in FilterCommand class for further processing and actual filtering process took place in AddressBook class.

  • Working Principle of FilterCommandParser Class

    1. The input is trimmed (spaces at the beginning and at the end are cleaned), cleared from multiple spaces and turned into lowercase form.

    2. By checking the first number of characters of the input, the type of the process is determined (and, or, clear or reverse) and stored in an integer value. If the input has none of them, an invalid input message is shown.

    3. Since there are 10 different fields that can be filtered, a String array with size 10, called criterion, is created and the values are set to " " in initialization.

    4. If the type is clear or reverse, a new FilterCommand object is called with passing the criterion array and the process-type-holding-integer for that method. If it is not, followings take place.

    5. The prefixes are searched. For each of the fields, these controls are made:

      • Checked if the PREFIX exists in the input for the searched field.

      • If it is, then REVERSE PREFIX for that field is also searched and if that is also found, it is checked that if the PREFIX is placed before REVERSE PREFIX.

      • If it is not, or if the search cannot reach to this step, then an invalid input message is shown.

      • If the steps are passed successfully, the element in the criterion array for this field will be changed to the value "available"
        e.g. if the input is filter or phone<57>phone, then the PREFIX and REVERSE PREFIX locations are correct, the 21st index (related index for the phone in the array) of the criterion will be set to "available".

      • Since the parser looks for the first occurrence of PREFIX and REVERSE PREFIX, if there are multiple filtering parts for the searched criteria, then the first one will be taken.

    6. For the available fields (the ones with the regarding criterion indexes are set to "available"), an input check is made for the the text between the PREFIX and REVERSE PREFIX. For the non-available filtering conditions, the value in criterion for the related field is set to null.

    7. If the parameters does not pass the input check, an error is thrown, which says the input is in invalid form. If they passes the input check, then the index for the regarding field in criterion array is set to the text value between the PREFIX and REVERSE PREFIX.
      e.g. the 1st index of criterion is set to 57 regarding to the example above.

    8. FilterCommand function is called. In the parameters criterion and process-type-holding-integer passed to the object constructor.

  • Working Principle of FilterCommand Class

    1. For each 10 fields of the filter command criterion, a string parameter is constructed and the values are set regarding the values in criterion array. If no value for that field is present, the parameter in the FilterCommand class is set to null.

    2. Since SKILLS and POSITIONS fields can contain more than one criterion inside (all the criterion are separated with ", " for these), the string values in criterion array regarding to those fields are split through "," usage and the data for these are stored in String[] parameters created in FilterCommand class, instead of String parameters.

    3. Also the type of the process (and, or, clear or reverse) is stored in a parameter in FilterCommand, too.

    4. According to the process type, one of the methods filterAnd(), filterOr(), clearFilter() or reverseFilter() is called through Model interface and these methods in Model also called the one of these methods in AddressBook class with the same name.

    5. For filterAnd() and filterOr() methods, the values for every single field are passed through the method call.

  • Working Principle of AddressBook Class for Filtering Purposes

    • In the AddressBook class, a new UniquePersonsList parameter called allPersonsStorage is added.

    • When the filtering method is used, the persons parameter in the class is updated according to the filtering criterion (the persons that are not matching the conditions are removed). However, in order not to lose data, the new added allPersonsStorage parameter is not being changed with the filtering processes. It still continues to store every single person in the application storage.

    • When clearFilter() method is called, if there is a filtering available, every single person who is not in persons parameter but in allPersonsStorage are added to the persons storage. So basically, it is right to say that persons parameter only holds the persons we expect to see in the GUI.

    • When reverseFilter() method is called, if there is a filtering available, every single person who is in persons parameter is replaced with the persons who were not stored in this parameter before.

    • When filterOr() method is called, every single person in persons parameter is traversed and the ones that do not contain none of the criterion set through input are removed from persons.

    • When filterAnd() method is called, every single person in persons parameter is traversed and the ones that do not contain even one of the criterion set through input are removed from persons.

    • The information if there is a filtering available in the application, is also stored in a boolean parameter in AddressBook and set true with filterAnd() and filterOr() methods, set false with the initial launch of the application, clearFilter() call and Add Command call (because it increases the size of the data and it is not know that if the newly added person fits the filtering criterion or not).

    • Filter-keeping-parameter is important, because with undo and redo commands, it is important to maintain the filtering state in order not to lose any data and in order to use clearFilter() method.

Alternative Approaches

In this title, both Command implementation and Parser implementation will be discussed in 2 parts:

Command Implementation

Instead of adding another parameter in AddressBook class called allPersonsStorage, another approach would be letting persons parameter to hold all the unfiltered information and updating filteredPersons parameter in the ModelManager class. filteredPersons is a list of persons that is defined in ModelManager. It is especially used in FindCommand, that applies a basic filter to the list of persons in the application with only one criteria NAME. However, filteredPersons is implemented with Predicate approach.

  • Pros of this approach:

    • Does not need any additional permanent parameter to be created in AddressBook class.

    • Decreases the number of changes made in each list changing method of the AddressBook class. Because, if any additional parameter is added to AddressBook class, all the functions have to be changed considering the new parameter.

  • Cons of this approach:

    • It is hard and time consuming to implement this approach because Predicates are used. In AddressBook class itself, we can directly reach to the persons and their all fields easily. But with Predicate approach, it requires additional data to be built (Predicates may need to be created before adding new persons to the parameter). Moreover, we do not have much knowledge about Predicate usage and because of these reasons, our job may take more time to finish.

Parser Implementation

Instead of putting the criterion contents between both PREFIXES and REVERSE PREFIXES, we could only add the content after PREFIX (without any REVERSE PREFIX usage) like the addition process .

  • Pros of this approach:

    • User would need to write less number of characters

  • Cons of this approach:

    • Using also reverse prefix makes the job much easier, because it simply marks also the end of the content.

    • In currently implemented version, no order of the criterion is necessary. So, first phone number and then name etc. can be added for filtering condition. However in the alternative approach, implementing the input taking with no order is harder and time consuming.

Testing of Filter Command Design

The testing methods for filtering is written for 3 different parts:

FilterCommandParserTests

  • This test class is prepared for unit testing of FilterCommandParser cass. With the tests:

    • The validity of inputs with single and multiple field are present are checked.

    • The given order of inputs are checked in case of any possibility for an error.

    • Empty command or filter command without any type specification are checked.

    • The exceptions thrown are controlled, when the criterion are empty.

    • For number type of criterion, the negative and positive out of bound values, entering string values and entering valid values are checked.

    • For String type of criterion, the type of characters allowed are checked.

FilterCommandTests

  • This test class is prepared for unit testing of Filtering Command. With these tests Filtering process are checked:

    • when a single or multiple criterion are given,

    • when filtering occurs multiple times,

    • when type is clear or reverse and there are no/one/multiple filters are applied before.

FilterCommandIntegrationTests

  • This test class contains integration tests and investigates the interaction of FilterCommand with: UndoCommand, RedoCommand, AddCommand, DeleteCommand,SortCommand, FindCommand, SelectCommand, and cases, when all of them are together.

  • Each test case at least contains filtering with or - success or and - success, clear - success and clear - failure, reverse - success and reverse - failure.

  • Also for every interacting command, failure and success cases are both investigated.