| Both sides previous revision
Previous revision
|
|
tutorial:dev:override_filter [2019/02/04 09:20]
tomiskar |
tutorial:dev:override_filter [2019/03/01 10:37] (current)
kotisovam edits |
| ====== Module - Override a filter in custom module ====== | ====== Module - Overriding a filter in a custom module ====== |
| |
| A [[devel:documentation:architecture:dev:filters|mechanism]] for dynamic registry and composing of filters has been developed in the application for searching the data in IdM (identities, roles, tree structure components, etc.). A new filter can be registered for existing REST services in any module. | A [[devel:documentation:architecture:dev:filters|mechanism]] for dynamic registry and composing of filters has been developed in the application for searching the data in IdM (identities, roles, tree structure components, etc.). A new filter can be registered for existing REST services in any module. |
| |
| The aim of this tutorial is show the way, how to override some actual filter behavior. We chosen **filter on identity's username**, which is represented by ''username'' parameter in search (url parameter). This filter is implemented in core module and search all identities, which have the same username as given parameter value (equals). We want to override this filter => we want to search all identities with username, which contain given parameter value (like). | The aim of this tutorial is to show how to override some actual filter behavior. We chosen **filter on identity's username**, which is represented by ''username'' parameter in search (url parameter). This filter is implemented in core module and search all identities, which have the same username as given parameter value (equals). We want to override this filter => we want to search all identities with username, which contain a given parameter value (like). |
| |
| Source codes for this tutorial can be found in the [[https://github.com/bcvsolutions/CzechIdMng/blob/f1af4dc460b185c0668508ce6def223cd11e3971/Realization/backend/example/src/main/java/eu/bcvsolutions/idm/example/repository/filter/UsernameIdentityFilter.java|example module]] | Source codes for this tutorial can be found in the [[https://github.com/bcvsolutions/CzechIdMng/blob/f1af4dc460b185c0668508ce6def223cd11e3971/Realization/backend/example/src/main/java/eu/bcvsolutions/idm/example/repository/filter/UsernameIdentityFilter.java|example module]] |
| |
| ===== What do you need before you start ===== | ===== What you need before you start ===== |
| |
| * You need to install CzechIdM 7.5.0 (and higher). We have CzechIdM installed for this tutorial on server ''http://localhost:8080/idm-backend''. | * You need to install CzechIdM 7.5.0 (and higher). We have CzechIdM installed for this tutorial on server ''http://localhost:8080/idm-backend''. |
| ===== 01 Test search identity by username ===== | ===== 01 Test search identity by username ===== |
| |
| At start, we will search identity by username - we will see, how core filter works. Just core filter is implemented now, so command: | At start, we will search identity by username - this way you can see how the core filter works. Only the core filter is implemented now, and as a result this command: |
| |
| $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test12345 | $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test12345 |
| | |
| returns our prepared test identity, but command | returns our prepared test identity, whereas the command |
| |
| $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test1234 | $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test1234 |
| |
| returns nothing (if we don't have identity with username ''test1234'' created:)). | returns nothing (unless we have previously created an identity with the username ''test1234'')). |
| |
| ===== 02 Filter implemetation ===== | ===== 02 Filter implementation ===== |
| |
| We'll create new filter in our module, which search all identities with username, which contains given parameter value (like). | We are going to create a new filter in our module which searches all identities by username, which contains a given parameter value (like). |
| |
| <code java> | <code java> |
| </code> | </code> |
| |
| New filter is registered to search identities (see FilterBuilder template), when parameter ''IdmIdentityFilter.PARAMETER_USERNAME'' is given in search parameters. Filter behavior is implemented in ''getPredicate'' method. Method ''getOrder'' says, which filter will be used as default. For example, if we want to add new filter and we want to make him default without any additional configuration, then we'll return value e.g. ''-10''. Then this filter will be used, when application starts as default (=> order before core filters), respectively before all filters with order greater than ''-10''. | The new filter is registered to search for identities (see FilterBuilder template), when parameter ''IdmIdentityFilter.PARAMETER_USERNAME'' is given in search parameters. Filter behavior is implemented in ''getPredicate'' method. The method ''getOrder'' says which filter is used by default. For example, if we want to add a new filter, and set it as default without any additional configuration, then we return value e.g. ''-10''. Once set up this way, the filter will be used, when application starts as default (=> order before core filters), respectively before all filters with order greater than ''-10''. |
| |
| ===== 03 Configure filter usage ===== | ===== 03 Configure filter usage ===== |
| |
| We added new filter with order ''10'', so default filter is still used, because all core filters has order ''0'' (**the smallest order wins** - see ''[[https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/Ordered.html|@Ordered]]''). That is what we wants in the most ways. We don't want to change default behavior, but we want to be able to configure, which filter is used explicitly => choose one implementation. | We added new filter with order ''10'', so a default filter is still used, because all core filters have order ''0'' (**the smallest order wins** - see ''[[https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/Ordered.html|@Ordered]]''). That is all we need in most cases. We don't intend to change default behavior, but we want to be able to configure which one of the filters is used explicitly => choose one implementation. |
| |
| So, we can go to the application configuration page (or to application.property file) and set property value: | Go to the application configuration page (or to application.property file) and set the property value: |
| |
| <code properties> | <code properties> |
| </code> | </code> |
| |
| <note important>We added new filter with order ''10'', so default filter is still used, because all core filters has order ''0'' (**the smallest order wins** - see ''[[https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/Ordered.html|@Ordered]]'').</note> | <note important>We've added a new filter with order ''10'', so the default filter is still used, since all core filters have order ''0'' (**the smallest order wins** - see ''[[https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/Ordered.html|@Ordered]]'').</note> |
| |
| Read more about [[devel:documentation:application_configuration:dev:backend#entity_filters|filter configuration]]. | Read more about [[devel:documentation:application_configuration:dev:backend#entity_filters|filter configuration]]. |
| ===== 04 Test search identity by username ===== | ===== 04 Test search identity by username ===== |
| |
| We execute test commands again: | Now, execute test commands again: |
| $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test12345 | $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test12345 |
| $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test1234 | $curl -u admin:admin http://localhost:8080/idm-backend/api/v1/identities?username=test1234 |