Search workflow

How does it work

All search operations are performed through API. There are no direct interactions with database.

Following sequence diagram describes how samples search request is processed.

What logic is executed when search by samples is performed?

All search requests are handled by SearchController class. It is mapped to handle all /search requests (using class-level @RequestMapping("/search") annotation). Afterwards, appropriate method is chosen (in this case, it should be mapped with @PostMapping("/sample")). @PostMapping means that method gets invoked only if POST requests comes to corresponding URL.

In case of POST requests, data comes to server in JSON format. Spring automagically unmarshalls incoming JSON into instances of classes specified in arguments of appropriate methods (argument should be marked with @RequestBody annotation).

How API requests are built?

Each *ApiServiceImpl class uses corresponding Fluent*SearchApiBuilder builder to build request parameters. In case of samples search it is FluentSampleSearchApiBuilder.

Let's review how SamplesApiServiceImpl.findSample builds search parameters:

` Strgin requestParams = FluentSampleSearchApiBuilder.aRequest()

            .queryNumber(searchCriteria.getSampleNumber()).andReturn()

            .queryCountry(searchCriteria.getCountry())

            .returnAnalyzed()

            .buildFullQuery();`

• searchCriteria.getSampleNumber() - returns instance of SearchField class that represents one search criterion in the search form.

SearchField class contains 2 fields: name - which is actually value of the search criterion and LookUpType enum which indicates search type (selected from combobox).

• .queryNumber(searchCriteria.getSampleNumber())

Adds search criteria for querying samples by number.

• .andReturn()

Specifies that we want to get in response fields from the previously called query method (fields used in queryNumber method).

• .queryCountry(searchCriteria.getCountry())

Adds criteria for querying samples by country without returning these fields.

• .returnAnalyzed()

Indicates that we want to get additionally analyzed field.

• .buildFullQuery()

Specifies that we want to build query with specified returning fields (there is also method buildDefaultFieldsQuery() which builds query without &fields= parameters).

Please note that these builders build only filtering part of search criteria! Technical parameters such as paginate_by, page, order_by are filled in ApiServiceImpl.searchRawEntities. These parameters can be also moved to builders if needed.

Internally builders use following methods which they inherit from parent class FluentSearchApiBuilder:

1. buildFieldParameters(fieldName, value) - search for given value in one field
2. buildMultiSearch(value, fieldName...) - search for value in multiple fields
3. addReturningField(fieldName) - retrieve this field with given name
4. buildOrSearch(List orSearchPairs) - OR search. OrSearchPair contains SearchField object and name of the field which should contain given value (used for example in queryMultipleIds method).

Pro tips: How to debug stuff

During debug session you are provided with current Java heap dump which contains all the used variables. Oftentimes it is much more convenient and efficient to debug application than putting additional log outputs.

1. Run application in debug mode from your IDE.
2. Put breakpoints to suspicious code lines (e.g after calling builders' build methods).
3. Reproduce the issue
4. Check what parameters were built
5. ???
6. Fix bug!
7. And definitely write unit tests for such case!