EmailNotificationService

Supporting service for the user-registration functionality.

The framework provides a default implementation which in turn uses the org.apache.causeway.applib.services.email.EmailService , namely EmailServiceDefault .

API

EmailNotificationService.java
interface EmailNotificationService {
  boolean send(EmailRegistrationEvent ev)     (1)
  boolean send(PasswordResetEvent ev)     (2)
  boolean isConfigured()     (3)
}
1 send(EmailRegistrationEvent)

Sends an email to verify an email address as part of the initial user registration
2 send(PasswordResetEvent)

Sends an email to reset a password for an already-registered user
3 isConfigured()

Whether this service has been configured and thus available for use.

Members

send(EmailRegistrationEvent)

Sends an email to verify an email address as part of the initial user registration

send(PasswordResetEvent)

Sends an email to reset a password for an already-registered user

isConfigured()

Whether this service has been configured and thus available for use.

If this returns false then it is not valid to call #send(EmailRegistrationEvent) (and doing so will result in an IllegalStateException being thrown).

Implementation

The Core Runtime Services module provides a default implementation of this service, EmailNotificationServiceDefault. This implementation constructs the emails to send in support of user registration.

Alternatives

The text of these email templates are hard-coded as resources, in other words baked into the core jar files. If you need to use different text then you can of course always write and register your own implementation to be used instead of Apache Causeway' default.

If you have configured an alternative email service implementation, it should process the message body as HTML.

Be aware also that there may not be any Apache Causeway session running when this service is called. If necessary, one can be created on the fly using the InteractionService#runAuthenticated(…​) (not API). .

User Registration

The EmailNotificationService supports the user registration (self sign-up) features of the Web UI (Wicket viewer) whereby a user can sign-up to access an application by providing a valid email address.

  • The Wicket viewer will check whether an implementation of this service (and also the UserRegistrationService) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address.

  • A verification email is sent using this service; the email includes a link back to the running application.

  • The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned UserRegistrationService).

  • The role of this service in all of this is to format and send out emails for the initial registration, or for password resets.

The default implementation of this service uses the EmailService, which must be configured in order for user registration to be enabled.

The default implementation of this service uses EmailService, which must have been configured/initialized correctly.

This service is used by (Apache Causeway' default implementation of) UserRegistrationService.

See: