This chapter focuses on explaining the Liferay development basics. You learn about the Liferay workspace’s power to set up your local development environments and its fundamentals for creating, building, and deploying Liferay modules using different approaches, such as the wizard and the Blade CLI. The chapter also explains how to build modules using Gradle and Maven. Once you are familiar with these fundamentals, you learn how to start the Liferay DXP Server and connect your Liferay DXP instance to the database. Lastly, you are introduced to Gogo shell for managing deployed modules.
The Liferay Workspace
As the name suggests, a Liferay workplace is nothing more than an area to keep and manage projects while developing modules in Liferay DXP. The Liferay workplace is generated to help manage Liferay modules by providing the right set of tools and folder structure and offering support to build processes and other configurations. In the Liferay documentation, the workspace is called a “generated wrapper environment” and is an official way to create Liferay DXP modules using Gradle. However, the Liferay workplace can also be created with Maven. Don’t worry if you don’t know Gradle and Maven; you’ll learn more about them later in this chapter.
Liferay Workspace Primer
The Liferay workspace is very flexible, as it can be used in many different development environments. Typically, when a team is working on a Liferay project, the Liferay workspace is initialized by one developer and then committed to a revision control system. Then the same workspace is checked out by the rest of the team and configured in the Eclipse/Liferay Developer Studio to develop new modules. However, one project can have multiple workspaces depending on its requirements. Also, it can be used in various IDEs. Build scripts and configurations can also be edited and easily managed using the Liferay workspace. Not only this, but the workspace can be customized according to need. So, a team of developers can share a single Liferay workspace, which is why it’s considered flexible.
Two approaches can initialize the Liferay workspace: using the Blade CLI or using the Eclipse/Liferay Developer Studio, supporting Gradle and Maven for project builds. They are covered briefly in the upcoming section.
Configs: This folder contains configuration files of different environments. These files are used by Liferay DXP servers and projects inside your workspace as global configuration files.
Gradle: This folder contains the Gradle wrapper used by the Liferay DXP workspace.
Modules: This folder contains Liferay DXP custom modules.
Themes: This folder contains the Liferay themes generated using the Liferay Theme Generator.
Build.gradle: This folder is a standard build file of Gradle.
Gradle-local.properties: This folder is used to specify the user-specific properties of your workspace, which will help multiple users use a single workspace by configuring specific properties for the workspace on their machines.
Gradle.properties: This file specifies the Liferay DXP server global configuration and workspace’s project location.
Gradlew: This folder is used to execute the Gradle command wrapper.
Settings.gradle: This folder configures dependencies and applies plugins to the workspace.
A screenshot of the Liferay workplace lists project explorer. The project explorer lists apress underscore ws.
The Liferay workspace
You see Gradle-related folders and files here, but this does not mean that only Gradle can be used to build the modules.
This section has explained the Liferay workspace; in the next section, you explore various Liferay DXP-supported build tools.
Build Tools
Liferay DXP modules can be built using Gradle or Maven. However, by default, Gradle is used for builds. Gradle and Maven are different tools that will help you build software. Building software is an end-to-end process involving many distinct functions. Compiling the source code and packaging are the two most important in this context.
Gradle
Build.gradle Example
Maven
Pom.xml Example
Introduction to Liferay Modules
This book has already discussed what a Liferay module actually is, but to brush up, a Liferay module is simply an OSGi component with a specific declaration for registering it as a Liferay component in the @component annotation body. The crucial entries in this annotation are the property key and the service key. There are different values for them, which you learn in detail in the Liferay portlet creation section of the next chapter. Here, you see an overview of a Liferay module.
- 1.
Creating an empty module: A module consists of a folder structure that’s ideal for maintaining scalable code.
- 2.
Creating the configuration files: You have already created a folder structure, but to register the folder structure as a module, you need to create a few configuration files, including a manifest, build scripts, and resources.
- 3.
Creating the source code: A module needs source code to implement the logic. This is the backbone of the module. It indicates when the module is deployed, when it’s visible, and when it’s executed to the end user.
- 4.
Compilation: By the end of Step 3, you have created a module, but it is passive, which means the module is created, but it is not running. To run the module, you must build the code. Compilation is the first step of the build process. The code is built from the configuration and build scripts you created. The compiled code is packaged in a WAR or JAR file (an artifact), ready for deployment during the next step.
- 5.
Deployment: Deployment is the process of installing the packaged artifact on the application server. Liferay has a straightforward installation process; you have to copy the artifact in the deploy directory of the application server, and the rest is taken care of by the Liferay runtime.
Blade tools and Developer Studio can be used to do all this effectively and efficiently. You learn about the Blade CLI commands needed to do these steps in the next section of this chapter.
The @component Annotation
This section has explained the various Liferay DXP-supported build tools; in the next section, you explore the Blade CLI.
The Blade CLI
Blade stands for Bootstrap Liferay Advanced Developer Environment, which essentially provides a command-line interface for managing Liferay modules and projects in a Liferay workspace. Internally, the Blade CLI is a bootstrapped version of a Gradle-based environment that creates/builds Liferay modules. Everything from creation to the deployment of modules can be done with the help of Blade commands.
init: This command is used to initialize a new Liferay workspace. As you know, you need to create a workspace before creating a module. By default, all the Blade commands create a Gradle-based environment, which can be customized to Maven. It also automatically sets the default Liferay DXP version. For example:
version: This command displays version information about the Blade CLI.
samples: This command generates a sample project.
create: This command creates a new Liferay module project from the available templates.
install: This command installs a bundle into Liferay’s module framework.
deploy: This command builds and deploys bundles to the Liferay module framework.
update: This command updates the Blade CLI to the latest version.
server: This command starts or stops the server defined by your Liferay project. For example:
help: This command provides help about a specific command.
sh: This command connects to Liferay, executes the Gogo command, and returns the output.
This section has explained how you can work with the Blade CLI; in the next section, you learn how to run Liferay DXP the first time.
Running Liferay the First Time
To superficially understand Liferay, you can broadly say that Liferay is a Java-based web application (a portal) running inside an application server. It may be in any form, such as a Liferay DXP bundled application server that can run in a cloud-based server or a container (Docker and so on). There is another way, which is to manually install Liferay in your choice of application server.
Liferay comes bundled with server applications, such as Apache Tomcat, Jboss, Glassfish, and so on. The Liferay DXP Tomcat bundle is an archive that can be extracted, configured, and run on any server. It is a very lean Apache Tomcat application server with Liferay DXP installed and can be easily configured. The example you see in this section is the installation of a Tomcat bundled Liferay DXP on a Windows computer.
Java installation: A compatible Java (JDK) version is installed. Java 11 is recommended, or any equivalent TCK compatible Java, such as AWS Corretto. Check the Liferay compatibility matrix on the official website. The Java_home and path variables must be set.
Liferay artifacts: The Tomcat bundle and activation key downloaded from Liferay’s official website.
Running Liferay Application
data: This folder stores files that are stored inside Liferay Documents and Media, search indexes, hypersonic databases, and the deployed license of a Liferay subscription. These are not present in all environments, but depend on the configurations.
deploy: This directory is readable from the auto-deploy scanner and is used for deployment. Whenever a JAR file is ready, you have to move the JAR inside this directory to get it deployed.
elasticsearch-sidecar: This is the embedded search engine of Liferay DXP 7.4. This was named elasticsearch7 in version 7.3. It was not part of the bundle before Liferay DXP 7.2 and below.
license: This folder contains the distribution license information of Liferay DXP and other third-party software.
logs: This folder stores all the Liferay run logs.
osgi: This folder contains all the artifacts and configurations of the deployed OSGi modules in the server. You can say this is the backbone of an OSGi system inside a Liferay DXP application server.
patching-tool: This folder appears in the Enterprise edition of the Liferay DXP distribution only. This tool helps in installing officially published patches in the Liferay DXP application server.
tools: This folder contains a script batch file, which helps in migrating the Liferay database from a lower version to the current version of Liferay when you’re upgrading Liferay.
A snapshot of the application server's structure. Pages and folders are on the list.
The top hierarchy of the application server
A screenshot of the Liferay server startup script. The title reads, Starting Liferay digital experience platform 7. 4. 13 G A 1 with a date and year.
The Liferay server startup
This section has explained how to start the Liferay server the first time; the next section explains how to connect the server to a database.
Database Connectivity with Liferay DXP
Database connectivity is essential for any web application. The Liferay DXP database stores a lot of information, including user data, site data, and so on. It may shock you, but in a fresh installation of Liferay DXP, you get approximately 392 tables. In fact, starting Liferay DXP (or any version of Liferay) is not at all possible without a database. Due to this reason, Liferay DXP is shipped with an embedded in-memory database, which is initialized with sample data when you start the server the first time. The name of this in-memory database is Hypersonic SQL (HSQL). The HSQL database is recommended for demo purposes or the first startup only, as it loses values when Liferay is restarted.
You need to connect Liferay DXP to any standard relational database (RDBMS), such as Oracle, MySQL, and MariaDB, for persisting values for production and other environments. Connecting RDBMS to Liferay DXP is very easy and achieved in several ways. The three most popular methods are configuring the user interface (after starting the portal the first time), using portal-ext.properties, or using the JNDI approach. The following section explains these approaches.
Note that whatever approach you choose, you must create a database with the needed encoding (UTF8 in most cases) and user credentials for database access before starting the configuration in Liferay. After the connectivity configuration, it is mandatory to restart the Liferay DXP application server to see the connectivity.
Database connectivity from the UI: As you learned at the beginning of this section, the Liferay DXP portal cannot be started without database connectivity, and HSQL helps. Once the portal starts with HSQL, there is a screen on the browser to connect the database with your instance of Liferay. See Figure 2-4. Once configured, these configurations are stored in portal-setup-wizard.properties. This is the easiest way to connect to a database. However, this screen will not appear if connection details are provided elsewhere in the system.
A screenshot of a database. The filled-in information bars are database type, J D B C U R L, J D B C driver class name, user name, password, and sample data.
Database connectivity using the UI
Database connectivity from portal-ext.properties: Connecting to the database using the properties file is a straightforward configuration approach. You can provide connectivity-related details in either of the portal-ext.properties files. This property file serves as a master resource bundle for most portal configurations. This uses the JDBC approach for connectivity. To connect, you must mention four properties and values, listed here:
jdbc.default.driverClassName= This property tells Liferay to load the respective driver while connecting to the database. It provides all the essential classes and interfaces to make pooled connections with databases. For example, to connect to MySQL 8, you use the com.mysql.cj.jdbc.Driver driver class.
jdbc.default.url= This is the connection URL. It contains the protocol, host, port number, database name, and other optional parameters such as encoding, and so on. The following example is a sample connection URL that connects to a MySQL 8 database:
jdbc:mysql://localhost/lportal74?characterEncoding=UTF-8
jdbc.default.username= This is a key to provide a username to authenticate the connection.
jdbc.default.password= This is a key to provide a password to authenticate the connection.
Database connectivity via JNDI: This approach comes from traditional Java applications and is the most complicated among those mentioned. The Java Naming and Directory Interface (JNDI) is an application programming interface (API) that provides naming and directory functionality to Java applications. JNDI connectivity is generally preferred in production environments because of better garbage handling and multithreading, thus improved performance. To do connectivity, you must set the configurations in the following files—context.xml and portal-ext.properties—as explained in Listings 2-5 and 2-6.
Context.xml Configuration
The portal-ext.properties File Configuration
A screenshot of the database connectivity confirmation logs. The log illustrates commands for verification, starting initial, dynamic, and web bundles.
Database connectivity via the JNDI connection log
This section has explained how to connect Liferay DXP to the database; in the next section, you are introduced to the Gogo shell.
Gogo Shell
The Gogo shell is the command-line interface for OSGi and was developed by the Apache Organization. Its full name is Apache Felix Gogo Shell and it’s a subproject of Apache Felix implementation. It is very generic and is used in various servers and runtime environments such as Eclipse IDE, Apache Karaf, and so on. As Liferay Developer Studio uses Eclipse as a base; it is very well used there as well.
Command: Gogo shell commands are part of the Org.apache.felix.gogo.command package, and they contain a set of basic commands.
Runtime: The Gogo shell runtime is included in the Org.apache.felix.gogo.runtime package and is the backbone of command-processing ability.
Shell: Gogo shell is present in the Org.apache.felix.gogo.shell package and is responsible for the command-line interface.
It is for the OSGi framework,
Unlike the UNIX Bash, it converts all arguments to strings,
All the public methods are used as command names to operate on data and objects,
The Gogo shell used in Liferay DXP allows you to use all Felix Gogo shell basic commands and Liferay commands. Also, in Liferay DXP, the Gogo shell can be accessed from the Liferay DXP Control Panel, the Blade CLI, and telnet. However, Liferay recommends using it from the control panel. You must make sure the application server is up and running. Gogo shell is excellent for managing OSGi bundle lifecycles using commands. You have already seen the bundle states, and those states can be changed from the Gogo shell using various commands, including install, start, stop, and so on. This is how the modularity of Liferay DXP comes into action.
A screenshot of a Gogo shell demonstrates the list of bundles. The tab on the top is labeled Command, and the button above the bundles is labeled Execute.
The Gogo shell’s Installed bundles list
Summary
In this chapter, you learned how to leverage the power of the Liferay workspace for setting up development environments and their fundamental parts. Next, you learned how to build modules using Gradle and Maven. Once you were familiar with the Liferay workspace, you learned how to create a Liferay module. Further, you learned how to start the Liferay DXP server and connect your Liferay DXP instance to the database. Lastly, you were introduced to the Blade CLI and Gogo shell.