[
{
"path": ".gitattributes",
"content": "# Set default behaviour, in case users don't have core.autocrlf set.\n* text=auto\n\n# Explicitly declare text files we want to always be normalized and converted\n# to native line endings on checkout.\n*.c text\n*.h text\n*.java text\n*.xml text\n*.gradle text\n*.fodp text diff=xml\n*.properties text\n*.css text\n*.js text\n*.sql text\n*.txt text\n*.xsl text\n*.tex text\n*.markdown text\n*.md text\n\n# Declare files that will always have CRLF line endings on checkout.\n*.sln text eol=crlf\n\n# Denote all files that are truly binary and should not be modified.\n*.png binary\n*.jpg binary\n*.gif binary\n"
},
{
"path": ".gitignore",
"content": "*~\n*.bak\n*.class\n*.iml\n*.swp\n*-tmp.html\n.project\n.classpath\n.settings\ngit-modified-list.txt\nnbbuild.xml\nproperties/\n.METADATA\n.DS_Store\n.directory \n.gradle\n.nb-gradle\n.vscode\n\nnode_modules/\n\n/*.ipr\n/*.iws\n/*.patch\nbuild.*.properties\n\nbuild/\nclasses/\ndist/\n**nbproject**\n.ivy/\n.sass-cache/\n.DS_Store/\n*#\n/develop/tutorials/code/osgi/modules/form-nav-extension-portlet/.nb-gradle/\n/develop/tutorials/code/osgi/modules/com.liferay.docs.greetingimpl/.nb-gradle/\n/develop/tutorials/code/osgi/modules/com.liferay.docs.greetingapi/.nb-gradle/\n/develop/tutorials/code/osgi/modules/com.liferay.docs.greetingcommand/.nb-gradle/\n**/temp/**\n/develop/tutorials/code/com-liferay-docs-guestbook/.nb-gradle/\n"
},
{
"path": "README.markdown",
"content": "# LIFERAY-DOCS\n\n\n\n\n\n[](https://liferay-community.slack.com/messages/C5XE4BH3Q/)\n\nWelcome to Liferay's official documentation project, the home of\n[Liferay Developer Network](https://dev.liferay.com) articles. All articles are\nwritten in\n\nMarkdown, making them easy to write and read. Approved articles are\nuploaded to the Liferay Developer Network (LDN) and converted automatically to\nHTML. In this project, you can contribute new articles, improve existing\narticles, or fix documentation bugs. To produce documentation that is\ncomprehensive and stylistically consistent, the liferay-docs project provides\nwriting guidelines,\nstandards & customizations,\nand a\ntutorial template.\n\nYou'll learn how quickly to submit a new article and its images next. \n\n## Quick Steps to Submit a New Article\n\nYou can follow these steps to create a new article and contribute it from \nGitHub. \n\n1. Sign in to GitHub. If you don't already have a GitHub account, you must\n [join](https://github.com/join) GitHub in order to contribute to\n liferay-docs. \n\n2. Click on a `new-articles` link folder below. These match the LDN sections\n where you can add a articles:\n\n - `develop/new-articles`\n\n - `discover/new-articles`\n\n - `distribute/new-articles`\n\n3. Select the liferay-docs branch that matches the Liferay Portal version\n you're writing about: \n\n
\n
\n
Branch
\n
Portal Version
\n
\n
\n
master
\n
7.2
\n
\n
\n
7.1.x
\n
7.1
\n
\n
\n
7.0.x
\n
7.0
\n
\n
\n
6.2.x
\n
6.2
\n
\n
\n\n4. Click the **plus** sign after **new-articles/:**\n \n\n5. Write your article and click the\n  button, to\n prepare a [pull request](https://help.github.com/articles/using-pull-requests/). \n\n6. Send the pull request to the default user `liferay`. \n\n7. Drag your article's images into the pull request's comments to associate\n the images with your article. \n\nYour new article is submitted! Liferay's Knowledge Management team will review\nyour contribution. Approved changes are merged into the liferay-docs repo and\npublished to the [Liferay Developer Network](https://dev.liferay.com). \n\nIf you want to clone our repository and do serious documentation work on your\nown machine, [click here](guidelines/01-creating-docs-for-liferay.markdown) to go\nto our guidelines section. \n\nThanks for helping us out with Liferay documentation! \n\n## Redirect instructions\n\n```\ncd liferay-docs\n./bin/update_liferay_learn_links.sh path/to/properties/file\n```\n\nFor example, \n\n```bash\ncd liferay-learn\ncat ./site/docs/redirects_keep.properties ./site/docs/redirects_new.properties > ~/redirects.properties\ncd ../liferay-docs\n./bin/update_liferay_learn_links.sh ~/redirects.properties\n```\n"
},
{
"path": "bin/convert-markdown.sh",
"content": "#!/bin/sh\n\nscriptPath=$(readlink -f \"$0\")\n\nclasspathDir=$(dirname $(dirname \"$scriptPath\"))/lib\nhtmlFile=$1\nhtmlFile=$(echo \"${htmlFile}\" | sed 's/[^.]*$//')\nhtmlFile=${htmlFile}html\n#echo \"java -cp \"${classpathDir}/*\" com.liferay.documentation.util.MarkdownToHtml $1 ${htmlFile}\"\n#java -cp \"${classpathDir}/*\" com.liferay.documentation.util.MarkdownToHtml $1 ${htmlFile}\n# echo \"java -cp \"${classpathDir}/*\" com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI $1 > ${htmlFile}\"\njava -cp \"${classpathDir}/*\" com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI /dev/stdin \nexit 0\n"
},
{
"path": "bin/convert.bat",
"content": "@echo off\n\nset CLASSPATH=%~dp0\\..\\lib\n\nif \"%1\"==\"\" goto usage\nif \"%2\"==\"\" goto convert\n\njava -cp .;%CLASSPATH%\\* com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI %1 > %2\n\ngoto end\n\n:usage\n\necho Usage: convert.bat [Markdown file to convert] or convert.bat [Markdown file to convert] [HTML file to be written]\necho.\necho Run the convert.bat script from any directory.\necho.\necho The first argument is the path to the Markdown file to convert to HTML.\necho.\necho The second argument is optional. It specifies the path to the HTML file to be created. If this argument is omitted, the HTML file to be created will be created in the same directory as the Markdown file and will have the same filename as the Markdown file except that the .markdown file extension will be replaced by the .html file extension.\necho.\ngoto end\n\n:convert\n\nset htmlFile=%1\nset htmlFile=%htmlFile:markdown=html%\n\njava -cp .;%CLASSPATH%\\* com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI %1 > %htmlFile%\n\n:end\n"
},
{
"path": "bin/convert.sh",
"content": "#!/bin/sh\n\nscriptPath=$(readlink -f \"$0\")\n\nclasspathDir=$(dirname $(dirname \"$scriptPath\"))/lib\n\nif [ $# -lt 1 ]; then\n\techo\n\techo Usage: ./convert.sh \\[Markdown file to convert\\] or ./convert.sh \\[Markdown file to convert\\] \\[HTML file to be written\\]\n\techo\n\techo Run the convert.sh script from the liferay-docs directory or any subdirectory.\n\techo\n\techo The first argument is the path to the Markdown file to convert to HTML.\n\techo\n\techo The second argument is optional. It specifies the path to the HTML file to be created. If this argument is omitted, the HTML file to be created is created in the same directory as the Markdown file and has the same filename as the Markdown file except that the .markdown file extension is replaced by the .html file extension. \n\techo\n\texit 1\nelif [ $# -lt 2 ]; then\n\thtmlFile=$1\n\thtmlFile=$(echo \"${htmlFile}\" | sed 's/[^.]*$//')\n\thtmlFile=${htmlFile}html\n\t#echo \"java -cp \"${classpathDir}/*\" com.liferay.documentation.util.MarkdownToHtml $1 ${htmlFile}\"\n\t#java -cp \"${classpathDir}/*\" com.liferay.documentation.util.MarkdownToHtml $1 ${htmlFile}\n\techo \"java -cp \"${classpathDir}/*\" com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI $1 > ${htmlFile}\"\n\tjava -cp \"${classpathDir}/*\" com.liferay.knowledge.base.markdown.converter.cli.MarkdownConverterCLI $1 > ${htmlFile}\n\texit 0\nelse\n\tjava -cp \"${classpathDir}/*\" com.liferay.documentation.util.MarkdownToHtml $1 > $2\n\texit 0\nfi\n"
},
{
"path": "bin/migrate.py",
"content": "import os\nimport re\nimport shutil\nimport sys\n\n\ndef append_to_line(line, new_line):\n line = line.replace(\"\\r\",\"\")\n line = line.replace(\"\\n\", \"\")\n line = line + \" \" + new_line.lstrip()\n return line\n\ndef end_sidebar(sidebar_line, newFile):\n if sidebar_line not in \"\":\n sidebar_line = sidebar_line.replace(\"| \", \"\")\n newFile.write(sidebar_line)\n newFile.write(\"```\\n\")\n sidebar_line = \"\"\n return sidebar_line\n\ndef write_and_reset_string(line, newFile):\n if line not in \"\":\n newFile.write(line)\n line = \"\"\n\n return line\n\n\nif __name__ == \"__main__\":\n\n if (len(sys.argv) < 2):\n print(\"Usage:\\n\\tpython migrate.py article [dest_folder]\\n\\nDescription:\\n\\tMigrates the article to an .md file and converts the content to liferay-learn Markdown/MyST syntax. The converted article destination folder [dest_folder] is the current folder by default but is typically set to a liferay-learn folder.\\n\\n\\tIMPORTANT: Run this script in the liferay-docs article's folder so that the script can use the image file paths found in the article to copy the image files to the [dest_folder]/[article_name]/images/ folder.\")\n sys.exit()\n\n article = sys.argv[1]\n\n dest_folder = \".\"\n if (len(sys.argv)) > 2:\n dest_folder = sys.argv[2]\n\n if not (os.path.isdir(dest_folder)):\n os.mkdir(dest_folder)\n\n article_name = article.split('.markdown')[0]\n\n new_article_path = dest_folder + \"/\" + article_name + \".md\"\n\n # Copy referenced image files to [article destination folder]/[article_name]/images\n\n file = open(article)\n content = file.read()\n file.close()\n\n png_split = content.split('.png)')\n\n images = []\n\n png_split_len = len(png_split) - 1\n ii = 0;\n\n while (ii < png_split_len):\n paran_split = png_split[ii].split('(')\n\n if (len(paran_split) > 1):\n image = paran_split[len(paran_split) - 1] + '.png'\n images.append(image)\n\n ii = ii + 1\n\n article_name_folder = dest_folder + \"/\" + article_name\n images_folder = article_name_folder + \"/images\"\n\n if (len(images) > 0):\n\n if not os.path.isdir(article_name_folder):\n os.mkdir(article_name_folder)\n\n if not os.path.isdir(images_folder):\n os.mkdir(images_folder)\n\n print(\"Writing images to folder: \" + images_folder)\n\n for ff in images:\n shutil.copy(ff, images_folder)\n\n # Process the text\n\n file = open(article)\n lines = file.readlines()\n file.close()\n\n # Open the destination file for writing to\n newFile = open(new_article_path, 'w')\n\n print(\"Migrating to article: \" + new_article_path)\n\n # Track the last significant line's first non-space character column index\n prev_index = -1\n\n # Variables for storing text that belongs on the same line; hard returns are\n # removed\n list_item_line = \"\"\n para_line = \"\"\n sidebar_line = \"\"\n\n # Variables that allow you to skip more detailed condition checks\n done_header_id = False\n done_title = False\n done_toc = False\n prev_sidebar_line_empty = False\n\n # Variables for markup context\n in_code = False\n in_header_id = False\n\n images_folder_path = \"](./\" + article_name + \"/images/\"\n\n for line in lines:\n\n # Set all image file locations to the ./[article_name]/images/ folder\n line = re.sub(\"\\]\\((../)+images/\", images_folder_path, line)\n\n # Replace legacy tokens\n line = re.sub(\"@product@\", \"Liferay DXP\", line)\n line = re.sub(\"@commerce@\", \"Liferay Commerce\", line)\n line = re.sub(\"@ide@\", \"Dev Studio DXP\", line)\n line = re.sub(\"@app-ref@\", \"https://docs.liferay.com/dxp/apps\", line)\n line = re.sub(\"@platform-ref@\", \"https://docs.liferay.com/dxp/portal\", line)\n\n # Convenience variable for working with the current line free of leading\n # and trailing white space.\n trimmed_line = line.lstrip()\n\n if not done_header_id:\n # Skip over all of the legacy header-id stuff\n\n if trimmed_line.startswith(\"---\"):\n if not in_header_id:\n in_header_id = True\n else:\n done_header_id = True\n in_header_id = False\n\n continue\n if not done_title and trimmed_line in \"\":\n # Skip empty lines until the title is written\n continue\n elif line.startswith(\"#\"):\n # Handle heading\n newFile.write(line)\n\n if not done_title:\n done_title = True\n elif not done_toc and trimmed_line in \"\":\n # Skip empty lines until TOC is done\n continue\n elif trimmed_line.startswith(\"```\"):\n # Toggle whether we're in code\n\n # Write any saved text\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Write the current line as is\n newFile.write(line)\n\n # Track whether code block has started or ended\n if (in_code):\n in_code = False\n else:\n in_code = True\n elif re.search(\"^\\d.\", trimmed_line):\n # Handle an ordered list item\n\n # Write any saved text\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Start all ordered list items with 1.\n list_item_line = re.sub(\"\\d+.\\s*\", \"1. \", line, 1)\n\n prev_index = re.search(\"\\S\", line).start()\n elif trimmed_line.startswith(\"-\"):\n # Handle an unordered-list item starting with -\n\n # Write any saved text\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Start list items with '*' instead of '-', followed by a single space\n list_item_line = re.sub(\"-\\s*\", \"* \", line, 1)\n\n prev_index = re.search(\"\\S\", line).start()\n elif trimmed_line.startswith(\"* \"):\n # Handle an unordered-list item starting with *\n\n # Write any saved text\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Start list items with '*', followed by a single space\n list_item_line = re.sub(\"\\*\\s*\", \"* \", line, 1)\n\n prev_index = re.search(\"\\S\", line).start()\n elif re.search(\"^\\|\", line.strip()):\n\n if not re.search(\"^\\|.*\\|$\", line.strip()):\n\n # Handle a sidebar line\n\n # Write any saved text\n para_line = write_and_reset_string(para_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n pipe_index = re.search(\"|\", line).start()\n\n tmp_line = line.replace(\"| \", \"\", 1).strip()\n if tmp_line in \"\":\n prev_sidebar_line_empty = True\n sidebar_line += \"\\n\"\n else:\n\n # Replace the leading pipe with a space\n stripped_line = line.replace(\"| \", \"\", 1)\n\n if sidebar_line in \"\":\n\n # Start the sidebar\n\n if \"**Note:**\" in stripped_line:\n newFile.write(\"```{note}\\n\")\n stripped_line = stripped_line.replace(\"**Note:**\", \"\", 1)\n elif \"**Tip:**\" in stripped_line:\n newFile.write(\"```{tip}\\n\")\n stripped_line = stripped_line.replace(\"**Tip:**\", \"\", 1)\n elif \"**Warning:**\" in stripped_line:\n newFile.write(\"```{warning}\\n\")\n stripped_line = stripped_line.replace(\"**Warning:**\", \"\", 1)\n elif \"**Important:**\" in stripped_line:\n newFile.write(\"```{important}\\n\")\n stripped_line = stripped_line.replace(\"**Important:**\", \"\", 1)\n elif \"**Note**:\" in stripped_line:\n newFile.write(\"```{note}\\n\")\n stripped_line = stripped_line.replace(\"**Note**:\", \"\", 1)\n elif \"**Tip**:\" in stripped_line:\n newFile.write(\"```{tip}\\n\")\n stripped_line = stripped_line.replace(\"**Tip**:\", \"\", 1)\n elif \"**Warning**:\" in stripped_line:\n newFile.write(\"```{warning}\\n\")\n stripped_line = stripped_line.replace(\"**Warning**:\", \"\", 1)\n elif \"**Important**:\" in stripped_line:\n newFile.write(\"```{important}\\n\")\n stripped_line = stripped_line.replace(\"**Important**:\", \"\", 1)\n else:\n newFile.write(\"```{note}\\n\")\n\n if sidebar_line in \"\":\n sidebar_line = stripped_line.lstrip()\n else:\n if prev_sidebar_line_empty:\n sidebar_line = sidebar_line + stripped_line\n prev_sidebar_line_empty = False\n else:\n sidebar_line = sidebar_line.rstrip() + \" \" + stripped_line.lstrip()\n\n prev_index = re.search(\"\\S\", line).start()\n else:\n # Handle table line\n\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Write the table line\n newFile.write(line)\n elif in_code:\n\n # Write code line\n newFile.write(line)\n elif trimmed_line.startswith(\"[TOC\"):\n # Don't write anything for the legacy TOC line\n done_toc = True\n continue\n elif para_line != \"\":\n\n if re.search(\"^[\\d\\-]\", trimmed_line):\n # Write the existing paragraph and start a list item\n list_item_line = line\n\n para_line = write_and_reset_string(para_line, newFile)\n\n prev_index = re.search(\"\\S\", line).start()\n elif re.search(\"^[\\:]\", trimmed_line):\n\n # Write definition term\n newFile.write(para_line)\n\n # Start the term definition\n para_line = line\n\n prev_index = re.search(\"\\S\", line).start()\n elif re.search(\"^[\\w\\*\\@\\!\\(\\&\\.\\[\\`\\s(\\w\\*\\@\\!\\(\\&\\.\\[\\`)]\", trimmed_line):\n\n para_line = append_to_line(para_line, trimmed_line)\n else:\n\n # Write the existing paragraph and the current line\n para_line = write_and_reset_string(para_line, newFile)\n newFile.write(line)\n\n if re.search(\"\\S\", line):\n prev_index = re.search(\"\\S\", line).start()\n elif re.search(\"^[\\w\\*\\@\\!\\(\\&\\.\\[\\`\\s\\:(\\w\\*\\@\\!\\(\\&\\.\\[\\`)]\", trimmed_line):\n\n sidebar_line = end_sidebar(sidebar_line, newFile)\n\n if re.search(\"\\S\", line):\n index = re.search(\"\\S\", line).start()\n\n if index > prev_index:\n\n if list_item_line != \"\":\n list_item_line = append_to_line(list_item_line, line)\n elif (para_line != \"\"):\n para_line = append_to_line(para_line, line)\n else:\n para_line = line\n prev_index = index\n else:\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n para_line = line\n prev_index = index\n else:\n # Empty line\n\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Write the current line\n newFile.write(line)\n else:\n\n if not done_header_id and trimmed_line in \"\":\n # Skip writing empty lines before writing the title line\n continue\n else:\n # Set index to first non-space character\n if re.search(\"\\S\", line):\n prev_index = re.search(\"\\S\", line).start()\n\n\n para_line = write_and_reset_string(para_line, newFile)\n sidebar_line = end_sidebar(sidebar_line, newFile)\n list_item_line = write_and_reset_string(list_item_line, newFile)\n\n # Write the current line\n newFile.write(line)\n\n # Done looping through the lines\n\n # Finish writing the current paragraph, list item, or sidebar\n\n if para_line != \"\":\n newFile.write(para_line)\n elif list_item_line != \"\":\n newFile.write(list_item_line)\n elif sidebar_line != \"\":\n newFile.write(sidebar_line)\n\n newFile.close()"
},
{
"path": "bin/update-liferay-learn-links.sh",
"content": "#!/bin/bash\n\n# This script was inspired by the answers at\n# https://stackoverflow.com/questions/30724170/how-to-read-properties-file-using-shell-script\n\nredirects_file=~/redirects_all.properties\n\nif [ \"${#}\" -eq 0 ]\nthen\n echo \"Must input a properties file\"\n echo \"Usage: ./bin/update-liferay-learn_links.sh path/to/properties/file\"\n exit 1\nfi\n\nif [ \"${#}\" -ge 1 ]\nthen\n if [ ! -f ${1} ]\n then\n echo \"File ${1} does not exist.\"\n\n exit 1\n else\n redirects_file=${1}\n fi\nfi\n\necho \"Redirects file ${redirects_file}\"\n\n# Read configuration into an associative array\ndeclare -A REDIRECT\n\n# IFS is the 'internal field separator'. In this case, your file uses '='\nIFS=\"=\"\nwhile read -r key value\ndo\n if [ -n $value ]; then\n REDIRECT[$key]=$value\n else\n REDIRECT[$key]=$value\n fi\ndone < ${redirects_file}\nunset IFS\n\nfor file in `find . -type f -name \"*.markdown\"`\ndo\n if [ -n \"$(grep learn.liferay.com $(echo ${file}))\" ]\n then\n echo \"${file}\"\n\n for key in \"${!REDIRECT[@]}\"\n do\n sed -i s@$key@${REDIRECT[$key]}@g \"${file}\"\n done\n fi\ndone"
},
{
"path": "bin/update-markdown-sidebar-syntax-win.sh",
"content": "#!/bin/sh\n\ndevelopdir=\"../develop\"\ndistributedir=\"../distribute\"\nusedir=\"../use\"\n\nfor file in $(find $developdir -name \"*.markdown\")\ndo\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\r\\n\\+\\$\\$\\$\\r\\n\\r\\n/g' $file\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)/\\r\\n\\$\\$\\$\\r\\n/g' $file\ndone\n\nfor file in $(find $distributedir -name \"*.markdown\")\ndo\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\r\\n\\+\\$\\$\\$\\r\\n\\r\\n/g' $file\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)/\\r\\n\\$\\$\\$\\r\\n/g' $file\ndone\n\nfor file in $(find $usedir -name \"*.markdown\")\ndo\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\r\\n\\+\\$\\$\\$\\r\\n\\r\\n/g' $file\nperl -p0777i.bak -e 's/\\r\\n[ \\t]*---[ ]*(\\r\\n)/\\r\\n\\$\\$\\$\\r\\n/g' $file\ndone\n"
},
{
"path": "bin/update-markdown-sidebar-syntax.sh",
"content": "#!/bin/sh\n\ndevelopdir=\"../develop\"\ndistributedir=\"../distribute\"\nusedir=\"../use\"\n\nfor file in $(find $developdir -name \"*.markdown\")\ndo\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\n\\+\\$\\$\\$\\n\\n/g' $file\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n/\\n\\$\\$\\$\\n/g' $file\ndone\n\nfor file in $(find $distributedir -name \"*.markdown\")\ndo\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\n\\+\\$\\$\\$\\n\\n/g' $file\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n/\\n\\$\\$\\$\\n/g' $file\ndone\n\nfor file in $(find $usedir -name \"*.markdown\")\ndo\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n+[ ]*!\\[.*\\]\\(.*\\)[\\s]*/\\n\\+\\$\\$\\$\\n\\n/g' $file\nperl -p0777i -e 's/\\n[ \\t]*---[ ]*\\n/\\n\\$\\$\\$\\n/g' $file\ndone\n"
},
{
"path": "book/developer/appdev.aux",
"content": "\\relax \n\\providecommand{\\transparent@use}[1]{}\n\\providecommand\\hyper@newdestlabel[2]{}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {229}Application Development}{661}{chapter.229}\\protected@file@percent }\n\\newlabel{application-development}{{229}{661}{Application Development}{chapter.229}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.1}Getting Started with Liferay Development}{662}{section.229.1}\\protected@file@percent }\n\\newlabel{getting-started-with-liferay-development}{{229.1}{662}{Getting Started with Liferay Development}{section.229.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.2}Create Your Object Model and Database in One Shot}{662}{section.229.2}\\protected@file@percent }\n\\newlabel{create-your-object-model-and-database-in-one-shot}{{229.2}{662}{Create Your Object Model and Database in One Shot}{section.229.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.3}Create a REST Interface}{663}{section.229.3}\\protected@file@percent }\n\\newlabel{create-a-rest-interface}{{229.3}{663}{Create a REST Interface}{section.229.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.4}Create a Web Client}{663}{section.229.4}\\protected@file@percent }\n\\newlabel{create-a-web-client}{{229.4}{663}{Create a Web Client}{section.229.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.5}Use Liferay's Frameworks}{663}{section.229.5}\\protected@file@percent }\n\\newlabel{use-liferays-frameworks}{{229.5}{663}{Use Liferay's Frameworks}{section.229.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {229.6}Next Steps}{663}{section.229.6}\\protected@file@percent }\n\\newlabel{next-steps}{{229.6}{663}{Next Steps}{section.229.6}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {230}Developing Web Front-Ends}{665}{chapter.230}\\protected@file@percent }\n\\newlabel{developing-web-front-ends}{{230}{665}{Developing Web Front-Ends}{chapter.230}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {230.1}Using Popular Frameworks}{665}{section.230.1}\\protected@file@percent }\n\\newlabel{using-popular-frameworks}{{230.1}{665}{Using Popular Frameworks}{section.230.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {230.2}Getting Started}{666}{section.230.2}\\protected@file@percent }\n\\newlabel{getting-started}{{230.2}{666}{Getting Started}{section.230.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {231}Developing an Angular Application}{669}{chapter.231}\\protected@file@percent }\n\\newlabel{developing-an-angular-application}{{231}{669}{Developing an Angular Application}{chapter.231}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {231.1}{\\ignorespaces Apps like this Guestbook app are easy to migrate to Liferay DXP.}}{669}{figure.231.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {231.1}Related Topics}{673}{section.231.1}\\protected@file@percent }\n\\newlabel{related-topics}{{231.1}{673}{Related Topics}{section.231.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {232}Developing a React Application}{675}{chapter.232}\\protected@file@percent }\n\\newlabel{developing-a-react-application}{{232}{675}{Developing a React Application}{chapter.232}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {232.1}{\\ignorespaces Apps like this Guestbook app are easy to migrate to Liferay DXP.}}{675}{figure.232.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {232.1}Related Topics}{678}{section.232.1}\\protected@file@percent }\n\\newlabel{related-topics-1}{{232.1}{678}{Related Topics}{section.232.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {233}Developing a Vue Application}{679}{chapter.233}\\protected@file@percent }\n\\newlabel{developing-a-vue-application}{{233}{679}{Developing a Vue Application}{chapter.233}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {233.1}{\\ignorespaces Vue Apps like this Guestbook App are easy to deploy, and they look great in Liferay DXP.}}{680}{figure.233.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {233.1}Related Topics}{683}{section.233.1}\\protected@file@percent }\n\\newlabel{related-topics-2}{{233.1}{683}{Related Topics}{section.233.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {234}Liferay MVC Portlet}{685}{chapter.234}\\protected@file@percent }\n\\newlabel{liferay-mvc-portlet}{{234}{685}{Liferay MVC Portlet}{chapter.234}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {234.1}MVC Layers and Modularity}{685}{section.234.1}\\protected@file@percent }\n\\newlabel{mvc-layers-and-modularity}{{234.1}{685}{MVC Layers and Modularity}{section.234.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {234.2}Liferay MVC Command Classes}{686}{section.234.2}\\protected@file@percent }\n\\newlabel{liferay-mvc-command-classes}{{234.2}{686}{Liferay MVC Command Classes}{section.234.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {234.3}Liferay MVC Portlet Component}{686}{section.234.3}\\protected@file@percent }\n\\newlabel{liferay-mvc-portlet-component}{{234.3}{686}{Liferay MVC Portlet Component}{section.234.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {234.4}A Simpler MVC Portlet}{687}{section.234.4}\\protected@file@percent }\n\\newlabel{a-simpler-mvc-portlet}{{234.4}{687}{A Simpler MVC Portlet}{section.234.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {235}Creating an MVC Portlet}{689}{chapter.235}\\protected@file@percent }\n\\newlabel{creating-an-mvc-portlet}{{235}{689}{Creating an MVC Portlet}{chapter.235}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {235.1}{\\ignorespaces The example portlet shows a message defined by the language property \\texttt {yourmvc.caption=Hello\\ from\\ YourMVC!} in the Language.properties file.}}{691}{figure.235.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {235.1}Related Topics}{691}{section.235.1}\\protected@file@percent }\n\\newlabel{related-topics-3}{{235.1}{691}{Related Topics}{section.235.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {236}Writing MVC Portlet Controller Code}{693}{chapter.236}\\protected@file@percent }\n\\newlabel{writing-mvc-portlet-controller-code}{{236}{693}{Writing MVC Portlet Controller Code}{chapter.236}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {236.1}Action Methods}{693}{section.236.1}\\protected@file@percent }\n\\newlabel{action-methods}{{236.1}{693}{Action Methods}{section.236.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {236.2}Render Logic}{694}{section.236.2}\\protected@file@percent }\n\\newlabel{render-logic}{{236.2}{694}{Render Logic}{section.236.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {236.3}Setting and Retrieving Request and Response Parameters and Attributes}{695}{section.236.3}\\protected@file@percent }\n\\newlabel{setting-and-retrieving-request-and-response-parameters-and-attributes}{{236.3}{695}{Setting and Retrieving Request and Response Parameters and Attributes}{section.236.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {236.4}Related Topics}{696}{section.236.4}\\protected@file@percent }\n\\newlabel{related-topics-4}{{236.4}{696}{Related Topics}{section.236.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {237}Configuring the View Layer}{697}{chapter.237}\\protected@file@percent }\n\\newlabel{configuring-the-view-layer}{{237}{697}{Configuring the View Layer}{chapter.237}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {237.1}Using the init.jsp}{697}{section.237.1}\\protected@file@percent }\n\\newlabel{using-the-init.jsp}{{237.1}{697}{Using the init.jsp}{section.237.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {237.2}Using Render URLs}{698}{section.237.2}\\protected@file@percent }\n\\newlabel{using-render-urls}{{237.2}{698}{Using Render URLs}{section.237.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {237.3}Using Action URLs}{699}{section.237.3}\\protected@file@percent }\n\\newlabel{using-action-urls}{{237.3}{699}{Using Action URLs}{section.237.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {237.4}Related Topics}{699}{section.237.4}\\protected@file@percent }\n\\newlabel{related-topics-5}{{237.4}{699}{Related Topics}{section.237.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {238}MVC Action Command}{701}{chapter.238}\\protected@file@percent }\n\\newlabel{mvc-action-command}{{238}{701}{MVC Action Command}{chapter.238}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {238.1}Related Topics}{703}{section.238.1}\\protected@file@percent }\n\\newlabel{related-topics-6}{{238.1}{703}{Related Topics}{section.238.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {239}MVC Render Command}{705}{chapter.239}\\protected@file@percent }\n\\newlabel{mvc-render-command}{{239}{705}{MVC Render Command}{chapter.239}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {239.1}Related Topics}{706}{section.239.1}\\protected@file@percent }\n\\newlabel{related-topics-7}{{239.1}{706}{Related Topics}{section.239.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {240}MVC Resource Command}{707}{chapter.240}\\protected@file@percent }\n\\newlabel{mvc-resource-command}{{240}{707}{MVC Resource Command}{chapter.240}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {240.1}Related Topics}{709}{section.240.1}\\protected@file@percent }\n\\newlabel{related-topics-8}{{240.1}{709}{Related Topics}{section.240.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {241}PortletMVC4Spring}{711}{chapter.241}\\protected@file@percent }\n\\newlabel{portletmvc4spring}{{241}{711}{PortletMVC4Spring}{chapter.241}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {241.1}{\\ignorespaces This PortletMVC4Spring portlet enables users to enter job applications. It uses the Spring features mentioned above and handles requests from multiple portlet phases.}}{712}{figure.241.1}\\protected@file@percent }\n\\gdef \\LT@xii {\\LT@entry \n {1}{234.8775pt}\\LT@entry \n {1}{234.8775pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {242}Developing a Portlet Using PortletMVC4Spring}{715}{chapter.242}\\protected@file@percent }\n\\newlabel{developing-a-portlet-using-portletmvc4spring}{{242}{715}{Developing a Portlet Using PortletMVC4Spring}{chapter.242}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {242.1}{\\ignorespaces The archetype's sample portlet prints a greeting (e.g., \\emph {Hello, Joe Bloggs}) on submitting a first and last name.}}{715}{figure.242.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {242.1}Related Topics}{719}{section.242.1}\\protected@file@percent }\n\\newlabel{related-topics-9}{{242.1}{719}{Related Topics}{section.242.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {243}Migrating to PortletMVC4Spring}{721}{chapter.243}\\protected@file@percent }\n\\newlabel{migrating-to-portletmvc4spring}{{243}{721}{Migrating to PortletMVC4Spring}{chapter.243}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {243.1}Related Topics}{722}{section.243.1}\\protected@file@percent }\n\\newlabel{related-topics-10}{{243.1}{722}{Related Topics}{section.243.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {244}JSF Portlet}{723}{chapter.244}\\protected@file@percent }\n\\newlabel{jsf-portlet}{{244}{723}{JSF Portlet}{chapter.244}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {245}Developing a JSF Portlet Application}{725}{chapter.245}\\protected@file@percent }\n\\newlabel{developing-a-jsf-portlet-application}{{245}{725}{Developing a JSF Portlet Application}{chapter.245}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {246}Bean Portlet}{729}{chapter.246}\\protected@file@percent }\n\\newlabel{bean-portlet}{{246}{729}{Bean Portlet}{chapter.246}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {246.1}Portlet Configuration Annotations}{729}{section.246.1}\\protected@file@percent }\n\\newlabel{portlet-configuration-annotations}{{246.1}{729}{Portlet Configuration Annotations}{section.246.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {246.2}Dependency Injection}{730}{section.246.2}\\protected@file@percent }\n\\newlabel{dependency-injection}{{246.2}{730}{Dependency Injection}{section.246.2}{}}\n\\gdef \\LT@xiii {\\LT@entry \n {1}{287.70345pt}\\LT@entry \n {1}{182.05156pt}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {246.3}Portlet Phase Methods}{731}{section.246.3}\\protected@file@percent }\n\\newlabel{portlet-phase-methods}{{246.3}{731}{Portlet Phase Methods}{section.246.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {247}Creating a Bean Portlet}{733}{chapter.247}\\protected@file@percent }\n\\newlabel{creating-a-bean-portlet}{{247}{733}{Creating a Bean Portlet}{chapter.247}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {247.1}{\\ignorespaces The Foo portlet prints the message returned from \\texttt {doView} method and shows the included JSP's contents.}}{735}{figure.247.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {247.1}Related Topics}{735}{section.247.1}\\protected@file@percent }\n\\newlabel{related-topics-11}{{247.1}{735}{Related Topics}{section.247.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {248}Service Builder}{737}{chapter.248}\\protected@file@percent }\n\\newlabel{service-builder}{{248}{737}{Service Builder}{chapter.248}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {248.1}Customization via Implementation Classes}{738}{section.248.1}\\protected@file@percent }\n\\newlabel{customization-via-implementation-classes}{{248.1}{738}{Customization via Implementation Classes}{section.248.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {248.2}Hibernate Configurations}{738}{section.248.2}\\protected@file@percent }\n\\newlabel{hibernate-configurations}{{248.2}{738}{Hibernate Configurations}{section.248.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {248.3}Caching}{738}{section.248.3}\\protected@file@percent }\n\\newlabel{caching}{{248.3}{738}{Caching}{section.248.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {248.4}Dynamic Query and Custom SQL Query}{738}{section.248.4}\\protected@file@percent }\n\\newlabel{dynamic-query-and-custom-sql-query}{{248.4}{738}{Dynamic Query and Custom SQL Query}{section.248.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {249}Creating a Service Builder Project}{741}{chapter.249}\\protected@file@percent }\n\\newlabel{creating-a-service-builder-project}{{249}{741}{Creating a Service Builder Project}{chapter.249}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {249.1}Related Topics}{742}{section.249.1}\\protected@file@percent }\n\\newlabel{related-topics-12}{{249.1}{742}{Related Topics}{section.249.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {250}Creating the service.xml File}{743}{chapter.250}\\protected@file@percent }\n\\newlabel{creating-the-service.xml-file}{{250}{743}{Creating the service.xml File}{chapter.250}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {251}Defining Global Service Information}{745}{chapter.251}\\protected@file@percent }\n\\newlabel{defining-global-service-information}{{251}{745}{Defining Global Service Information}{chapter.251}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {251.1}Dependency Injector}{745}{section.251.1}\\protected@file@percent }\n\\newlabel{dependency-injector}{{251.1}{745}{Dependency Injector}{section.251.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {251.2}Package Path}{746}{section.251.2}\\protected@file@percent }\n\\newlabel{package-path}{{251.2}{746}{Package Path}{section.251.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {251.3}Multiversion concurrency control (MVCC)}{746}{section.251.3}\\protected@file@percent }\n\\newlabel{multiversion-concurrency-control-mvcc}{{251.3}{746}{Multiversion concurrency control (MVCC)}{section.251.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {251.4}Namespace Options}{747}{section.251.4}\\protected@file@percent }\n\\newlabel{namespace-options}{{251.4}{747}{Namespace Options}{section.251.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {251.5}Author}{747}{section.251.5}\\protected@file@percent }\n\\newlabel{author}{{251.5}{747}{Author}{section.251.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {252}Defining Service Entities}{749}{chapter.252}\\protected@file@percent }\n\\newlabel{defining-service-entities}{{252}{749}{Defining Service Entities}{chapter.252}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {253}Defining the Columns (Attributes) for Each Service Entity}{751}{chapter.253}\\protected@file@percent }\n\\newlabel{defining-the-columns-attributes-for-each-service-entity}{{253}{751}{Defining the Columns (Attributes) for Each Service Entity}{chapter.253}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {253.1}Create Entity Columns}{751}{section.253.1}\\protected@file@percent }\n\\newlabel{create-entity-columns}{{253.1}{751}{Create Entity Columns}{section.253.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {253.2}Support Multi-tenancy}{752}{section.253.2}\\protected@file@percent }\n\\newlabel{support-multi-tenancy}{{253.2}{752}{Support Multi-tenancy}{section.253.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {253.3}Workflow Fields}{752}{section.253.3}\\protected@file@percent }\n\\newlabel{workflow-fields}{{253.3}{752}{Workflow Fields}{section.253.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {253.4}Audit Entities}{752}{section.253.4}\\protected@file@percent }\n\\newlabel{audit-entities}{{253.4}{752}{Audit Entities}{section.253.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {254}Defining Relationships Between Service Entities}{753}{chapter.254}\\protected@file@percent }\n\\newlabel{defining-relationships-between-service-entities}{{254}{753}{Defining Relationships Between Service Entities}{chapter.254}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {254.1}{\\ignorespaces Relating entities is a snap in Liferay Dev Studio DXP's \\emph {Diagram} mode for \\texttt {service.xml}.}}{754}{figure.254.1}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {255}Defining Ordering of Service Entity Instances}{755}{chapter.255}\\protected@file@percent }\n\\newlabel{defining-ordering-of-service-entity-instances}{{255}{755}{Defining Ordering of Service Entity Instances}{chapter.255}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {256}Defining Service Entity Finder Methods}{757}{chapter.256}\\protected@file@percent }\n\\newlabel{defining-service-entity-finder-methods}{{256}{757}{Defining Service Entity Finder Methods}{chapter.256}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {256.1}Creating Finders}{757}{section.256.1}\\protected@file@percent }\n\\newlabel{creating-finders}{{256.1}{757}{Creating Finders}{section.256.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {257}Running Service Builder}{759}{chapter.257}\\protected@file@percent }\n\\newlabel{running-service-builder}{{257}{759}{Running Service Builder}{chapter.257}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {257.1}Gradle}{759}{section.257.1}\\protected@file@percent }\n\\newlabel{gradle}{{257.1}{759}{Gradle}{section.257.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {257.2}Maven}{759}{section.257.2}\\protected@file@percent }\n\\newlabel{maven}{{257.2}{759}{Maven}{section.257.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {258}Understanding the Code Generated by Service Builder}{761}{chapter.258}\\protected@file@percent }\n\\newlabel{understanding-the-code-generated-by-service-builder}{{258}{761}{Understanding the Code Generated by Service Builder}{chapter.258}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {258.1}{\\ignorespaces Service Builder generates these persistence classes and interfaces for an example entity called \\emph {Event}. You shouldn't (and you won't need to) customize any of these classes or interfaces.}}{762}{figure.258.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {258.2}{\\ignorespaces Service Builder generates these service classes and interfaces. Only the {[}ENTITY\\_NAME{]}LocalServiceImpl (e.g., EventLocalServiceImpl for the Event entity) allows custom methods to be added to the service layer.}}{763}{figure.258.2}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {258.3}{\\ignorespaces Service Builder generates these model classes and interfaces. Only \\texttt {{[}ENTITY\\_NAME{]}Impl} (e.g., \\texttt {EventImpl} for the Event entity) allows custom methods to be added to the service layer.}}{765}{figure.258.3}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {259}Iterative Development}{767}{chapter.259}\\protected@file@percent }\n\\newlabel{iterative-development}{{259}{767}{Iterative Development}{chapter.259}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {259.1}Related Topics}{767}{section.259.1}\\protected@file@percent }\n\\newlabel{related-topics-13}{{259.1}{767}{Related Topics}{section.259.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {260}Customizing Model Entities With Model Hints}{769}{chapter.260}\\protected@file@percent }\n\\newlabel{customizing-model-entities-with-model-hints}{{260}{769}{Customizing Model Entities With Model Hints}{chapter.260}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {260.1}Model Hint Types}{771}{section.260.1}\\protected@file@percent }\n\\newlabel{model-hint-types}{{260.1}{771}{Model Hint Types}{section.260.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {260.2}Default Hints}{771}{section.260.2}\\protected@file@percent }\n\\newlabel{default-hints}{{260.2}{771}{Default Hints}{section.260.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {260.3}Hint Collections}{772}{section.260.3}\\protected@file@percent }\n\\newlabel{hint-collections}{{260.3}{772}{Hint Collections}{section.260.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {261}Configuring service.properties}{775}{chapter.261}\\protected@file@percent }\n\\newlabel{configuring-service.properties}{{261}{775}{Configuring service.properties}{chapter.261}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {261.1}Related Topics}{775}{section.261.1}\\protected@file@percent }\n\\newlabel{related-topics-14}{{261.1}{775}{Related Topics}{section.261.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {262}Connecting Service Builder to an External Database}{777}{chapter.262}\\protected@file@percent }\n\\newlabel{connecting-service-builder-to-an-external-database}{{262}{777}{Connecting Service Builder to an External Database}{chapter.262}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {263}Connecting the Data Source Using a DataSourceProvider}{779}{chapter.263}\\protected@file@percent }\n\\newlabel{connecting-the-data-source-using-a-datasourceprovider}{{263}{779}{Connecting the Data Source Using a DataSourceProvider}{chapter.263}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {263.1}Related Topics}{781}{section.263.1}\\protected@file@percent }\n\\newlabel{related-topics-15}{{263.1}{781}{Related Topics}{section.263.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {264}Connecting the Data Source Using Spring Beans}{783}{chapter.264}\\protected@file@percent }\n\\newlabel{connecting-the-data-source-using-spring-beans}{{264}{783}{Connecting the Data Source Using Spring Beans}{chapter.264}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.1}Specify Your Database and a Data Source Name in Your \\texttt {service.xml}}{784}{section.264.1}\\protected@file@percent }\n\\newlabel{specify-your-database-and-a-data-source-name-in-your-service.xml}{{264.1}{784}{\\texorpdfstring {Specify Your Database and a Data Source Name in Your \\texttt {service.xml}}{Specify Your Database and a Data Source Name in Your service.xml}}{section.264.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.2}Create the Database Manually}{784}{section.264.2}\\protected@file@percent }\n\\newlabel{create-the-database-manually}{{264.2}{784}{Create the Database Manually}{section.264.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.3}Define the Data Source}{784}{section.264.3}\\protected@file@percent }\n\\newlabel{define-the-data-source}{{264.3}{784}{Define the Data Source}{section.264.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.4}Connect Your Service Builder Module to the Data Source Via a Spring Bean}{784}{section.264.4}\\protected@file@percent }\n\\newlabel{connect-your-service-builder-module-to-the-data-source-via-a-spring-bean}{{264.4}{784}{Connect Your Service Builder Module to the Data Source Via a Spring Bean}{section.264.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.5}Run Service Builder}{786}{section.264.5}\\protected@file@percent }\n\\newlabel{run-service-builder}{{264.5}{786}{Run Service Builder}{section.264.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {264.6}Related Topics}{786}{section.264.6}\\protected@file@percent }\n\\newlabel{related-topics-16}{{264.6}{786}{Related Topics}{section.264.6}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {265}Migrating a Service Builder Module from Spring DI to OSGi DS}{787}{chapter.265}\\protected@file@percent }\n\\newlabel{migrating-a-service-builder-module-from-spring-di-to-osgi-ds}{{265}{787}{Migrating a Service Builder Module from Spring DI to OSGi DS}{chapter.265}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {265.1}Step 1: Prepare Your Project for DS}{787}{section.265.1}\\protected@file@percent }\n\\newlabel{step-1-prepare-your-project-for-ds}{{265.1}{787}{Step 1: Prepare Your Project for DS}{section.265.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {265.2}Step 2: Update Your Spring Bean Classes}{788}{section.265.2}\\protected@file@percent }\n\\newlabel{step-2-update-your-spring-bean-classes}{{265.2}{788}{Step 2: Update Your Spring Bean Classes}{section.265.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {265.3}Step 3: Resolve Any Circular Dependencies}{789}{section.265.3}\\protected@file@percent }\n\\newlabel{step-3-resolve-any-circular-dependencies}{{265.3}{789}{Step 3: Resolve Any Circular Dependencies}{section.265.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {265.4}Related Topics}{790}{section.265.4}\\protected@file@percent }\n\\newlabel{related-topics-17}{{265.4}{790}{Related Topics}{section.265.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {266}Business Logic with Service Builder}{791}{chapter.266}\\protected@file@percent }\n\\newlabel{business-logic-with-service-builder}{{266}{791}{Business Logic with Service Builder}{chapter.266}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {267}Implementing an Add Method}{793}{chapter.267}\\protected@file@percent }\n\\newlabel{implementing-an-add-method}{{267}{793}{Implementing an Add Method}{chapter.267}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.1}Step 1: Declare an add method with parameters for creating the entity}{794}{section.267.1}\\protected@file@percent }\n\\newlabel{step-1-declare-an-add-method-with-parameters-for-creating-the-entity}{{267.1}{794}{Step 1: Declare an add method with parameters for creating the entity}{section.267.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.2}Step 2: Validate the parameters}{795}{section.267.2}\\protected@file@percent }\n\\newlabel{step-2-validate-the-parameters}{{267.2}{795}{Step 2: Validate the parameters}{section.267.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.3}Step 3: Generate a primary key}{795}{section.267.3}\\protected@file@percent }\n\\newlabel{step-3-generate-a-primary-key}{{267.3}{795}{Step 3: Generate a primary key}{section.267.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.4}Step 4: Create an entity instance}{795}{section.267.4}\\protected@file@percent }\n\\newlabel{step-4-create-an-entity-instance}{{267.4}{795}{Step 4: Create an entity instance}{section.267.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.5}Step 5: Populate the entity attributes}{796}{section.267.5}\\protected@file@percent }\n\\newlabel{step-5-populate-the-entity-attributes}{{267.5}{796}{Step 5: Populate the entity attributes}{section.267.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.6}Step 6: Persist the entity}{796}{section.267.6}\\protected@file@percent }\n\\newlabel{step-6-persist-the-entity}{{267.6}{796}{Step 6: Persist the entity}{section.267.6}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {267.7}Step 7: Return the entity}{796}{section.267.7}\\protected@file@percent }\n\\newlabel{step-7-return-the-entity}{{267.7}{796}{Step 7: Return the entity}{section.267.7}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {268}Implementing Update and Delete Methods}{797}{chapter.268}\\protected@file@percent }\n\\newlabel{implementing-update-and-delete-methods}{{268}{797}{Implementing Update and Delete Methods}{chapter.268}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.1}Implementing an Update Method}{797}{section.268.1}\\protected@file@percent }\n\\newlabel{implementing-an-update-method}{{268.1}{797}{Implementing an Update Method}{section.268.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.2}Step 1: Declare an Update Method with Parameters for Updating the Entity}{798}{section.268.2}\\protected@file@percent }\n\\newlabel{step-1-declare-an-update-method-with-parameters-for-updating-the-entity}{{268.2}{798}{Step 1: Declare an Update Method with Parameters for Updating the Entity}{section.268.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.3}Step 2: Validate the Parameters}{798}{section.268.3}\\protected@file@percent }\n\\newlabel{step-2-validate-the-parameters-1}{{268.3}{798}{Step 2: Validate the Parameters}{section.268.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.4}Step 3: Retrieve the Entity Instance}{799}{section.268.4}\\protected@file@percent }\n\\newlabel{step-3-retrieve-the-entity-instance}{{268.4}{799}{Step 3: Retrieve the Entity Instance}{section.268.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.5}Step 4: Update the Entity Attributes}{799}{section.268.5}\\protected@file@percent }\n\\newlabel{step-4-update-the-entity-attributes}{{268.5}{799}{Step 4: Update the Entity Attributes}{section.268.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.6}Step 5: Persist and Return the Updated Entity Instance}{799}{section.268.6}\\protected@file@percent }\n\\newlabel{step-5-persist-and-return-the-updated-entity-instance}{{268.6}{799}{Step 5: Persist and Return the Updated Entity Instance}{section.268.6}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.7}Step 6: Run Service Builder}{799}{section.268.7}\\protected@file@percent }\n\\newlabel{step-6-run-service-builder}{{268.7}{799}{Step 6: Run Service Builder}{section.268.7}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.8}Implementing a Delete Method}{799}{section.268.8}\\protected@file@percent }\n\\newlabel{implementing-a-delete-method}{{268.8}{799}{Implementing a Delete Method}{section.268.8}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {268.9}Related Topics}{800}{section.268.9}\\protected@file@percent }\n\\newlabel{related-topics-18}{{268.9}{800}{Related Topics}{section.268.9}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {269}Implementing Methods to Get and Count Entities}{801}{chapter.269}\\protected@file@percent }\n\\newlabel{implementing-methods-to-get-and-count-entities}{{269}{801}{Implementing Methods to Get and Count Entities}{chapter.269}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {269.1}Getter Methods}{801}{section.269.1}\\protected@file@percent }\n\\newlabel{getter-methods}{{269.1}{801}{Getter Methods}{section.269.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {269.2}Counter Methods}{802}{section.269.2}\\protected@file@percent }\n\\newlabel{counter-methods}{{269.2}{802}{Counter Methods}{section.269.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {269.3}Service Method Prefixes and Transactional Aspects}{803}{section.269.3}\\protected@file@percent }\n\\newlabel{service-method-prefixes-and-transactional-aspects}{{269.3}{803}{Service Method Prefixes and Transactional Aspects}{section.269.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {269.4}Related Topics}{804}{section.269.4}\\protected@file@percent }\n\\newlabel{related-topics-19}{{269.4}{804}{Related Topics}{section.269.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {270}Implementing Any Other Business Logic}{805}{chapter.270}\\protected@file@percent }\n\\newlabel{implementing-any-other-business-logic}{{270}{805}{Implementing Any Other Business Logic}{chapter.270}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {271}Integrating with Liferay's Frameworks}{807}{chapter.271}\\protected@file@percent }\n\\newlabel{integrating-with-liferays-frameworks}{{271}{807}{Integrating with Liferay's Frameworks}{chapter.271}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {271.1}Related Topics}{808}{section.271.1}\\protected@file@percent }\n\\newlabel{related-topics-20}{{271.1}{808}{Related Topics}{section.271.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {272}Invoking Local Services}{809}{chapter.272}\\protected@file@percent }\n\\newlabel{invoking-local-services}{{272}{809}{Invoking Local Services}{chapter.272}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {272.1}Step 1: Reference the Local Service Component}{809}{section.272.1}\\protected@file@percent }\n\\newlabel{step-1-reference-the-local-service-component}{{272.1}{809}{Step 1: Reference the Local Service Component}{section.272.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {272.2}Step 2: Call the Component's Methods}{810}{section.272.2}\\protected@file@percent }\n\\newlabel{step-2-call-the-components-methods}{{272.2}{810}{Step 2: Call the Component's Methods}{section.272.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {272.3}Related Topics}{811}{section.272.3}\\protected@file@percent }\n\\newlabel{related-topics-21}{{272.3}{811}{Related Topics}{section.272.3}{}}\n\\gdef \\LT@xiv {\\LT@entry \n {1}{194.50543pt}\\LT@entry \n {1}{275.24957pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {273}Invoking Services from Spring Service Builder Code}{813}{chapter.273}\\protected@file@percent }\n\\newlabel{invoking-services-from-spring-service-builder-code}{{273}{813}{Invoking Services from Spring Service Builder Code}{chapter.273}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {273.1}Referencing a Spring Bean that is in the Application Context}{814}{section.273.1}\\protected@file@percent }\n\\newlabel{referencing-a-spring-bean-that-is-in-the-application-context}{{273.1}{814}{Referencing a Spring Bean that is in the Application Context}{section.273.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {273.2}Referencing OSGi Services}{814}{section.273.2}\\protected@file@percent }\n\\newlabel{referencing-osgi-services}{{273.2}{814}{Referencing OSGi Services}{section.273.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {273.3}Related Topics}{815}{section.273.3}\\protected@file@percent }\n\\newlabel{related-topics-22}{{273.3}{815}{Related Topics}{section.273.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {274}Advanced Queries}{817}{chapter.274}\\protected@file@percent }\n\\newlabel{advanced-queries}{{274}{817}{Advanced Queries}{chapter.274}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {275}Custom SQL}{819}{chapter.275}\\protected@file@percent }\n\\newlabel{custom-sql}{{275}{819}{Custom SQL}{chapter.275}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {275.1}Specify Your Custom SQL}{819}{section.275.1}\\protected@file@percent }\n\\newlabel{specify-your-custom-sql}{{275.1}{819}{Specify Your Custom SQL}{section.275.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {275.2}Related Topics}{820}{section.275.2}\\protected@file@percent }\n\\newlabel{related-topics-23}{{275.2}{820}{Related Topics}{section.275.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {276}Defining a Custom Finder Method}{821}{chapter.276}\\protected@file@percent }\n\\newlabel{defining-a-custom-finder-method}{{276}{821}{Defining a Custom Finder Method}{chapter.276}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {277}Dynamic Query}{823}{chapter.277}\\protected@file@percent }\n\\newlabel{dynamic-query}{{277}{823}{Dynamic Query}{chapter.277}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.1}Example Finder Method: findByGuestbookNameEntryName}{823}{section.277.1}\\protected@file@percent }\n\\newlabel{example-finder-method-findbyguestbooknameentryname}{{277.1}{823}{Example Finder Method: findByGuestbookNameEntryName}{section.277.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.2}Using a Hibernate Session}{825}{section.277.2}\\protected@file@percent }\n\\newlabel{using-a-hibernate-session}{{277.2}{825}{Using a Hibernate Session}{section.277.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.3}Creating Dynamic Queries}{826}{section.277.3}\\protected@file@percent }\n\\newlabel{creating-dynamic-queries}{{277.3}{826}{Creating Dynamic Queries}{section.277.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.4}Restriction Criteria}{826}{section.277.4}\\protected@file@percent }\n\\newlabel{restriction-criteria}{{277.4}{826}{Restriction Criteria}{section.277.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.5}Projection Criteria}{827}{section.277.5}\\protected@file@percent }\n\\newlabel{projection-criteria}{{277.5}{827}{Projection Criteria}{section.277.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.6}Order Criteria}{827}{section.277.6}\\protected@file@percent }\n\\newlabel{order-criteria}{{277.6}{827}{Order Criteria}{section.277.6}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {277.7}Executing the Dynamic Query}{828}{section.277.7}\\protected@file@percent }\n\\newlabel{executing-the-dynamic-query}{{277.7}{828}{Executing the Dynamic Query}{section.277.7}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {278}Accessing Your Custom Finder Method from the Service Layer}{829}{chapter.278}\\protected@file@percent }\n\\newlabel{accessing-your-custom-finder-method-from-the-service-layer}{{278}{829}{Accessing Your Custom Finder Method from the Service Layer}{chapter.278}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {278.1}Related Topics}{830}{section.278.1}\\protected@file@percent }\n\\newlabel{related-topics-24}{{278.1}{830}{Related Topics}{section.278.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {279}Actionable Dynamic Queries}{831}{chapter.279}\\protected@file@percent }\n\\newlabel{actionable-dynamic-queries}{{279}{831}{Actionable Dynamic Queries}{chapter.279}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {279.1}Related Topics}{833}{section.279.1}\\protected@file@percent }\n\\newlabel{related-topics-25}{{279.1}{833}{Related Topics}{section.279.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {280}REST Builder}{835}{chapter.280}\\protected@file@percent }\n\\newlabel{rest-builder}{{280}{835}{REST Builder}{chapter.280}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {281}Generating APIs with REST Builder}{837}{chapter.281}\\protected@file@percent }\n\\newlabel{generating-apis-with-rest-builder}{{281}{837}{Generating APIs with REST Builder}{chapter.281}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {281.1}Related Topics}{838}{section.281.1}\\protected@file@percent }\n\\newlabel{related-topics-26}{{281.1}{838}{Related Topics}{section.281.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {282}Troubleshooting Application Development Issues}{839}{chapter.282}\\protected@file@percent }\n\\newlabel{troubleshooting-application-development-issues}{{282}{839}{Troubleshooting Application Development Issues}{chapter.282}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {282.1}Modules}{839}{section.282.1}\\protected@file@percent }\n\\newlabel{modules}{{282.1}{839}{Modules}{section.282.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {282.2}Services and Components}{840}{section.282.2}\\protected@file@percent }\n\\newlabel{services-and-components}{{282.2}{840}{Services and Components}{section.282.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {283}Adjusting Module Logging}{841}{chapter.283}\\protected@file@percent }\n\\newlabel{adjusting-module-logging}{{283}{841}{Adjusting Module Logging}{chapter.283}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {283.1}Related Topics}{842}{section.283.1}\\protected@file@percent }\n\\newlabel{related-topics-27}{{283.1}{842}{Related Topics}{section.283.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {284}Identifying Liferay Artifact Versions for Dependencies}{843}{chapter.284}\\protected@file@percent }\n\\newlabel{identifying-liferay-artifact-versions-for-dependencies}{{284}{843}{Identifying Liferay Artifact Versions for Dependencies}{chapter.284}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {284.1}Related Topics}{843}{section.284.1}\\protected@file@percent }\n\\newlabel{related-topics-28}{{284.1}{843}{Related Topics}{section.284.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {285}Resolving Bundle-SymbolicName Syntax Issues}{845}{chapter.285}\\protected@file@percent }\n\\newlabel{resolving-bundle-symbolicname-syntax-issues}{{285}{845}{Resolving Bundle-SymbolicName Syntax Issues}{chapter.285}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {285.1}Related Topics}{845}{section.285.1}\\protected@file@percent }\n\\newlabel{related-topics-29}{{285.1}{845}{Related Topics}{section.285.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {286}Calling Non-OSGi Code that Uses OSGi Services}{847}{chapter.286}\\protected@file@percent }\n\\newlabel{calling-non-osgi-code-that-uses-osgi-services}{{286}{847}{Calling Non-OSGi Code that Uses OSGi Services}{chapter.286}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {286.1}Related Topics}{847}{section.286.1}\\protected@file@percent }\n\\newlabel{related-topics-30}{{286.1}{847}{Related Topics}{section.286.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {287}Connecting to JNDI Data Sources}{849}{chapter.287}\\protected@file@percent }\n\\newlabel{connecting-to-jndi-data-sources}{{287}{849}{Connecting to JNDI Data Sources}{chapter.287}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {288}Detecting Unresolved OSGi Components}{851}{chapter.288}\\protected@file@percent }\n\\newlabel{detecting-unresolved-osgi-components}{{288}{851}{Detecting Unresolved OSGi Components}{chapter.288}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.1}Declarative Services Components}{851}{section.288.1}\\protected@file@percent }\n\\newlabel{declarative-services-components}{{288.1}{851}{Declarative Services Components}{section.288.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.2}Declarative Services Unsatisfied Component Scanner}{852}{section.288.2}\\protected@file@percent }\n\\newlabel{declarative-services-unsatisfied-component-scanner}{{288.2}{852}{Declarative Services Unsatisfied Component Scanner}{section.288.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.3}ds:unsatisfied Command}{852}{section.288.3}\\protected@file@percent }\n\\newlabel{dsunsatisfied-command}{{288.3}{852}{ds:unsatisfied Command}{section.288.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.4}Service Builder Components}{853}{section.288.4}\\protected@file@percent }\n\\newlabel{service-builder-components}{{288.4}{853}{Service Builder Components}{section.288.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.5}Unavailable Component Scanner}{853}{section.288.5}\\protected@file@percent }\n\\newlabel{unavailable-component-scanner}{{288.5}{853}{Unavailable Component Scanner}{section.288.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.6}dm na Command}{854}{section.288.6}\\protected@file@percent }\n\\newlabel{dm-na-command}{{288.6}{854}{dm na Command}{section.288.6}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.7}ServiceProxyFactory}{854}{section.288.7}\\protected@file@percent }\n\\newlabel{serviceproxyfactory}{{288.7}{854}{ServiceProxyFactory}{section.288.7}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {288.8}Related Topics}{854}{section.288.8}\\protected@file@percent }\n\\newlabel{related-topics-31}{{288.8}{854}{Related Topics}{section.288.8}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {289}Disabling Cache for Table Mapper Tables}{855}{chapter.289}\\protected@file@percent }\n\\newlabel{disabling-cache-for-table-mapper-tables}{{289}{855}{Disabling Cache for Table Mapper Tables}{chapter.289}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {289.1}Why would I want to disable cache on a table mapper?}{855}{section.289.1}\\protected@file@percent }\n\\newlabel{why-would-i-want-to-disable-cache-on-a-table-mapper}{{289.1}{855}{Why would I want to disable cache on a table mapper?}{section.289.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {289.2}Disabling a Table Mapper Cache}{856}{section.289.2}\\protected@file@percent }\n\\newlabel{disabling-a-table-mapper-cache}{{289.2}{856}{Disabling a Table Mapper Cache}{section.289.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {290}Implementing Logging}{857}{chapter.290}\\protected@file@percent }\n\\newlabel{implementing-logging}{{290}{857}{Implementing Logging}{chapter.290}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {290.1}Related Topics}{858}{section.290.1}\\protected@file@percent }\n\\newlabel{related-topics-32}{{290.1}{858}{Related Topics}{section.290.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {291}Declaring Optional Import Package Requirements}{859}{chapter.291}\\protected@file@percent }\n\\newlabel{declaring-optional-import-package-requirements}{{291}{859}{Declaring Optional Import Package Requirements}{chapter.291}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {291.1}Related Topics}{860}{section.291.1}\\protected@file@percent }\n\\newlabel{related-topics-33}{{291.1}{860}{Related Topics}{section.291.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {292}Resolving Bundle Requirements}{861}{chapter.292}\\protected@file@percent }\n\\newlabel{resolving-bundle-requirements}{{292}{861}{Resolving Bundle Requirements}{chapter.292}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {292.1}Related Topics}{862}{section.292.1}\\protected@file@percent }\n\\newlabel{related-topics-34}{{292.1}{862}{Related Topics}{section.292.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {293}Resolving ClassNotFoundException and NoClassDefFoundError in OSGi Bundles}{863}{chapter.293}\\protected@file@percent }\n\\newlabel{resolving-classnotfoundexception-and-noclassdeffounderror-in-osgi-bundles}{{293}{863}{Resolving ClassNotFoundException and NoClassDefFoundError in OSGi Bundles}{chapter.293}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {293.1}Case 1: The Missing Class Belongs to an OSGi Module}{863}{section.293.1}\\protected@file@percent }\n\\newlabel{case-1-the-missing-class-belongs-to-an-osgi-module}{{293.1}{863}{Case 1: The Missing Class Belongs to an OSGi Module}{section.293.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {293.2}Case 2: The Missing Class Doesn't Belong to an OSGi Module}{864}{section.293.2}\\protected@file@percent }\n\\newlabel{case-2-the-missing-class-doesnt-belong-to-an-osgi-module}{{293.2}{864}{Case 2: The Missing Class Doesn't Belong to an OSGi Module}{section.293.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {293.3}Case 3: The Missing Class Belongs to a Global Library}{864}{section.293.3}\\protected@file@percent }\n\\newlabel{case-3-the-missing-class-belongs-to-a-global-library}{{293.3}{864}{Case 3: The Missing Class Belongs to a Global Library}{section.293.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {293.4}Case 4: The Missing Class Belongs to a Java Runtime Package}{865}{section.293.4}\\protected@file@percent }\n\\newlabel{case-4-the-missing-class-belongs-to-a-java-runtime-package}{{293.4}{865}{Case 4: The Missing Class Belongs to a Java Runtime Package}{section.293.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {293.5}Related Topics}{865}{section.293.5}\\protected@file@percent }\n\\newlabel{related-topics-35}{{293.5}{865}{Related Topics}{section.293.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {294}System Check}{867}{chapter.294}\\protected@file@percent }\n\\newlabel{system-check}{{294}{867}{System Check}{chapter.294}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {294.1}Related Topics}{867}{section.294.1}\\protected@file@percent }\n\\newlabel{related-topics-36}{{294.1}{867}{Related Topics}{section.294.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {295}Troubleshooting Front-End Development Issues}{869}{chapter.295}\\protected@file@percent }\n\\newlabel{troubleshooting-front-end-development-issues}{{295}{869}{Troubleshooting Front-End Development Issues}{chapter.295}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {295.1}CSS}{869}{section.295.1}\\protected@file@percent }\n\\newlabel{css}{{295.1}{869}{CSS}{section.295.1}{}}\n\\newlabel{broken-css-angular-app}{{295.1}{869}{CSS}{section*.7}{}}\n\\newlabel{portal-css-broken-ie}{{295.1}{869}{CSS}{section*.8}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {295.2}Modules}{869}{section.295.2}\\protected@file@percent }\n\\newlabel{modules-1}{{295.2}{869}{Modules}{section.295.2}{}}\n\\newlabel{jquery-anonymous-module-error}{{295.2}{869}{Modules}{section*.9}{}}\n\\newlabel{source-maps-not-showing}{{295.2}{870}{Modules}{section*.10}{}}\n\\newlabel{disable-bundler-analytics}{{295.2}{870}{Modules}{section*.11}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {295.3}Portlets}{870}{section.295.3}\\protected@file@percent }\n\\newlabel{portlets}{{295.3}{870}{Portlets}{section.295.3}{}}\n\\newlabel{angular-react-vue-portlet-disable-spa}{{295.3}{870}{Portlets}{section*.12}{}}\n\\@setckpt{developer/appdev}{\n\\setcounter{page}{871}\n\\setcounter{equation}{0}\n\\setcounter{enumi}{3}\n\\setcounter{enumii}{1}\n\\setcounter{enumiii}{3}\n\\setcounter{enumiv}{0}\n\\setcounter{footnote}{0}\n\\setcounter{mpfootnote}{0}\n\\setcounter{@memmarkcntra}{0}\n\\setcounter{storedpagenumber}{1}\n\\setcounter{book}{0}\n\\setcounter{part}{3}\n\\setcounter{chapter}{295}\n\\setcounter{section}{3}\n\\setcounter{subsection}{0}\n\\setcounter{subsubsection}{0}\n\\setcounter{paragraph}{0}\n\\setcounter{subparagraph}{0}\n\\setcounter{@ppsavesec}{0}\n\\setcounter{@ppsaveapp}{0}\n\\setcounter{vslineno}{0}\n\\setcounter{poemline}{0}\n\\setcounter{modulo@vs}{0}\n\\setcounter{memfvsline}{0}\n\\setcounter{verse}{0}\n\\setcounter{chrsinstr}{0}\n\\setcounter{poem}{0}\n\\setcounter{newflo@tctr}{4}\n\\setcounter{@contsubnum}{0}\n\\setcounter{section@level}{0}\n\\setcounter{maxsecnumdepth}{1}\n\\setcounter{sidefootnote}{0}\n\\setcounter{pagenote}{0}\n\\setcounter{pagenoteshadow}{0}\n\\setcounter{memfbvline}{0}\n\\setcounter{bvlinectr}{0}\n\\setcounter{cp@cntr}{0}\n\\setcounter{ism@mctr}{0}\n\\setcounter{xsm@mctr}{0}\n\\setcounter{csm@mctr}{0}\n\\setcounter{ksm@mctr}{0}\n\\setcounter{xksm@mctr}{0}\n\\setcounter{cksm@mctr}{0}\n\\setcounter{msm@mctr}{0}\n\\setcounter{xmsm@mctr}{0}\n\\setcounter{cmsm@mctr}{0}\n\\setcounter{bsm@mctr}{0}\n\\setcounter{workm@mctr}{0}\n\\setcounter{sheetsequence}{943}\n\\setcounter{lastsheet}{2851}\n\\setcounter{lastpage}{2779}\n\\setcounter{figure}{0}\n\\setcounter{lofdepth}{1}\n\\setcounter{table}{0}\n\\setcounter{lotdepth}{1}\n\\setcounter{Item}{1096}\n\\setcounter{Hfootnote}{5}\n\\setcounter{bookmark@seq@number}{0}\n\\setcounter{memhycontfloat}{0}\n\\setcounter{Hpagenote}{0}\n\\setcounter{r@tfl@t}{0}\n\\setcounter{float@type}{4}\n\\setcounter{LT@tables}{14}\n\\setcounter{LT@chunks}{3}\n\\setcounter{parentequation}{0}\n\\setcounter{FancyVerbLine}{0}\n}\n"
},
{
"path": "book/developer/appdev.tex",
"content": "\\chapter{Application Development}\\label{application-development}\n\nWriting applications on Liferay's standards-based platform makes your\nlife easier. Whether you create headless services for clients to access,\nfull-blown web applications with beautiful UIs, or anything in between,\nLiferay DXP streamlines the process to help you get your job done\nfaster.\n\nLiferay's framework embraces your existing tools and build environments\nlike \\href{https://maven.apache.org}{Maven} and\n\\href{https://gradle.org}{Gradle}. You can work with the standard\ntechnologies you know and leverage Liferay's APIs for Documents,\nPermissions, Search, or Content when you need them. Here's a high level\nview of what you can do:\n\n\\begin{itemize}\n\\item\n \\textbf{Deployment of existing standards-based apps:} If you have an\n existing app built outside of Liferay DXP, you can deploy it on\n Liferay DXP. The Liferay Bundler Generator and Liferay npm Bundler\n provide the project scaffolding and packaging to deploy\n \\href{https://angular.io/}{Angular},\n \\href{https://reactjs.org/}{React}, and \\href{https://vuejs.org/}{Vue}\n web front-ends as Widgets. Spring Portlet MVC app conversion to\n \\href{https://github.com/liferay/portletmvc4spring}{PortletMVC4Spring}\n requires only a few steps. JSF applications work almost as-is. Portlet\n 3.0 or 2.0 compliant portlets deploy on Liferay DXP.\n\\item\n \\textbf{Back-end Java services, web services, and REST services:}\n Service Builder is an object-relational mapper where you describe your\n data model in a single \\texttt{xml} file. From this, you can generate\n the tables, a Java API for accessing your data model, and web\n services. On top of these, REST Builder generates OpenAPI-based REST\n services your client applications can call.\n\\item\n \\textbf{Authentication and single-sign on (SSO):} OAuth 2.0, OpenID\n Connect, and SAML are built-in and ready to go.\n\\item\n \\textbf{Front-end web development using Java EE and/or JavaScript:}\n Use Java EE standard Portlet technology (JSR 168, JSR 286, JSR 362)\n with CDI and/or JSF. Prefer Spring?\n \\href{https://github.com/liferay/portletmvc4spring}{PortletMVC4Spring}\n brings the Spring MVC Framework to Liferay. Rather have a client-side\n app? Write it in \\href{https://angular.io/}{Angular},\n \\href{https://reactjs.org/}{React}, or \\href{https://vuejs.org/}{Vue}.\n Been using Liferay DXP for a while? Liferay MVC Portlet is better than\n ever.\n\\item\n \\textbf{Frameworks and APIs for every need:} Be more productive by\n using Liferay's built-in and well-tested APIs that cover often-used\n features like file management(upload/download), permissions, comments,\n out-of-process messaging, or UI elements such as data tables and item\n selectors. Liferay DXP offers many APIs for every need, from an entire\n workflow framework to a streamlined way of getting request parameters.\n\\item\n \\textbf{Tool freedom:} Liferay provides Maven archetypes,\n \\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\n Workspace},\n \\href{/docs/7-2/reference/-/knowledge_base/r/gradle-plugins}{Gradle}\n and \\href{/docs/7-2/reference/-/knowledge_base/r/maven-plugins}{Maven}\n plugins, a \\href{http://yeoman.io/}{Yeoman}-based\n \\href{/docs/7-2/reference/-/knowledge_base/r/theme-generator}{theme\n generator}, and\n \\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI} to\n integrate with any development workflow. On top of that, you can use\n our \\href{/docs/7-2/reference/-/knowledge_base/r/intellij}{IntelliJ\n plugin} or the Eclipse-based\n \\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\n Developer Studio} if you need a full-blown development environment.\n\\item\n \\textbf{Developer community:} The \\href{https://liferay.dev}{Liferay\n DXP community} is helpful and active.\n\\end{itemize}\n\n\\section{Getting Started with Liferay\nDevelopment}\\label{getting-started-with-liferay-development}\n\nWant to see what it's like to develop an app on Liferay DXP? Here's a\nquick tour.\n\n\\section{Create Your Object Model and Database in One\nShot}\\label{create-your-object-model-and-database-in-one-shot}\n\nYou don't need a database to work with Liferay, but if your app uses\none, you can design it and your object model at the same time with\nLiferay's object-relational mapper,\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}. You define your object model in a single \\texttt{xml} file:\n\n\\begin{verbatim}\n\n\n\n liferay\n GB\n \n\n \n \n\n \n \n \n\n \n\n \n \n \n \n \n \n \n\n \n \n \n\n \n\n\n\\end{verbatim}\n\nService Builder generates your object model, database, SOAP, and JSON\nweb services automatically. Java classes are ready for you to implement\nyour business logic around generated CRUD operations. The web services\nare mapped to your business logic. If you want a REST interface, you can\ncreate one.\n\n\\section{Create a REST Interface}\\label{create-a-rest-interface}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/rest-builder}{REST Builder}\nhelps you define REST interfaces for your APIs, using\n\\href{https://swagger.io/docs/specification/about/}{OpenAPI/Swagger}.\nCreate your\n\\href{https://swagger.io/docs/specification/basic-structure/}{YAML\ndefinition} file for your REST interface along with a configuration file\ndefining where Java classes, a client, and tests should be generated,\nand you have REST endpoints ready to call your API.\n\nNext, you need a client. You can use Liferay DXP in headless mode and\nwrite your web and mobile clients any way you want. Or you can create\nyour web clients on Liferay's platform and take advantage of its many\ntools and APIs that speed up development.\n\n\\section{Create a Web Client}\\label{create-a-web-client}\n\nLiferay DXP is an ideal platform upon which to build a web client. Its\nJava EE-based technology means you can pick from the best it has to\noffer: Spring MVC using\n\\href{https://github.com/liferay/portletmvc4spring}{PortletMVC4Spring},\nthe new backwards-compatible Portlet 3, JSF using\n\\href{https://liferayfaces.org}{Liferay Faces}, or the venerable\nOSGi-based\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{Liferay\nMVC Portlet}. If you're a front-end developer, deploy your Angular,\nReact, or Vue-based front-end applications to run as widgets next to the\nrest of Liferay DXP's installed applications.\n\n\\section{Use Liferay's Frameworks}\\label{use-liferays-frameworks}\n\nYour apps need features. Liferay has implemented tons of common\nfunctionality you can use in your applications. The\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/liferay-ui/tld-summary.html}{Liferay-UI}\ntag library has tons of web components like Search Container (a sortable\ndata table), panels, buttons, and more. Liferay's\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/asset-framework}{Asset\nFramework} can publish data from your application in context wherever\nusers need it---as a notification, a related asset, as tagged or\ncategorized data, or as relevant data based on a\n\\href{/docs/7-2/user/-/knowledge_base/u/creating-user-segments}{user\nsegment}. Need to provide file upload/download? Use the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/documents-and-media-api}{Documents\nAPI}. Need a robust permissions system? Use\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/defining-application-permissions}{Liferay\npermissions}. Want users to submit comments? Use Liferay's\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/adding-comments-to-your-app}{comments}.\nNeed to process data outside the request/response? Use the Message Bus.\nShould users select items from a list? Use the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/item-selector}{Item\nSelector}.\n\n\\section{Next Steps}\\label{next-steps}\n\nSo what's next? \\href{/download}{Download} Liferay DXP and\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{create\nyour first project}! Have a look at our\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{back-end},\n\\href{/docs/7-2/appdev/-/knowledge_base/a/rest-builder}{REST Builder},\nand \\href{/docs/7-2/appdev/-/knowledge_base/a/web-front-ends}{front-end}\ndocs, examine what Liferay's\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/frameworks}{frameworks}\nhave to offer, and then go create the beautiful things that only you can\nmake.\n\n\\chapter{Developing Web Front-Ends}\\label{developing-web-front-ends}\n\nLiferay's open development framework removes barriers so developers can\nwrite applications faster. If you already have an application, you can\ndeploy it on Liferay DXP:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Java-based standards (CDI, JSF, Portlets, Spring)\n\\item\n Front-end standards (Angular, React, Vue)\n\\end{itemize}\n\nIf you plan to write a new application and deploy it on Liferay DXP, you\ncan use the frameworks you know along with the build tools (Gradle,\nMaven) you know. Liferay also offers its own development framework\ncalled MVC Portlet that it uses to develop applications. When you want\nto integrate with\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Liferay\nservices} and frameworks such as permissions, assets, and indexers,\nyou'll find that these easily and seamlessly blend with your application\nto provide a great user experience.\n\nRegardless of your development strategy for applications, you'll find\nLiferay DXP to be a flexible platform that supports anything you need to\nwrite.\n\n\\section{Using Popular Frameworks}\\label{using-popular-frameworks}\n\nLiferay gives you a head start on developing and deploying apps that use\nthese popular Java and JavaScript-based technologies:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-an-angular-application}{Angular\n Widget}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-react-application}{React\n Widget}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-vue-application}{Vue\n Widget}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{Liferay\n MVC Portlet}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/portletmvc4spring}{PortletMVC4Spring\n Portlet}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/jsf-portlet}{JSF Portlet}\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The Reference section describes\n\\href{/docs/7-2/reference/-/knowledge_base/r/sample-projects}{sample\nprojects} and\n\\href{/docs/7-2/reference/-/knowledge_base/r/project-templates}{project\ntemplates} for creating UIs using other technologies.\n\n\\noindent\\hrulefill\n\nAngular, React, and Vue applications are written the same as you would\noutside of Liferay DXP---using \\href{https://www.npmjs.com/}{npm} and\nthe webpack dev server. The Liferay JS Generator creates a portlet\nbundle (project) for developing and deploying each type of app. The\nbundle project comes with npm commands for building, testing, and\ndeploying the app. It packages the app's dependencies (including\nJavaScript packages), deploys the bundle as a JAR, and installs the\nbundle to Liferay DXP's run time environment, making your app available\nas a widget.\n\nYou can also develop web front-ends using Java EE standards. Liferay DXP\nsupports the \\href{https://jcp.org/en/jsr/detail?id=362}{JSR 362}\nPortlet 3.0 standard which is backwards-compatible with the\n\\href{http://jcp.org/en/jsr/detail?id=286}{JSR 286} Portlet 2.0 standard\nfrom the Java Community Process (JCP). Each portlet framework has\nbenefits you may wish to consider.\n\nBean Portlet is the only framework containing all of the Portlet 3\nfeatures:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Contexts and Dependency Injection (CDI)\n\\item\n Extended method annotations\n\\item\n Explicit render state\n\\item\n Action, render, and resource parameters\n\\item\n Asynchronous support\n\\end{itemize}\n\nIf you're a JavaServer Faces (JSF) developer, the\n\\href{/docs/7-1/reference/-/knowledge_base/r/understanding-liferay-faces-bridge}{Liferay\nFaces Bridge} supports deploying JSF web apps as portlets without\nwriting portlet-specific Java code. It also contains innovative features\nthat make it possible to leverage the power of JSF 2.x inside a portlet\napplication.\n\nIf Spring is your thing, Spring Portlet MVC portlets are easy to\nconfigure and deploy on Liferay DXP. You can continue using Spring\nfeatures, including Spring beans and Spring dependency injection.\n\nLast but not least, Liferay MVC Portlet continues to be a favorite with\nexperienced Liferay developers, and makes portlet development easy for\nLiferay newcomers. It leverages OSGi Declarative Services (DS) for\ninjecting dependencies and defining configurable extension points. Since\nLiferay DXP core and Liferay-written apps use DS, gaining experience\nwith DS helps you develop Liferay DXP extensions and customizations.\nLiferay MVC Portlet works seamlessly with many Liferay frameworks, such\nas MVC commands, Service Builder, and more.\n\nNo matter which development framework you choose, you'll be able to get\nan app up and running fast.\n\n\\section{Getting Started}\\label{getting-started}\n\nIf you have an existing app that uses one the frameworks described\nabove, your first step is to deploy it to Liferay DXP. Most deployments\ninvolve configuration steps that you can complete in an hour or less.\n\nYou can also build apps from scratch using the tools you like or\nleveraging Liferay's tool offering. Liferay provides templates for\ncreating all kinds of apps and samples that you can examine and modify\nto fit your needs.\n\nOnce your app is functional, you can improve your app by integrating it\nwith Liferay frameworks:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Localization\n\\item\n Permissions\n\\item\n Search and indexing\n\\item\n Asset publishing\n\\item\n Workflow\n\\item\n Staging\n\\item\n Data export and import\n\\end{itemize}\n\nLiferay provides frameworks that integrate these features fast. As you\ndevelop apps on Liferay DXP, you'll enjoy using what you know, discover\nframeworks and tools that boost your productivity, and have fun creating\nrich, full-featured applications.\n\nIf you're experienced with developing one of the listed app types, feel\nfree to jump ahead to it. Otherwise, Angular Widgets is next.\n\n\\chapter{Developing an Angular\nApplication}\\label{developing-an-angular-application}\n\nRunning an existing Angular app on Liferay DXP makes the app available\nas a widget for using on site pages. You can\n\\href{/docs/7-2/reference/-/knowledge_base/r/adapting-existing-apps-to-run-on-product}{adapt\nyour existing Angular app}, but this doesn't give you access to the\nbundler and its various loaders to develop your project further in\nLiferay DXP. To have access to all of Liferay DXP's features, you must\nuse the Liferay JS Generator and Liferay npm Bundler to merge your files\ninto a portlet bundle, adapt your routes and CSS, and deploy your\nbundle.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/appdev-angular-app-migrated.png}\n\\caption{Apps like this Guestbook app are easy to migrate to Liferay\nDXP.}\n\\end{figure}\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Using \\href{https://www.npmjs.com}{npm}, install the Liferay JS\n Generator:\n\n\\begin{verbatim}\nnpm install -g yo generator-liferay-js\n\\end{verbatim}\n\\item\n Generate an Angular-based portlet bundle project for deploying your\n app to your \\href{/deployment/docs/installing-product}{Liferay DXP\n installation}.\n\n\\begin{verbatim}\nyo liferay-js\n\\end{verbatim}\n\n Select \\texttt{Angular\\ based\\ portlet} and opt for generating sample\n code. Here's the bundle's structure:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{{[}my-angular-portlet-bundle{]}}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{assets/} → CSS, HTML templates, and resources\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{css/} → CSS files\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{styles.css} → Default CSS file\n \\end{itemize}\n \\item\n \\texttt{app/} → HTML templates\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{app.component.html} → Root component template\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{features/} → Liferay DXP bundle features\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{localization/} → Resource bundles\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{Language.properties} → Default language keys\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{src/} → JavaScript an TypeScript files\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{app/} → Application modules and Components\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{app.component.ts} → Main component\n \\item\n \\texttt{app.module.ts} → Root module\n \\item\n \\texttt{dynamic.loader.ts} → Loads an Angular component\n dynamically for the portlet to attach to\n \\end{itemize}\n \\item\n \\texttt{types/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{LiferayParams.ts} → Parameters passed by Liferay DXP\n to the JavaScript module\n \\end{itemize}\n \\item\n \\texttt{index.ts} → Main module invoked by the ``bootstrap''\n module to initialize the portlet\n \\item\n \\texttt{polyfills.ts} → Fills in browser JavaScript\n implementation gaps\n \\end{itemize}\n \\item\n \\texttt{package.json} → npm bundle configuration\n \\item\n \\texttt{README.md}\n \\item\n \\texttt{.npmbuildrc} → Build configuration\n \\item\n \\texttt{.npmbundlerrc} → Bundler configuration\n \\item\n \\texttt{tsconfig.json} → TypeScript configuration\n \\end{itemize}\n \\end{itemize}\n\\item\n Copy your app files, matching the types listed below, into your new\n project.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n File type | Destination | Comments |\n --------- | ----------- | -------- |\n HTML | `assets/app/` | Merge your main component with the existing `app.component.html`. |\n CSS | `assets/css/` | Overwrite `styles.css`. |\n TypeScript and JavaScript | `src/app/` | Merge with all files **except** `app.module.ts`---the root module merge is explained in a later step. |\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\item\n Update your component class \\texttt{templateUrl}s to use the\n \\texttt{web-context} value declared in your project's\n \\texttt{.npmbundlerrc} file. Here's the format:\n\n\\begin{verbatim}\ntemplateUrl: `/o/[web-context]/app/[template]`\n\\end{verbatim}\n\n Here's an example:\n\n\\begin{verbatim}\ntemplateUrl: '/o/my-angular-guestbook/app/add-entry/add-entry.component.html'\n\\end{verbatim}\n\\item\n Update your bundle to use portlet-level styling.\n\n \\begin{itemize}\n \\item\n Import all component CSS files through the CSS file (default is\n \\texttt{styles.css}) your bundle's \\texttt{package.json} file sets\n for your portlet. Here's the default setting:\n\n\\begin{verbatim}\n\"portlet\": {\n \"com.liferay.portlet.header-portlet-css\": \"/css/styles.css\",\n...\n}\n\\end{verbatim}\n \\item\n Remove \\texttt{selector} and \\texttt{styleUrls} properties from your\n component classes.\n \\end{itemize}\n\\item\n In your routing module's \\texttt{@NgModule} decorator, configure the\n router option \\texttt{useHash:\\ true}. This tells Angular to use\n client-side routing in the form of \\texttt{.../\\#/{[}route{]}}, which\n prevents client-side parameters (i.e., anything after \\texttt{\\#})\n from being sent back to Liferay DXP.\n\n For example, your routing module class \\texttt{@NgModule} decorator\n might look like this:\n\n\\begin{verbatim}\n@NgModule({\n imports: [RouterModule.forRoot(routes, {useHash: true})],\n exports: [RouterModule]\n})\nexport class AppRoutingModule { }\n\\end{verbatim}\n\\item\n Also in your routing module, export your view components for your root\n module (discussed next) to use. For example,\n\n\\begin{verbatim}\nexport const routingComponents = [ViewComponent1, ViewComponent2]\n\\end{verbatim}\n\\item\n Merge your root module with \\texttt{src/app/app.module.ts},\n configuring it to dynamically load components.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Components must be loaded dynamically to attach to the portlet's\n DOM. The DOM is determined at run time when the portlet's page is\n rendered. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n- Import the `routingComponents` constant and the app routing module class\n from your app routing module. For example,\n\n ```javascript\n import { AppRoutingModule, routingComponents } from './app-routing.module';\n ```\n\n- Specify the base href for the router to use in the navigation URLs. \n\n ```javascript\n import { APP_BASE_HREF } from '@angular/common';\n ...\n \n @NgModule({\n ...\n providers: [{provide: APP_BASE_HREF, useValue: '/'}]\n })\n ```\n\n- Declare the `routingComponents` constant in your `@NgModule` decorator. \n\n ```javascript\n @NgModule({\n declarations: [\n routingComponents,\n ...\n ],\n ...\n })\n ```\n\n- Make sure your `@NgModule` `bootstrap` property has no components. All \n components are loaded dynamically using the `entryComponents` array\n property. The empty `ngDoBootstrap()` method nullifies the default\n bootstrap implementation. \n\n ```javascript\n @NgModule({\n ...\n entryComponents: [AppComponent],\n bootstrap: [],\n ...\n })\n export class AppModule {\n ngDoBootstrap() {}\n ...\n }\n ```\n\nYour root module `app.module.ts` should look like this: \n\n```javascript\nimport { APP_BASE_HREF } from '@angular/common';\nimport { AppRoutingModule, routingComponents } from './app-routing.module';\n// more imports ...\n\n@NgModule({\n declarations: [\n AppComponent,\n routingComponents, \n // more declarations ...\n ],\n imports: [\n AppRoutingModule,\n // more imports ...\n ],\n entryComponents: [AppComponent],\n providers: [{provide: APP_BASE_HREF, useValue: '/'}],\n bootstrap: [],\n // more properties ...\n})\nexport class AppModule {\n ngDoBootstrap() {}\n\n // ...\n}\n```\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{8}\n\\tightlist\n\\item\n Merge your app \\texttt{package.json} file's \\texttt{dependencies} and\n \\texttt{devDependencies} into the bundle's \\texttt{package.json}.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** To work around build errors caused by the `rxjs` dependency, set\n the dependency to version `\"6.0.0\"`. See\n [LPS-92848](https://issues.liferay.com/browse/LPS-92848)\n for details. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{9}\n\\item\n Finally, deploy your bundle:\n\n\\begin{verbatim}\nnpm run deploy\n\\end{verbatim}\n\\end{enumerate}\n\nCongratulations! Your Angular app is deployed and now available as a\nwidget that you can add to site pages.\n\nThe Liferay npm Bundler confirms the deployment:\n\n\\begin{verbatim}\nReport written to liferay-npm-bundler-report.html\nDeployed my-angular-guestbook-1.0.0.jar to c:\\git\\bundles\n\\end{verbatim}\n\nThe Liferay DXP console confirms your bundle started:\n\n\\begin{verbatim}\n2019-03-22 20:17:53.181 INFO [fileinstall-C:/git/bundles/osgi/modules][BundleStartStopLogger:39] STARTED my-angular-guestbook_1.0.0 [1695]\n\\end{verbatim}\n\nTo find your widget, select the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}), navigate to\n\\emph{Widgets} and then the category you specified to the Liferay Bundle\nGenerator (\\emph{Sample} is the default category).\n\n\\section{Related Topics}\\label{related-topics}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/web-services}{Web\nServices}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{Localization}\n\n\\chapter{Developing a React\nApplication}\\label{developing-a-react-application}\n\nRunning an existing React app on Liferay DXP makes the app available as\na widget for using on site pages. You can\n\\href{/docs/7-2/reference/-/knowledge_base/r/adapting-existing-apps-to-run-on-product}{adapt\nyour existing React app}, but this doesn't give you access to the\nbundler and its various loaders to develop your project further in\nLiferay DXP. To have access to all of Liferay DXP's features, you must\nuse the Liferay JS Generator and Liferay npm Bundler to merge your files\ninto a portlet bundle, update your static resource paths, and deploy\nyour bundle.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/appdev-react-app-migrated.png}\n\\caption{Apps like this Guestbook app are easy to migrate to Liferay\nDXP.}\n\\end{figure}\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Using \\href{https://www.npmjs.com/}{npm}, install the Liferay JS\n Generator:\n\n\\begin{verbatim}\nnpm install -g yo generator-liferay-js\n\\end{verbatim}\n\\item\n Generate a React based portlet bundle project for deploying your app\n to your \\href{/deployment/docs/installing-product}{Liferay DXP\n installation}.\n\n\\begin{verbatim}\nyo liferay-js\n\\end{verbatim}\n\n Select \\texttt{React\\ based\\ portlet} and opt for generating sample\n code. Here's the bundle's structure:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{my-react-portlet-bundle}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{assets/} → CSS and resources\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{css/} → CSS files\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{styles.css} → Default CSS file\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{features/} → Liferay DXP bundle features\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{localization} → Resource bundles\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{Language.properties} → Default language keys\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{src/} → JavaScript and React component files\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{AppComponent.js} → Sample React component that you can\n remove\n \\item\n \\texttt{index.js} → Main module used to initialize the portlet\n \\end{itemize}\n \\item\n \\texttt{.babelrc} → Babel configuration\n \\item\n \\texttt{.npmbuildrc} → Build configuration\n \\item\n \\texttt{.npmbundlerrc} → Bundler configuration\n \\item\n \\texttt{package.json} → npm bundle configuration\n \\item\n \\texttt{README.md}\n \\end{itemize}\n \\end{itemize}\n\\item\n Copy your app files, matching the types listed below, into your new\n project.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n File type | Destination | Comments |\n --------- | ----------- | -------- |\n CSS | `assets/css/` | Overwrite `styles.css`. |\n JavaScript | `src/` | Merge with all files **except** `index.js`---the main module merge is explained in a later step. |\n Static resources | `assets/` | Include resources such as image files here |\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\item\n Update your bundle to use portlet-level styling.\n\n \\begin{itemize}\n \\tightlist\n \\item\n Import all component CSS files through the CSS file (default is\n \\texttt{styles.css}) your bundle's \\texttt{package.json} file sets\n for your portlet. Here's the default setting:\n \\end{itemize}\n\n\\begin{verbatim}\n \"portlet\": {\n \"com.liferay.portlet.header-portlet-css\": \"/css/styles.css\",\n ...\n }\n\\end{verbatim}\n\n \\begin{itemize}\n \\tightlist\n \\item\n Remove any CSS imports you have in your JS files\n \\end{itemize}\n\\item\n Update any static resource references to use the \\texttt{web-context}\n value declared in your project's \\texttt{.npmbundlerrc} file, and\n remove any imports for the resource. For example, if you have an image\n file called \\texttt{logo.png} in your \\texttt{assets} folder, you\n would use the format below. Note that the \\texttt{assets} folder is\n not included in the path.\n\n Here is the format:\n\n\\begin{verbatim}\n/o/[web-context]/[resource]\n\\end{verbatim}\n\n Here's an example image resource:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\\item\n Merge your entry module with \\texttt{src/index.js}, configuring it to\n dynamically load components.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Components must be loaded dynamically to attach to the portlet's\n DOM. The DOM is determined at run time when the portlet's page is\n rendered. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n- Use the `HashRouter` for routing between component views, as Liferay DXP \n requires hash routing for proper portal navigation:\n\n ```javascript\n import { HashRouter as Router } from 'react-router-dom';\n ```\n\n- Place your code inside the `main()` function.\n\n- Render your app inside the `portletElementId` element that is passed in \n the `main()` function. This is required to render the React app inside\n the portlet.\n\nYour entry module `index.js` should look like this. \n\n```javascript\nimport React from 'react';\nimport ReactDOM from 'react-dom';\n//import './index.css';//removed for Portal Migration\nimport App from './App';\nimport { HashRouter as Router } from 'react-router-dom';\n\nexport default function main({portletNamespace, contextPath, \nportletElementId}) {\n ReactDOM.render((\n \n \n \n ), document.getElementById(portletElementId));\n}\n```\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{6}\n\\item\n Merge your app \\texttt{package.json} file's \\texttt{dependencies} and\n \\texttt{devDependencies} into the bundle's \\texttt{package.json}.\n\\item\n Finally, deploy your bundle:\n\n\\begin{verbatim}\nnpm run deploy\n\\end{verbatim}\n\\end{enumerate}\n\nCongratulations! Your React app is deployed and now available as a\nwidget that you can add to site pages.\n\nThe Liferay npm Bundler confirms the deployment:\n\n\\begin{verbatim}\nReport written to liferay-npm-bundler-report.html\nDeployed my-react-guestbook-1.0.0.jar to c:\\git\\bundles\n\\end{verbatim}\n\nThe Liferay DXP console confirms your bundle started:\n\n\\begin{verbatim}\n2019-03-22 20:17:53.181 INFO \n[fileinstall-C:/git/bundles/osgi/modules][BundleStartStopLogger:39] \nSTARTED my-react-guestbook_1.0.0 [1695]\n\\end{verbatim}\n\nTo Find your widget, click the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}), navigate to\n\\emph{Widgets} and then the category you specified to the Liferay Bundle\nGenerator (\\emph{Sample} is the default category).\n\n\\section{Related Topics}\\label{related-topics-1}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/web-services}{Web\nServices}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{Localization}\n\n\\chapter{Developing a Vue\nApplication}\\label{developing-a-vue-application}\n\nRunning an existing Vue app on Liferay DXP makes the app available as a\nwidget for using on site pages. You can\n\\href{/docs/7-2/reference/-/knowledge_base/r/adapting-existing-apps-to-run-on-product}{adapt\nyour existing Vue app}, but this doesn't give you access to the bundler\nand its various loaders to develop your project further in Liferay DXP.\nTo have access to all of Liferay DXP's features, you must use the\nLiferay JS Generator and Liferay npm Bundler to merge your files into a\nportlet bundle, update your static resource paths, and deploy your\nbundle. The steps below demonstrate how to prepare a Vue app that uses\nsingle file components (\\texttt{.vue} files) with multiple views.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/appdev-vue-migrated.png}\n\\caption{Vue Apps like this Guestbook App are easy to deploy, and they\nlook great in Liferay DXP.}\n\\end{figure}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} if you have a tree of components expressed as\n\\texttt{.vue} templates, only the root one will be available as a true\nAMD module.\n\n\\noindent\\hrulefill\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Using \\href{https://www.npmjs.com/}{npm}, install the Liferay JS\n Generator:\n\n\\begin{verbatim}\nnpm install -g yo generator-liferay-js\n\\end{verbatim}\n\\item\n Generate a Vue based portlet bundle project:\n\n\\begin{verbatim}\nyo liferay-js\n\\end{verbatim}\n\n Select \\texttt{Vue\\ based\\ portlet} and opt for generating sample\n code. Here's the bundle's structure:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{my-vue-portlet-bundle}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{assets/} → CSS and resources\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{css/} → CSS not included in \\texttt{.vue} files.\n \\end{itemize}\n \\item\n \\texttt{features/} → Liferay DXP bundle features\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{localization/} → Resource bundles\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{Language.properties} → Default language keys\n \\end{itemize}\n \\item\n \\texttt{settings.json} → Placeholder System Settings\n \\end{itemize}\n \\item\n \\texttt{src/} → JavaScript and Vue files\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{index.js} → Main module used to initialize the portlet\n \\end{itemize}\n \\item\n \\texttt{.babelrc} → Babel configuration\n \\item\n \\texttt{.npmbuildrc} → Build configuration\n \\item\n \\texttt{.npmbundlerrc} → Bundler configuration\n \\item\n \\texttt{package.json} → npm bundle configuration\n \\item\n \\texttt{README.md}\n \\end{itemize}\n \\end{itemize}\n\\item\n Copy your app files, matching the types listed below, into your new\n project.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n File type | Destination | Comments |\n --------- | ----------- | -------- |\n CSS | `assets/css/` | Overwrite `styles.css`. |\n Static resources | `assets` | Include resources such as image files here |\n VUE and JS| `src` | Merge your main component with the existing `index.js`. More info on that below. |\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\item\n Update your bundle to use portlet-level styling.\n\n \\begin{itemize}\n \\item\n If you have internal CSS included with\n \\texttt{\\textless{}style\\textgreater{}} tags in your \\texttt{.vue}\n files, import \\texttt{.index.css} in \\texttt{/assets/styles.css}.\n This is generated by the modified build script further down:\n\n\\begin{verbatim}\n@import '../index.css';\n\\end{verbatim}\n \\item\n Import all custom CSS files (i.e.~CSS not included in \\texttt{.vue}\n files) through the CSS file (default is \\texttt{styles.css}) your\n bundle's \\texttt{package.json} file sets for your portlet. Here's\n the default setting:\n\n\\begin{verbatim}\n\"portlet\": {\n \"com.liferay.portlet.header-portlet-css\": \"/css/styles.css\",\n...\n}\n\\end{verbatim}\n \\end{itemize}\n\\item\n Update any static resource references to use the \\texttt{web-context}\n value declared in your project's \\texttt{.npmbundlerrc} file. Here's\n the format:\n\n\\begin{verbatim}\n/o/[web-context]/[resource]\n\\end{verbatim}\n\n Here's an example image resource:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\\item\n Merge your entry module with \\texttt{src/index.js}, following these\n steps to dynamically load components.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Components must be loaded dynamically to attach to the portlet's\n DOM. The DOM is determined at runtime when the portlet's page is\n rendered. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n- Use Vue's runtime + compiler module \n (`import Vue from 'vue/dist/vue.common';`) so you don't have to process \n templates during build time. This is imported by default at the top of \n the file.\n\n- Remove the sample content from the `main()` function (i.e. the `node` \n constant and its use), and replace it with your router code.\n\n- Make these updates to the `new Vue` instance:\n\n - Remove the default data properties (the ones you just removed in the \n sample content), and set the render element to `portletElementId`. \n This is required and ensures that your app is rendered inside the \n portlet.\n - Add the router.\n - Add a render function that mounts your component wrapper to the Vue \n instance and displays it.\n \n Your updated configuration should look like this:\n\n ```javascript\n new Vue({\n el: `#${portletElementId}`,\n render: h => h(App),\n router\n })\n ```\n\nYour entry module `index.js` should look like this. \n\n```javascript\nimport Vue from 'vue/dist/vue.common';\nimport App from './App.vue'\nimport VueRouter from 'vue-router'\n//Component imports\n\nexport default function main({portletNamespace, contextPath, portletElementId}) {\n\n Vue.config.productionTip = false\n\n Vue.use(VueRouter)\n\n const router = new VueRouter({\n routes: [\n {\n ...\n }\n ]\n })\n new Vue({\n el: `#${portletElementId}`,\n render: h => h(App),\n router\n })\n}\n```\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{6}\n\\item\n Merge your app \\texttt{package.json} file's \\texttt{dependencies} and\n \\texttt{devDependencies} into the project's \\texttt{package.json}, and\n replace the \\texttt{babel-cli} and \\texttt{babel-preset-env} dev\n dependencies with the newer \\texttt{\"@babel/cli\":\\ \"\\^{}7.0.0\"} and\n \\texttt{\"@babel/preset-env\":\\ \"\\^{}7.4.2\"} packages instead. Also\n include the \\texttt{\"vueify\":\\ \"9.4.1\"} dev dependency.\n\\item\n Update the \\texttt{.babelrc} file to use \\texttt{@babel/preset-env}\n instead of \\texttt{env}:\n\n\\begin{verbatim}\n\"presets\": [\"@babel/preset-env\"]\n\\end{verbatim}\n\\item\n If you're using \\texttt{.vue} files, replace the build script in the\n \\texttt{package.json} with the one below to use\n \\texttt{vue-cli-service}. The updated build script uses vue-cli to\n access the main entrypoint for the app (\\texttt{index.js} in the\n example below) and combines all the Vue templates and JS files into\n one single file named \\texttt{index.common.js} and generates an\n \\texttt{index.css} file for any internal CSS included with\n \\texttt{\\textless{}style\\textgreater{}} tags in \\texttt{.vue} files:\n\n\\begin{verbatim}\n\"scripts\": {\n \"build\": \"babel --source-maps -d build src && vue-cli-service build --dest \n build/ --formats commonjs --target lib --name index ./src/index.js && npm \n run copy-assets && liferay-npm-bundler\",\n \"copy-assets\": \"lnbs-copy-assets\",\n \"deploy\": \"npm run build && lnbs-deploy\",\n \"start\": \"lnbs-start\"\n}\n\\end{verbatim}\n\\item\n Update the \\texttt{main} entry of the \\texttt{package.json} to match\n the new \\href{http://www.commonjs.org/}{CommonJS} file name specified\n in the previous step:\n\n\\begin{verbatim}\n\"main\": \"index.common\"\n\\end{verbatim}\n\\item\n Finally, deploy your portlet bundle:\n\n\\begin{verbatim}\nnpm run deploy\n\\end{verbatim}\n\\end{enumerate}\n\nCongratulations! Your Vue app is deployed and now available as a widget\nthat you can add to site pages.\n\nThe liferay-npm-bundler confirms the deployment:\n\n\\begin{verbatim}\nReport written to liferay-npm-bundler-report.html\nDeployed my-vue-guestbook-1.0.0.jar to c:\\git\\bundles\n\\end{verbatim}\n\nThe Liferay DXP console confirms your bundle started:\n\n\\begin{verbatim}\n2019-03-22 20:17:53.181 INFO \n[fileinstall-C:/git/bundles/osgi/modules][BundleStartStopLogger:39] \nSTARTED my-vue-guestbook_1.0.0 [1695]\n\\end{verbatim}\n\nFind your widget by selecting the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}) and navigating to\n\\emph{Widgets} and the category you specified to the Liferay Bundle\nGenerator (\\emph{Sample} is the default category).\n\n\\section{Related Topics}\\label{related-topics-2}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/web-services}{Web\nServices}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{Localization}\n\n\\chapter{Liferay MVC Portlet}\\label{liferay-mvc-portlet}\n\nIf you're an experienced developer, this is not the first time you've\nheard about Model View Controller. If there are so many implementations\nof MVC frameworks in Java, why did Liferay create yet another one? Stay\nwith us and you'll see that Liferay MVC Portlet provides these benefits:\n\n\\begin{itemize}\n\\tightlist\n\\item\n It's lightweight, as opposed to many other Java MVC frameworks.\n\\item\n There are no special configuration files that need to be kept in sync\n with your code.\n\\item\n It's a simple extension of\n \\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/GenericPortlet.html}{\\texttt{GenericPortlet}}.\n\\item\n You avoid writing a bunch of boilerplate code, since Liferay's MVC\n Portlet framework only looks for some pre-defined parameters when the\n \\texttt{init()} method is called.\n\\item\n The controller can be broken down into MVC command classes, each of\n which handles the controller code for a particular\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{portlet phase}\n (render, action, and resource serving phases).\n\\item\n An MVC command class can serve multiple portlets.\n\\item\n Liferay's portlets use it. That means there are plenty of robust\n implementations to reference when you need to design or troubleshoot\n your Liferay applications.\n\\end{itemize}\n\nThe Liferay MVC Portlet framework is light and easy to use. The default\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-the-mvc-portlet-template}{\\texttt{MVCPortlet}\nproject} template generates a fully configured and working project.\n\nHere, you'll learn how MVCPortlet works by covering these topics:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[mvc-layers-and-modularity]{MVC layers and modularity}\n\\item\n \\hyperref[liferay-mvc-command-classes]{Liferay MVC command classes}\n\\item\n \\hyperref[liferay-mvc-portlet-component]{Liferay MVC portlet\n component}\n\\item\n \\hyperref[a-simpler-mvc-portlet]{Simple MVC portlets}\n\\end{itemize}\n\nReview how each layer of the Liferay MVC portlet framework helps you\nseparate the concerns of your application.\n\n\\section{MVC Layers and Modularity}\\label{mvc-layers-and-modularity}\n\nIn MVC, there are three layers, and you can probably guess what they\nare.\n\n\\textbf{Model:} The model layer holds the application data and logic for\nmanipulating it.\n\n\\textbf{View:} The view layer contains logic for displaying data.\n\n\\textbf{Controller:} The middle man in the MVC pattern, the Controller\ncontains logic for passing the data back and forth between the view and\nthe model layers.\n\nLiferay DXP's applications are divided into multiple discrete modules.\nWith \\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}, the model layer is generated into a \\texttt{service} and an\n\\texttt{api} module. That accounts for the model in the MVC pattern. The\nview and the controller layers share a module, the \\texttt{web} module.\n\nGenerating the skeleton for a\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-the-service-builder-template}{multi-module\nService Builder-driven MVC application} saves you lots of time and gets\nyou started on the more important (and interesting, if we're being\nhonest) development work.\n\n\\section{Liferay MVC Command Classes}\\label{liferay-mvc-command-classes}\n\nIn a larger application, your \\texttt{-Portlet} class can become\nmonstrous and unwieldy if it holds all of the controller logic. Liferay\nprovides MVC command classes to break up your controller functionality.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCActionCommand.html}{\\texttt{MVCActionCommand}}:}\n Use \\texttt{-ActionCommand} classes to hold each of your portlet\n actions, which are invoked by action URLs.\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCRenderCommand.html}{\\texttt{MVCRenderCommand}}:}\n Use \\texttt{-RenderCommand} classes to hold a \\texttt{render} method\n that dispatches to the appropriate JSP, by responding to render URLs.\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCResourceCommand.html}{\\texttt{MVCResourceCommand}}:}\n Use \\texttt{-ResourceCommand} classes to serve resources based on\n resource URLs.\n\\end{itemize}\n\nThere must be some confusing configuration files to keep everything\nwired together and working properly, right? Wrong: it's all easily\nmanaged in the \\texttt{-Portlet} class's\n\\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\nannotation.\n\n\\section{Liferay MVC Portlet\nComponent}\\label{liferay-mvc-portlet-component}\n\nWhether or not you plan to split up the controller into MVC command\nclasses, the portlet \\texttt{@Component} annotation configures the\nportlet. Here's a simple portlet component as an example:\n\n\\begin{verbatim}\n@Component(\n property = {\n \"com.liferay.portlet.css-class-wrapper=portlet-hello-world\",\n \"com.liferay.portlet.display-category=category.sample\",\n \"com.liferay.portlet.icon=/icons/hello_world.png\",\n \"com.liferay.portlet.preferences-owned-by-group=true\",\n \"com.liferay.portlet.private-request-attributes=false\",\n \"com.liferay.portlet.private-session-attributes=false\",\n \"com.liferay.portlet.remoteable=true\",\n \"com.liferay.portlet.render-weight=50\",\n \"com.liferay.portlet.use-default-template=true\",\n \"javax.portlet.display-name=Hello World\",\n \"javax.portlet.expiration-cache=0\",\n \"javax.portlet.init-param.always-display-default-configuration-icons=true\",\n \"javax.portlet.name=\" + HelloWorldPortletKeys.HELLO_WORLD,\n \"javax.portlet.resource-bundle=content.Language\",\n \"javax.portlet.security-role-ref=guest,power-user,user\",\n \"javax.portlet.supports.mime-type=text/html\"\n },\n service = Portlet.class\n)\npublic class HelloWorldPortlet extends MVCPortlet {\n}\n\\end{verbatim}\n\nThe \\texttt{javax.portlet.name} property is required. When using MVC\ncommands, the \\texttt{javax.portlet.name} property value links\nparticular portlet URL/command combinations to the correct portlet.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Make your portlet name unique, considering how\n\\href{/docs/7-2/reference/-/knowledge_base/r/portlet-descriptor-to-osgi-service-property-map\\#ten}{Liferay\nDXP uses the name to create the portlet's ID}.\n\n\\noindent\\hrulefill\n\nThere can be some confusion over exactly what kind of\n\\texttt{Portlet.class} implementation you're publishing with a\ncomponent. The service registry expects this to be the\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/Portlet.html}{\\texttt{javax.portlet.Portlet}}\ninterface. Import that, and not, for example,\n\\texttt{com.liferay.portal.kernel.model.Portlet}.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The DTD\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/definitions/liferay-portlet-app_7_2_0.dtd.html}{liferay-portlet-app\\_7\\_2\\_0.dtd}\ndefines all the Liferay-specific attributes you can specify as\nproperties in your portlet components.\n\nConsider the \\texttt{\\textless{}css-class-wrapper\\textgreater{}} element\nfrom the above link as an example. To specify that property in your\ncomponent, use this syntax in your property list:\n\n\\texttt{\"com.liferay.portlet.css-class-wrapper=portlet-hello-world\",}\n\nThe properties namespaced with \\texttt{javax.portlet.} are elements of\nthe\n\\href{https://docs.liferay.com/portlet-api/3.0/portlet-app_3_0.xsd}{\\texttt{portlet.xml}\ndescriptor}.\n\n\\noindent\\hrulefill\n\n\\section{A Simpler MVC Portlet}\\label{a-simpler-mvc-portlet}\n\nIn simpler applications, you don't use MVC commands. Your portlet render\nURLs specify JSP paths in \\texttt{mvcPath} parameters.\n\n\\begin{verbatim}\n\n \n \" />\n\n\\end{verbatim}\n\nAs you've seen, Liferay's MVC Portlet framework gives you a\nwell-structured controller layer that takes very little time to\nimplement. With all your free time, you could\n\n\\begin{itemize}\n\\tightlist\n\\item\n Learn a new language\n\\item\n Take pottery classes\n\\item\n Lift weights\n\\item\n Work on your application's business logic\n\\end{itemize}\n\nIt's entirely up to you.\n\nTo get into the details of creating an MVC Portlet application, continue\nwith\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-an-mvc-portlet}{Creating\nan MVC Portlet}.\n\n\\chapter{Creating an MVC Portlet}\\label{creating-an-mvc-portlet}\n\nGenerating MVC portlet projects is a snap using Liferay's project\ntemplates. Here you'll generate an MVC Portlet project and deploy the\nportlet to Liferay DXP.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Generate an\n \\href{/docs/7-2/reference/-/knowledge_base/r/using-the-mvc-portlet-template}{MVC\n Portlet project} using a Gradle or Maven.\n\n Here's the resulting folder structure for an MVC Portlet class named\n \\texttt{MyMvcPortlet} in a base package\n \\texttt{com.liferay.docs.mvcportlet}:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{my-mvc-portlet-project} → Arbitrary project name.\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{gradle}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{wrapper}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{gradle-wrapper.jar}\n \\item\n \\texttt{gradle-wrapper.properties}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{src}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com/liferay/docs/mvcportlet}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{constants}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{MyMvcPortletKeys.java} → Declares portlet\n constants.\n \\end{itemize}\n \\item\n \\texttt{portlet}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{MyMvcPortlet.java} → MVC Portlet class.\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{resources}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{content}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{Language.properties} → Resource bundle\n \\end{itemize}\n \\item\n \\texttt{META-INF}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{resources}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{init.jsp} → Imports classes and taglibs and\n defines commonly used objects from the theme and the\n portlet.\n \\item\n \\texttt{view.jsp} → Default view template.\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{bnd.bnd} → OSGi bundle metadata.\n \\item\n \\texttt{build.gradle}\n \\item\n \\texttt{gradlew}\n \\end{itemize}\n \\end{itemize}\n\n The Maven-generated project includes a \\texttt{pom.xml} file and does\n not include the Gradle-specific files, but otherwise is exactly the\n same.\n\n Here's the resulting MVC Portlet class:\n\\end{enumerate}\n\n\\begin{verbatim}\npackage com.liferay.docs.mvcportlet.portlet;\n\nimport com.liferay.docs.mvcportlet.constants.MyMvcPortletKeys;\nimport com.liferay.portal.kernel.portlet.bridges.mvc.MVCPortlet;\nimport javax.portlet.Portlet;\nimport org.osgi.service.component.annotations.Component;\n\n@Component(\n immediate = true,\n property = {\n \"com.liferay.portlet.display-category=category.sample\",\n \"com.liferay.portlet.instanceable=true\",\n \"javax.portlet.display-name=my-mvc-portlet-project Portlet\",\n \"javax.portlet.init-param.template-path=/\",\n \"javax.portlet.init-param.view-template=/view.jsp\",\n \"javax.portlet.name=\" + MyMvcPortletKeys.MyMvc,\n \"javax.portlet.resource-bundle=content.Language\",\n \"javax.portlet.security-role-ref=power-user,user\"\n },\n service = Portlet.class\n)\npublic class MyMvcPortlet extends MVCPortlet {\n}\n\\end{verbatim}\n\nThe class extends\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCPortlet.html}{\\texttt{MVCPortlet}}.\nThe\n\\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\nannotation and \\texttt{service\\ =\\ Portlet.class} attribute makes the\nclass an OSGi Declarative Services component that provides the\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/Portlet.html}{\\texttt{javax.portlet.Portlet}}\nservice type. The \\texttt{immediate\\ =\\ true} attribute activates the\nservice immediately on the portlet's deployment.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{1}\n\\item\n Set any portlet configuration or Liferay portlet configuration values\n using \\texttt{javax.portlet.*} and \\texttt{com.liferay.portlet.*}\n \\texttt{@Component} annotation properties\n \\href{/docs/7-2/reference/-/knowledge_base/r/portlet-descriptor-to-osgi-service-property-map}{\\texttt{javax.portlet.*}\n and \\texttt{com.liferay.portlet.*} \\texttt{@Component} annotation\n properties} respectively.\n\n Here are the example component's properties:\n\n \\begin{itemize}\n \\item\n \\texttt{\"com.liferay.portlet.display-category=category.sample\"}:\n Sets the Widget's category to ``Sample''.\n \\item\n \\texttt{\"com.liferay.portlet.instanceable=true\"}: Activates the\n component immediately when its bundle installs.\n \\item\n \\texttt{\"javax.portlet.display-name=my-mvc-portlet-project\\ Portlet\"}:\n Sets the portlet's Widget name.\n \\item\n \\texttt{\"javax.portlet.init-param.template-path=/\"}: The path under\n \\texttt{src/main/resources/META-INF/resources/} where the templates\n reside.\n \\item\n \\texttt{\"javax.portlet.init-param.view-template=/view.jsp\"}: Default\n view template.\n \\item\n \\texttt{\"javax.portlet.name=\"\\ +\\ MyMvcPortletKeys.MyMvc}: The\n portlet's unique identity.\n \\item\n \\texttt{\"javax.portlet.resource-bundle=content.Language\"}: Sets the\n portlet's\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{resource\n bundle} to the \\texttt{content/Language*.properties} file(s) in the\n \\texttt{src/main/resources/} folder.\n \\item\n \\texttt{\"javax.portlet.security-role-ref=power-user,user\"}: Makes\n the Liferay DXP virtual instance's power user and user Roles\n available for defining the portlet's permissions.\n \\end{itemize}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** To opt-in to Portlet 3.0 features, set the component property\n `\"javax.portlet.version=3.0\"`.\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{2}\n\\item\n The portlet renders content via the view template\n \\texttt{src/main/resources/META-INF/resources/view.jsp} by default.\n\\item\n Build your project.\n\n \\emph{Gradle:}\n\n\\begin{verbatim}\ngradlew jar\n\\end{verbatim}\n\n \\emph{Maven:}\n\n\\begin{verbatim}\nmvn clean package\n\\end{verbatim}\n\\item\n Deploy the project\n \\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{using\n your build environment} or by building the project JAR and copying it\n to the \\texttt{deploy/} folder in your\n \\href{/docs/7-2/deploy/-/knowledge_base/d/liferay-home}{Liferay Home}.\n\\end{enumerate}\n\nThe MVC Portlet is now available in the Liferay DXP UI, in the Widget\ncategory you assigned it.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/default-mvc-portlet-on-page.png}\n\\caption{The example portlet shows a message defined by the language\nproperty \\texttt{yourmvc.caption=Hello\\ from\\ YourMVC!} in the\nLanguage.properties file.}\n\\end{figure}\n\nCongratulations on creating and deploying an MVC Portlet!\n\n\\section{Related Topics}\\label{related-topics-3}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/writing-mvc-portlet-controller-code}{Writing\nMVC Portlet Controller Code}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configuring\nthe View Layer}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command}\n\n\\chapter{Writing MVC Portlet Controller\nCode}\\label{writing-mvc-portlet-controller-code}\n\nIn MVC, your controller is a traffic director: it provides data to the\nright front-end view for display to the user, and it takes data the user\nentered in the front-end and passes it to the right back-end service.\nFor this reason, the controller must process requests from the\nfront-end, and it must determine the right front-end view to pass data\nback to the user.\n\nIf you have a small application that's not heavy on controller logic,\nyou can put all your controller code in the \\texttt{-Portlet} class. If\nyou have more complex needs (lots of actions, complex render logic to\nimplement, or maybe even some resource serving code), consider breaking\nthe controller into\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand classes},\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand classes}, and\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command classes}. Here you'll implement controller logic for\nsmall applications, where all the controller code is in the\n\\texttt{-Portlet} class. It involves these things:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Action methods\n\\item\n Render logic\n\\item\n Setting and retrieving request parameters and attributes\n\\end{itemize}\n\nStart with creating action methods.\n\n\\section{Action Methods}\\label{action-methods}\n\nYour portlet class can act as your controller by itself and process\nrequests using action methods. Here's a sample action method:\n\n\\begin{verbatim}\npublic void addGuestbook(ActionRequest request, ActionResponse response)\n throws PortalException, SystemException {\n\n ServiceContext serviceContext = ServiceContextFactory.getInstance(\n Guestbook.class.getName(), request);\n\n String name = ParamUtil.getString(request, \"name\");\n\n try {\n _guestbookService.addGuestbook(serviceContext.getUserId(),\n name, serviceContext);\n\n SessionMessages.add(request, \"guestbookAdded\");\n\n } catch (Exception e) {\n SessionErrors.add(request, e.getClass().getName());\n\n response.setRenderParameter(\"mvcPath\",\n \"/html/guestbook/edit_guestbook.jsp\");\n }\n\n}\n\\end{verbatim}\n\nThis action method has one job: call a service to add a guestbook. If\nthe call succeeds, the message \\texttt{\"guestbookAdded\"} is associated\nwith the request and added to the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/servlet/SessionMessages.html}{\\texttt{SessionMessages}\nobject}. If an exception is thrown, it's caught, and the class name is\nassociated with the request and added to the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/servlet/SessionErrors.html}{\\texttt{SessionErrors}\nobject}, and the response is set to render \\texttt{edit\\_guestbook.jsp}.\nSetting the \\texttt{mvcPath} render parameter is a Liferay\n\\texttt{MVCPortlet} framework convention that denotes the next view to\nrender to the user.\n\nWhile action methods respond to user actions, render logic determines\nthe view to display to the user. Render logic is next.\n\n\\section{Render Logic}\\label{render-logic}\n\nHere's how MVC Portlet determines which view to render. Note the\n\\texttt{init-param} properties you set in your component:\n\n\\begin{verbatim}\n\"javax.portlet.init-param.template-path=/\",\n\"javax.portlet.init-param.view-template=/view.jsp\",\n\\end{verbatim}\n\nThe \\texttt{template-path} property tells the MVC framework where your\nJSP files live. In the above example, \\texttt{/} means that the JSP\nfiles are in your project's root \\texttt{resources} folder. That's why\nit's important to follow Liferay's standard folder structure. The\n\\texttt{view-template} property directs the default rendering to\n\\texttt{view.jsp}.\n\nHere's the path of a hypothetical Web module's resource folder:\n\n\\begin{verbatim}\ndocs.liferaymvc.web/src/main/resources/META-INF/resources\n\\end{verbatim}\n\nBased on that resource folder, the \\texttt{view.jsp} file is found at\n\n\\begin{verbatim}\ndocs.liferaymvc.web/src/main/resources/META-INF/resources/view.jsp\n\\end{verbatim}\n\nand that's the application's default view. When the portlet's\n\\texttt{init} method (e.g., your portlet's override of\n\\texttt{MVCPortlet.init()}) is called, Liferay reads the initialization\nparameters you specify and directs rendering to the default JSP.\nThroughout the controller, you can render different views (JSP files) by\nsetting the render parameter \\texttt{mvcPath} like this:\n\n\\begin{verbatim}\nactionResponse.setRenderParameter(\"mvcPath\", \"/error.jsp\");\n\\end{verbatim}\n\nYou can avoid render logic by using initialization parameters and render\nparameters, but most of the time you'll override the portlet's\n\\texttt{render} method. Here's an example:\n\n\\begin{verbatim}\n@Override\npublic void render(RenderRequest renderRequest,\n RenderResponse renderResponse) throws PortletException, IOException {\n\n try {\n ServiceContext serviceContext = ServiceContextFactory.getInstance(\n Guestbook.class.getName(), renderRequest);\n\n long groupId = serviceContext.getScopeGroupId();\n\n long guestbookId = ParamUtil.getLong(renderRequest, \"guestbookId\");\n\n List guestbooks = _guestbookService\n .getGuestbooks(groupId);\n\n if (guestbooks.size() == 0) {\n Guestbook guestbook = _guestbookService.addGuestbook(\n serviceContext.getUserId(), \"Main\", serviceContext);\n\n guestbookId = guestbook.getGuestbookId();\n\n }\n\n if (!(guestbookId > 0)) {\n guestbookId = guestbooks.get(0).getGuestbookId();\n }\n\n renderRequest.setAttribute(\"guestbookId\", guestbookId);\n\n } catch (Exception e) {\n\n throw new PortletException(e);\n }\n\n super.render(renderRequest, renderResponse);\n\n}\n\\end{verbatim}\n\nThis render logic provides the view layer with data to display to the\nuser. The \\texttt{render} method above sets the render request attribute\n\\texttt{guestbookId} with the ID of a guestbook to display. If\nguestbooks exist, it chooses the first. Otherwise, it creates a\nguestbook and sets it to display. Lastly the method passes the render\nrequest and render response objects to the base class via its\n\\texttt{render} method.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Are you wondering how to call\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder services} in 7.0? In short, obtain a reference to the service by\nannotating one of your fields of that service type with the\n\\texttt{@Reference}\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{Declarative\nServices} annotation.\n\n\\texttt{@Reference\\ \\ private\\ GuestbookService\\ \\_guestbookService;}\n\nOnce done, you can call the service's methods.\n\n\\texttt{\\_guestbookService.addGuestbook(serviceContext.getUserId(),\\ \"Main\",\\ \\ \\ \\ \\ \\ \\ \\ \\ \\ serviceContext);}\n\n\\noindent\\hrulefill\n\nBefore venturing into the view layer, the next section demonstrates ways\nto pass information between the controller and view layers.\n\n\\section{Setting and Retrieving Request and Response Parameters and\nAttributes}\\label{setting-and-retrieving-request-and-response-parameters-and-attributes}\n\nA handy utility class called\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/util/ParamUtil.html}{\\texttt{ParamUtil}}\nfacilitates retrieving parameters from an\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/ActionRequest.html}{\\texttt{ActionRequest}}\nor a\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/RenderRequest.html}{\\texttt{RenderRequest}}.\n\nFor example, this JSP passes a parameter named \\texttt{guestbookId} in\nan action URL.\n\n\\begin{verbatim}\n\n \" />\n\n\\end{verbatim}\n\nThe \\texttt{\\textless{}portlet:actionURL\\textgreater{}} tag's\n\\texttt{name} attribute maps the action URL to a controller action\nmethod named \\texttt{doSomething}. Triggering an action URL invokes the\ncorresponding method in the controller.\n\nThe controller's \\texttt{doSomething} method referenced in this example\ngets the \\texttt{guestbookId} parameter value from the\n\\texttt{ActionRequest}.\n\n\\begin{verbatim}\nlong guestbookId = ParamUtil.getLong(actionRequest, \"guestbookId\");\n\\end{verbatim}\n\nTo pass information back to the view layer, the controller code can set\nrender parameters on response objects.\n\n\\begin{verbatim}\nactionResponse.setRenderParameter(\"mvcPath\", \"/error.jsp\");\n\\end{verbatim}\n\nThe code above sets a parameter called \\texttt{mvcPath} to JSP path\n\\texttt{/error.jsp}. This causes the controller's render method to\nredirect the user to that JSP.\n\nYour controller class can also set attributes into response objects\nusing the \\texttt{setAttribute} method.\n\n\\begin{verbatim}\nrenderResponse.setAttribute(\"guestbookId\", guestbookId);\n\\end{verbatim}\n\nJSPs can use Java code in scriptlets to interact with the request\nobject.\n\n\\begin{verbatim}\n<%\n long guestbookId = Long.valueOf((Long) renderRequest\n .getAttribute(\"guestbookId\"));\n%>\n\\end{verbatim}\n\nPassing information back and forth from your view and controller is\nimportant, but there's more to the view layer than that. The view layer\nis up next.\n\n\\section{Related Topics}\\label{related-topics-4}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-an-mvc-portlet}{Creating\nan MVC Portlet}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configuring\nthe View Layer}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command}\n\n\\chapter{Configuring the View Layer}\\label{configuring-the-view-layer}\n\nThis section briefly covers how to get your view layer working, from\norganizing your imports in one JSP file, to creating URLs that direct\nprocessing to methods in your portlet class.\n\n\\noindent\\hrulefill\n\nNote: As you create JSPs, you can\n\\href{/docs/7-1/tutorials/-/knowledge_base/t/applying-clay-styles-to-your-app}{apply\nClay styles to your app to match Liferay's apps}.\n\n\\noindent\\hrulefill\n\n\\section{Using the init.jsp}\\label{using-the-init.jsp}\n\nLiferay's practice puts all Java imports, tag library declarations, and\nvariable initializations into a JSP called \\texttt{init.jsp}. If you use\n\\href{/docs/7-1/tutorials/-/knowledge_base/t/blade-cli}{Blade CLI} or\n\\href{/docs/7-1/tutorials/-/knowledge_base/t/liferay-ide}{Liferay Dev\nStudio DXP} to create a module based on the \\texttt{mvc-portlet} project\ntemplate, these taglib declarations and initializations are added\nautomatically to your \\texttt{init.jsp}:\n\n\\begin{verbatim}\n<%@ taglib uri=\"http://java.sun.com/jsp/jstl/core\" prefix=\"c\" %>\n\n<%@ taglib uri=\"http://java.sun.com/portlet_2_0\" prefix=\"portlet\" %>\n\n<%@ taglib uri=\"http://liferay.com/tld/aui\" prefix=\"aui\" %>\n<%@ taglib uri=\"http://liferay.com/tld/portlet\" prefix=\"liferay-portlet\" %>\n<%@ taglib uri=\"http://liferay.com/tld/theme\" prefix=\"liferay-theme\" %>\n<%@ taglib uri=\"http://liferay.com/tld/ui\" prefix=\"liferay-ui\" %>\n\n\n\n\n\\end{verbatim}\n\nHere are the tag libraries it gives you:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/c/tld-frame.html}{\\texttt{c}}:\n JSTL core tags.\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/portlet/tld-frame.html}{\\texttt{portlet}}:\n Standard portlet component tags.\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/aui/tld-summary.html}{\\texttt{aui}}:\n \\href{https://alloyui.com/}{AlloyUI} component tags.\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/liferay-portlet/tld-frame.html}{\\texttt{liferay-portlet}}:\n Liferay portlet component tags.\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/liferay-theme/tld-frame.html}{\\texttt{liferay-theme}}:\n Liferay theme component tags.\n\\item\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/taglibs/util-taglib/liferay-ui/tld-frame.html}{\\texttt{liferay-ui}}:\n Liferay UI component tags.\n\\end{itemize}\n\nThese tags make portlet and Liferay objects available:\n\n\\begin{itemize}\n\\item\n \\texttt{\\textless{}portlet:defineObjects\\ /\\textgreater{}}: Implicit\n Java variables that reference Portlet API objects. The objects\n available are limited to those available in the current portlet\n request. For details, see the \\texttt{defineObjects} tag in\n \\href{https://jcp.org/en/jsr/detail?id=286}{JSR-286}.\n\\item\n \\texttt{\\textless{}liferay-theme:defineObjects\\ /\\textgreater{}}:\n Implicit Java variables that reference Liferay objects.\n\\end{itemize}\n\nTo use all that the \\texttt{init.jsp} has, include it in your other\nJSPs:\n\n\\begin{verbatim}\n<%@include file=\"/html/init.jsp\"%>\n\\end{verbatim}\n\nA JSP uses render URLs to display other pages and action URLs to invoke\ncontroller methods.\n\n\\section{Using Render URLs}\\label{using-render-urls}\n\nA render URL attached to a UI component action displays another page.\nFor example, this render URL displays the JSP \\texttt{/path/to/foo.jsp}.\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\nHere's how to use a render URL:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Add a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/renderURL.html}{\\texttt{\\textless{}portlet:renderURL\\textgreater{}}}\n to your JSP.\n\\item\n Name the render URL via a \\texttt{var} attribute in the\n \\texttt{\\textless{}portlet:renderURL\\textgreater{}} tag. The\n \\texttt{\\textless{}portlet:renderURL\\textgreater{}} tag constructs the\n URL and assigns it to the variable. For example, this render URL is\n assigned to the variable named \\texttt{adminURL}:\n\n\\begin{verbatim}\n\n ...\n\n\\end{verbatim}\n\\item\n As sub-element to the\n \\texttt{\\textless{}portlet:renderURL\\textgreater{}} tag, add a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/param.html}{\\texttt{\\textless{}portlet:param\\textgreater{}}}\n tag with the following attributes:\n\n \\texttt{name=\"mvcPath\"}: Your controller's \\texttt{render} method\n forwards processing to the JSP at the path specified in the\n \\texttt{value}.\n\n \\texttt{value=\"/path/to/foo.jsp\"}: The path to the JSP to render.\n Replace the value \\texttt{/path/to/foo.jsp} with your JSP path.\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\\item\n To invoke the render URL, assign its variable (\\texttt{var}) to a UI\n component action, such as a button or navigation bar item action.\n\\end{enumerate}\n\nInvoking the UI component causes the controller's render method to\ndisplay the \\texttt{mvcPath} parameter's JSP.\n\n\\section{Using Action URLs}\\label{using-action-urls}\n\nAction methods are different because they invoke an action (i.e., code),\nrather than link to another page. For example, this action URL invokes a\ncontroller method called \\texttt{doSomething} and passes a parameter\ncalled \\texttt{redirect}. The \\texttt{redirect} parameter contains the\npath of the JSP to render after invoking the action:\n\n\\begin{verbatim}\n\n \" />\n\n\\end{verbatim}\n\nHere's how to use an action URL:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Add a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/actionURL.html}{\\texttt{\\textless{}portlet:actionURL\\textgreater{}}}\n to your JSP.\n\\item\n Add a \\texttt{name} and \\texttt{var} attribute to the\n \\texttt{\\textless{}portlet:actionURL\\textgreater{}}. The\n \\texttt{\\textless{}portlet:actionURL\\textgreater{}} tag constructs the\n URL and assigns it to the \\texttt{var} variable.\n\n \\texttt{name}: Controller action to invoke.\n\n \\texttt{var}: Variable to assign the action URL to.\n\n\\begin{verbatim}\n\n ...\n\n\\end{verbatim}\n\\item\n As sub-element to the\n \\texttt{\\textless{}portlet:actionURL\\textgreater{}} tag, add a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/param.html}{\\texttt{\\textless{}portlet:param\\textgreater{}}}\n tag that has the following attributes:\n\n \\texttt{name=\"redirect\"}: Tells the portlet to redirect to the JSP\n associated with this parameter.\n\n \\texttt{value=\"/path/to/foo.jsp\"}: Redirects the user to this JSP path\n after invoking the action. Replace the value \\texttt{/path/to/bar.jsp}\n with your JSP path.\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\\item\n To invoke the action URL, assign its variable (\\texttt{var}) to a UI\n component action, such as a button or navigation bar item action.\n\\end{enumerate}\n\nCongratulations! Your portlet is ready for action.\n\nThese simple examples demonstrate how Liferay MVC Portlet facilitates\ncommunication between a smaller application's view layer and controller.\n\n\\section{Related Topics}\\label{related-topics-5}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/writing-mvc-portlet-controller-code}{Writing\nMVC Portlet Controller Code}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/front-end-taglibs}{Front-end\nTaglibs}\n\n\\href{https://portal.liferay.dev/docs/7-2/reference/-/knowledge_base/r/liferay-javascript-apis}{Liferay\nJavaScript APIs}\n\n\\chapter{MVC Action Command}\\label{mvc-action-command}\n\nLiferay's MVC Portlet framework enables you to handle\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{MVCPortlet}\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer\\#using-action-urls}{actions}\nin separate classes. This facilitates managing action logic in portlets\nthat have many actions. Each action URL in your portlet's JSPs invokes\nan appropriate action command class.\n\nHere are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configure\n your JSPs} to use action URLs via\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/actionURL.html}{\\texttt{\\textless{}portlet:actionURL\\textgreater{}}}\n tags. For example, the\n \\href{https://github.com/liferay/liferay-blade-samples/blob/7.1/gradle/apps/action-command-portlet/src/main/resources/META-INF/resources/view.jsp}{action-command-portlet}\n sample uses this action URL:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\n Name the action URL via its \\texttt{name} attribute. Your\n \\texttt{*MVCActionCommand} class maps to this name. Assign the\n \\texttt{var} attribute a variable name.\n\\item\n Assign the action URL variable (\\texttt{var}) to a UI component.\n Acting on the UI component invokes the action. For example, the\n sample's \\texttt{greetURL} action URL variable triggers on submitting\n this form:\n\n\\begin{verbatim}\n\" method=\"post\" name=\"fm\">\n \n\n \n \n \n\n\\end{verbatim}\n\\item\n Create a class that implements the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCActionCommand.html}{\\texttt{MVCActionCommand}}\n interface, or that extends the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/BaseMVCActionCommand.html}{\\texttt{BaseMVCActionCommand}}\n class. The latter may save you time, since it already implements\n \\texttt{MVCActionCommand}.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Tip:** Naming your `*MVCActionCommand` class after the action it \n performs makes the action mappings more obvious for maintaining the code.\n For example, if your action class edits some kind of entry, you could name\n its class `EditEntryMVCActionCommand`. If your application has several MVC\n command classes, naming them this way helps differentiate them. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\item\n Annotate your class with an\n \\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\n annotation, like this one:\n\n\\begin{verbatim}\n@Component(\n property = {\n \"javax.portlet.name=your_portlet_name_YourPortlet\",\n \"mvc.command.name=/your/jsp/action/url\"\n },\n service = MVCActionCommand.class\n)\n\\end{verbatim}\n\\item\n Set a \\texttt{javax.portlet.name} property to your portlet's internal\n ID.\n\n Note, you can apply MVC Command classes to multiple portlets by\n setting a \\texttt{javax.portlet.name} property for each portlet. For\n example, the \\texttt{javax.portlet.name} properties in this component\n apply it to three specific portlets.\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n property = {\n \"javax.portlet.name=\" + BlogsPortletKeys.BLOGS,\n \"javax.portlet.name=\" + BlogsPortletKeys.BLOGS_ADMIN,\n \"javax.portlet.name=\" + BlogsPortletKeys.BLOGS_AGGREGATOR,\n \"mvc.command.name=/blogs/edit_entry\"\n },\n service = MVCActionCommand.class\n)\npublic class EditEntryMVCActionCommand extends BaseMVCActionCommand {\n ...\n}\n\\end{verbatim}\n\\item\n Set the \\texttt{mvc.command.name} property to your\n \\texttt{\\textless{}portlet:actionURL\\textgreater{}} tag's\n \\texttt{name}. This maps your class to the action URL of the same\n name.\n\\item\n Register your class as an \\texttt{MVCActionCommand} service by setting\n the \\texttt{service} attribute to \\texttt{MVCActionCommand.class}.\n\\item\n Implement your action logic by overriding the appropriate method of\n the class you're implementing or extending.\n\n \\begin{itemize}\n \\item\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCActionCommand.html}{\\texttt{MVCActionCommand}}\n implementations override the \\texttt{processAction} method.\n \\item\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/BaseMVCActionCommand.html}{\\texttt{BaseMVCActionCommand}}\n extensions override the \\texttt{doProcessAction} method.\n \\end{itemize}\n\n Here's an example of overriding \\texttt{MVCActionCommand}'s\n \\texttt{processAction} method. This action logic gets the name\n parameter from the \\texttt{ActionRequest} and adds it to the session\n messages and to an \\texttt{ActionRequest} attribute.\n\n\\begin{verbatim}\n@Override\npublic boolean processAction(\n ActionRequest actionRequest, ActionResponse actionResponse)\n throws PortletException {\n\n _handleActionCommand(actionRequest);\n\n return true;\n}\n\nprivate void _handleActionCommand(ActionRequest actionRequest) {\n String name = ParamUtil.get(actionRequest, \"name\", StringPool.BLANK);\n\n if (_log.isInfoEnabled()) {\n _log.info(\"Hello \" + name);\n }\n\n String greetingMessage = \"Hello \" + name + \"! Welcome to OSGi\";\n\n actionRequest.setAttribute(\"GREETER_MESSAGE\", greetingMessage);\n\n SessionMessages.add(actionRequest, \"greetingMessage\", greetingMessage);\n}\n\nprivate static final Log _log = LogFactoryUtil.getLog(\n GreeterActionCommand.class);\n\\end{verbatim}\n\\end{enumerate}\n\nCongratulations! You've created an \\texttt{MVCActionCommand} that\nhandles your portlet actions.\n\n\\section{Related Topics}\\label{related-topics-6}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-an-mvc-portlet}{Creating\nan MVC Portlet}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configuring\nthe View Layer}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-liferay-mvc-commands}{MVC\nCommand Overrides}\n\n\\chapter{MVC Render Command}\\label{mvc-render-command}\n\n\\texttt{MVCRenderCommand}s are classes that respond to\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{MVCPortlet}\n\\href{/docs/7-2/appdev/-/knowledge_base/a/writing-mvc-portlet-controller-code\\#render-logic}{render\nURLs}. If your render logic is simple and you want to implement all of\nyour render logic in your portlet class, see\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{Writing\nMVC Portlet Controller Code}. If your render logic is complex or you\nwant clean separation between render paths, use\n\\texttt{MVCRenderCommand}s. Each render URL in your portlet's JSPs\ninvokes an appropriate render command class.\n\nHere are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configure\n your JSPs} to generate render URLs via\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/renderURL.html}{\\texttt{\\textless{}portlet:renderURL\\textgreater{}}}\n tags.\n\n For example, this\n \\href{https://github.com/liferay/liferay-blade-samples/tree/7.1/gradle/apps/render-command-portlet}{render-command-portlet}\n sample render URL invokes an MVC render command named\n \\texttt{/blade/render}.\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\\item\n Name the render URL via its\n \\texttt{\\textless{}portlet:param\\textgreater{}} named\n \\texttt{mvcRenderCommandName}. The render URL and\n \\texttt{*MVCRenderCommand} class (demonstrated later) map to the\n \\texttt{mvcRenderCommandName} value.\n\\item\n Assign the \\texttt{\\textless{}portlet:renderURL\\textgreater{}}'s\n \\texttt{var} attribute a variable name to pass to a UI component.\n\\item\n Assign the render URL variable (\\texttt{var}) to a UI component. When\n the user triggers the UI component, the \\texttt{*MVCRenderCommand}\n class that matches the render URL handles the render request.\n\n For example, the render URL with the variable \\texttt{bladeRender}\n triggers on users clicking this button.\n\n\\begin{verbatim}\n\" value=\"goto page render\" />\n\\end{verbatim}\n\\item\n Create a class that implements the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCRenderCommand.html}{\\texttt{MVCRenderCommand}}\n interface.\n\\item\n Annotate the class with an\n \\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\n annotation, like this one:\n\n\\begin{verbatim}\n@Component(\n property = {\n \"javax.portlet.name=com_liferay_blade_samples_portlet_rendercommand_BladeRenderPortlet\",\n \"mvc.command.name=/blade/render\"\n },\n service = MVCRenderCommand.class\n)\n\\end{verbatim}\n\\item\n Set a \\texttt{javax.portlet.name} property to your portlet's internal\n ID.\n\\item\n Set a \\texttt{mvc.command.name} property to your\n \\texttt{\\textless{}portlet:renderURL\\textgreater{}} tag\n \\texttt{mvcRenderCommandName} portlet parameter value. This maps your\n class to the render URL.\n\\item\n Register your class as an \\texttt{MVCRenderCommand} service by setting\n the \\texttt{service} attribute to \\texttt{MVCRenderCommand.class}.\n\n Note, you can apply MVC Command classes to multiple portlets by\n setting a \\texttt{javax.portlet.name} property for each portlet and\n apply MVC Command classes to multiple command names by setting an\n \\texttt{mvc.command.name} property for each command name. For example,\n this component's \\texttt{javax.portlet.name} properties and\n \\texttt{mvc.command.name} properties apply it to two specific portlets\n and two specific command names.\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n property = {\n \"javax.portlet.name=\" + HelloWorldPortletKeys.HELLO_MY_WORLD,\n \"javax.portlet.name=\" + HelloWorldPortletKeys.HELLO_WORLD,\n \"mvc.command.name=/hello/edit_super_entry\",\n \"mvc.command.name=/hello/edit_entry\"\n },\n service = MVCRenderCommand.class\n)\n\\end{verbatim}\n\\item\n Implement your render logic in a method that overrides\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCRenderCommand.html}{\\texttt{MVCRenderCommand}}'s\n \\texttt{render} method. Some \\texttt{*MVCRenderCommand}s, such as the\n one below, always render the same JSP.\n\n\\begin{verbatim}\npublic class BlogsViewMVCRenderCommand implements MVCRenderCommand {\n\n @Override\n public String render(\n RenderRequest renderRequest, RenderResponse renderResponse) {\n\n return \"/blogs/view.jsp\";\n }\n\n}\n\\end{verbatim}\n\\end{enumerate}\n\nAs you can see, MVC render commands are easy to implement and can\nrespond to multiple command names for multiple portlets.\n\n\\section{Related Topics}\\label{related-topics-7}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-an-mvc-portlet}{Creating\nan MVC Portlet}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configuring\nthe View Layer}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-resource-command}{MVC\nResource Command}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-liferay-mvc-commands}{MVC\nCommand Overrides}\n\n\\chapter{MVC Resource Command}\\label{mvc-resource-command}\n\nWhen using Liferay's\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{MVCPortlet\nframework}, you can create resource URLs in your JSPs to retrieve\nimages, XML, or any other kind of resource from a Liferay DXP instance.\nThe resource URL then invokes the corresponding MVC resource command\nclass (\\texttt{*MVCResourceCommand}) that processes the resource request\nand response.\n\nHere how to create your own MVC Resource Command:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configure\n your JSPs} to generate resource URLs via\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/portlet/resourceURL.html}{\\texttt{\\textless{}portlet:resourceURL\\textgreater{}}}\n tags.\n\n For example, this\n \\href{https://github.com/liferay/liferay-blade-samples/tree/7.1/gradle/apps/resource-command-portlet}{resource-command-portlet}\n sample resource URL invokes an MVC resource command named\n \\texttt{/blade/captcha}.\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\\item\n Name the resource URL via its \\texttt{id} attribute.\n\\item\n Assign the resource URL's \\texttt{var} attribute a variable name to\n pass to a UI component.\n\\item\n Assign the resource URL variable (\\texttt{var}) to a UI component,\n such as a button or icon. When the user triggers the UI component, the\n \\texttt{*MVCResourceCommand} class that matches the resource URL\n handles the resource request.\n\n For example, the sample's resource URL is triggered when the user\n clicks on this\n \\href{https://docs.liferay.com/dxp/apps/foundation/latest/taglibdocs/liferay-captcha/captcha.html}{\\texttt{liferay-captcha}}\n component:\n\n\\begin{verbatim}\n\" />\n\\end{verbatim}\n\\item\n Create a class that implements the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCResourceCommand.html}{\\texttt{MVCResourceCommand}}\n interface, or that extends the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/BaseMVCResourceCommand.html}{\\texttt{BaseMVCResourceCommand}}\n class. The latter may save you time, since it already implements\n \\texttt{MVCResourceCommand}.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Tip:** Naming your `*MVCResourceCommand` class after the resource it \n provides makes the resource mappings more obvious for maintaining the\n code. For example, if your resource URL serves a captcha, you could name\n its class `CaptchaMVCResourceCommand`. If your application has several MVC\n command classes, naming them this way helps differentiate them. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{5}\n\\item\n Annotate your class with an\n \\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\n annotation, like this one:\n\n\\begin{verbatim}\n@Component(\n property = {\n \"javax.portlet.name=your_portlet_name_YourPortlet\",\n \"mvc.command.name=/your/jsp/resource/url\"\n },\n service = MVCResourceCommand.class\n)\npublic class YourMVCResourceCommand extends BaseMVCResourceCommand {\n // your resource handling code\n}\n\\end{verbatim}\n\n \\begin{enumerate}\n \\def\\labelenumii{\\arabic{enumii}.}\n \\item\n Set a \\texttt{javax.portlet.name} property to your portlet's\n internal ID.\n \\item\n Set the \\texttt{mvc.command.name} property to your\n \\texttt{\\textless{}portlet:resourceURL\\textgreater{}} tag's\n \\texttt{id}. This maps your class to the resource URL of the same\n name.\n \\item\n Register your class as an \\texttt{MVCResourceCommand} service by\n setting the \\texttt{service} attribute to\n \\texttt{MVCResourceCommand.class}.\n \\end{enumerate}\n\\item\n Implement your resource logic by overriding the appropriate method of\n the class you're implementing or extending.\n\n \\begin{itemize}\n \\item\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCResourceCommand.html}{\\texttt{MVCResourceCommand}}\n implementations override the \\texttt{serveResource} method.\n \\item\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/BaseMVCResourceCommand.html}{\\texttt{BaseMVCResourceCommand}}\n extensions override the \\texttt{doServeResource} method.\n \\end{itemize}\n\\end{enumerate}\n\nFor example, the\n\\href{https://github.com/liferay/liferay-blade-samples/tree/7.1/gradle/apps/resource-command-portlet}{resource-command-portlet}'s\n\\texttt{CaptchaMVCResourceCommand} class implements the\n\\texttt{MVCResourceCommand} interface with only a single method:\n\\texttt{serveResource}.\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n property = {\n \"javax.portlet.name=com_liferay_blade_samples_portlet_resourcecommand_CaptchaPortlet\",\n \"mvc.command.name=/blade/captcha\"\n },\n service = MVCResourceCommand.class\n)\npublic class CaptchaMVCResourceCommand implements MVCResourceCommand {\n\n @Override\n public boolean serveResource(\n ResourceRequest resourceRequest, ResourceResponse resourceResponse)\n throws PortletException {\n\n if (_log.isInfoEnabled()) {\n _log.info(\"get captcha resource \");\n }\n\n try {\n CaptchaUtil.serveImage(resourceRequest, resourceResponse);\n\n return false;\n }\n catch (Exception e) {\n _log.error(e.getMessage(), e);\n\n return true;\n }\n }\n\n private static final Log _log = LogFactoryUtil.getLog(\n CaptchaMVCResourceCommand.class);\n\n}\n\\end{verbatim}\n\nThis \\texttt{serveResource} method processes the resource request and\nresponse via the \\texttt{javax.portlet.ResourceRequest} and\n\\texttt{javax.portlet.ResourceResponse} parameters, respectively. Note\nthat the \\texttt{try} block uses the helper class\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/captcha/CaptchaUtil.html}{\\texttt{CaptchaUtil}}\nto serve the CAPTCHA image. Though you don't have to create such a\nhelper class, doing so often simplifies your code.\n\nGreat! Now you know how to use \\texttt{MVCResourceCommand} to process\nresources in your Liferay MVC Portlets.\n\n\\section{Related Topics}\\label{related-topics-8}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-an-mvc-portlet}{Creating\nan MVC Portlet}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/configuring-the-view-layer}{Configuring\nthe View Layer}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-render-command}{MVC Render\nCommand}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/mvc-action-command}{MVC Action\nCommand}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-liferay-mvc-commands}{MVC\nCommand Overrides}\n\n\\chapter{PortletMVC4Spring}\\label{portletmvc4spring}\n\nPortletMVC4Spring is a way to develop portlets using the Spring\nFramework and the Model View Controller (MVC) pattern. While the Spring\nFramework supports developing \\emph{servlet-based} web applications\nusing\n\\href{https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html}{Spring\nWeb MVC}, PortletMVC4Spring supports developing \\emph{portlet-based}\napplications using MVC. You can build\n\\href{https://spring.io/projects/spring-framework}{Spring Framework}\nLiferay DXP portlets with features like these:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Inversion of control (IoC) / dependency injection (DI)\n\\item\n Annotations\n\\item\n Security\n\\item\n Binding and validation\n\\item\n Multi-part file upload\n\\item\n \\ldots{} and more\n\\end{itemize}\n\nYou'll learn these things about PortletMVC4Spring:\n\n\\begin{itemize}\n\\item\n \\textbf{Developing a Portlet Using PortletMVC4Spring:} Demonstrates\n creating and deploying a portlet using PortletMVC4Spring.\n\\item\n \\textbf{Annotation-based Controller Development:} Shows how to\n implement controllers using plain old Java objects (POJOs) and\n annotations.\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Background:} The PortletMVC4Spring project began as Spring\nPortlet MVC and was part of the\n\\href{https://spring.io/projects/spring-framework}{Spring Framework}.\nWhen the project was pruned from version 5.0.x of the Spring Framework\nunder\n\\href{https://github.com/spring-projects/spring-framework/issues/18701}{SPR-14129},\nit became necessary to fork and rename the project. This made it\npossible to improve and maintain the project for compatibility with the\nlatest versions of the Spring Framework and the Portlet API.\n\n\\href{http://www.liferay.com}{Liferay} adopted Spring Portlet MVC in\nMarch of 2019 and the project was renamed to \\textbf{PortletMVC4Spring}.\n\n\\noindent\\hrulefill\n\nIf you're familiar with Spring Web MVC, it's helpful to compare it with\nPortletMVC4Spring. Portlet workflow differs from servlet workflow\nbecause a request to the portlet can have two distinct phases: the\n\\texttt{ACTION\\_PHASE} and the \\texttt{RENDER\\_PHASE}. The\n\\texttt{ACTION\\_PHASE} is executed only once and is where any back-end\nchanges or actions occur, such as making changes in a database. The\n\\texttt{RENDER\\_PHASE} presents the portlet's content to the user each\ntime the display is refreshed. Thus for a single request, the\n\\texttt{ACTION\\_PHASE} is executed only once, but the\n\\texttt{RENDER\\_PHASE} may be executed multiple times. This provides\n(and requires) a clean separation between the activities that modify the\nsystem's persistent state and the activities that generate content. The\nPortlet 2.0 Specification added two more phases: The event phase and the\nresource phase, both of which are supported by annotation-driven\ndispatching.\n\nPortletMVC4Spring provides annotations that support requests from the\nrender, action, event, and resource serving portlet phases; Spring Web\nMVC provides only a \\texttt{@RequestMapping} annotation. Where a Spring\nWeb MVC controller might have a single handler method annotated with\n\\texttt{@RequestMapping}, an equivalent PortletMVC4Spring controller\nmight have multiple handler methods, each using one of the phase\nannotations: \\texttt{@ActionMapping}, \\texttt{@EventMapping},\n\\texttt{@RenderMapping}, or \\texttt{@ResourceMapping}.\n\nThe PortletMVC4Spring framework uses a \\texttt{DispatcherPortlet} that\ndispatches requests to handlers, with configurable handler mappings and\nview resolution, just as the \\texttt{DispatcherServlet} in the web\nframework does.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} For more information on portlets, portlet specifications,\nand how portlets differ from servlets, see\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{Portlets}.\n\n\\noindent\\hrulefill\n\nLiferay also provides full-featured sample portlets that demonstrate\nusing JSP and \\href{https://www.thymeleaf.org}{Thymeleaf} view\ntemplates. They exercise many features that form-based portlet\napplications typically require.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portletmvc4spring-applicant-jsp-app.png}\n\\caption{This PortletMVC4Spring portlet enables users to enter job\napplications. It uses the Spring features mentioned above and handles\nrequests from multiple portlet phases.}\n\\end{figure}\n\nThe samples are available here:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.5000}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.5000}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nSource Code\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nMaven Central\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\href{https://github.com/liferay/portletmvc4spring/tree/master/demo/applicant-jsp-portlet}{applicant-jsp-portlet}\n&\n\\href{https://search.maven.org/search?q=a:com.liferay.portletmvc4spring.demo.applicant.jsp.portlet}{com.liferay.portletmvc4spring.demo.applicant.jsp.portlet.war} \\\\\n\\href{https://github.com/liferay/portletmvc4spring/tree/master/demo/applicant-thymeleaf-portlet}{applicant-thymeleaf-portlet}\n&\n\\href{https://search.maven.org/search?q=a:com.liferay.portletmvc4spring.demo.applicant.thymeleaf.portlet}{com.liferay.portletmvc4spring.demo.applicant.thymeleaf.portlet.war} \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\nNow that you have a basic understanding of PortletMVC4Spring portlets\nand how they compare to Spring Web MVC applications, it's time to\ndevelop a PortletMVC4Spring portlet.\n\n\\chapter{Developing a Portlet Using\nPortletMVC4Spring}\\label{developing-a-portlet-using-portletmvc4spring}\n\nPortletMVC4Spring compliments the Spring Web framework and MVC design\npattern by providing annotations that map portlet requests to Controller\nclasses and methods. Here you'll develop and deploy a portlet\napplication that uses PortletMVC4Spring, Spring, and JSP/JSPX templates.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portletmvc4Spring-developing.png}\n\\caption{The archetype's sample portlet prints a greeting (e.g.,\n\\emph{Hello, Joe Bloggs}) on submitting a first and last name.}\n\\end{figure}\n\nFollow these steps to create and deploy your portlet application:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a PortletMVC4Spring project. See\n \\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-project-anatomy}{PortletMVC4Spring\n Project Anatomy} for the project structure and commands for generating\n PortletMVC4Spring projects. Here's the Maven command for generating\n the JSP/JSPX project. This article lists sample code from the\n generated project.\n\n\\begin{verbatim}\nmvn archetype:generate \\\n-DarchetypeGroupId=com.liferay.portletmvc4spring.archetype \\\n-DarchetypeArtifactId=com.liferay.portletmvc4spring.archetype.form.jsp.portlet \\\n-DarchetypeVersion=5.1.0 \\ \n-DgroupId=com.mycompany \\ \n-DartifactId=com.mycompany.my.form.jsp.portlet\n\\end{verbatim}\n\\item\n In your project's Gradle build file or Maven POM, add your app's\n dependencies. Here are the PortletMVC4Spring development dependencies:\n\n \\textbf{Gradle:}\n\n\\begin{verbatim}\ncompile group: 'com.liferay.portletmvc4spring', name: 'com.liferay.portletmvc4spring.framework', version: '5.1.0'\ncompile group: 'com.liferay.portletmvc4spring', name: 'com.liferay.portletmvc4spring.security', version: '5.1.0'\nprovidedCompile group: 'javax.portlet', name: 'portlet-api', version: '3.0.0'\n\\end{verbatim}\n\n \\textbf{Maven:}\n\n\\begin{verbatim}\n\n com.liferay.portletmvc4spring\n com.liferay.portletmvc4spring.framework\n 5.1.0\n\n\n com.liferay.portletmvc4spring\n com.liferay.portletmvc4spring.security\n 5.1.0\n\n\n javax.portlet\n portlet-api\n 3.0.0\n provided\n\n\\end{verbatim}\n\n At this point you can develop your Model, View, or Controller\n components, in any order.\n\\item\n Create your Model class(es) in a package for models (e.g.,\n \\texttt{java/{[}my-package-path{]}/dto}). The sample Model class is\n \\texttt{User}.\n\n\\begin{verbatim}\npublic class User implements Serializable {\n\n private static final long serialVersionUID = 1234273427623725552L;\n\n @NotBlank\n private String firstName;\n\n @NotBlank\n private String lastName;\n\n public String getFirstName() {\n return firstName;\n }\n\n public void setFirstName(String firstName) {\n this.firstName = firstName;\n }\n\n public String getLastName() {\n return lastName;\n }\n\n public void setLastName(String lastName) {\n this.lastName = lastName;\n }\n}\n\\end{verbatim}\n\\item\n Create your View using a Spring Web-supported template type. If you\n didn't generate your project using the archetype mentioned above,\n specify a View resolver for template type in your\n \\texttt{spring-context/portlet-application-context.xml} portlet\n application context. (See\n \\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-configuration-files}{PortletMVC4Spring\n Configuration Files} for details).\n\n The sample \\texttt{user.jspx} template renders a form for submitting a\n user's first and last name.\n\n\\begin{verbatim}\n\n\n \n \n \n \n \n
\n \n
\n \n \n \n \n \n\n\\end{verbatim}\n\n To invoke actions in your Controller, associate action URLs with your\n templates. The sample template associates the action URL variable\n \\texttt{mainFormActionURL} with its form element.\n\n\\begin{verbatim}\n\n\n ...\n\\end{verbatim}\n\n A \\texttt{\\textless{}form:form/\\textgreater{}} element's\n \\texttt{modelAttribute} attribute targets an application Model. The\n sample template targets the application's \\texttt{user} Model.\n\\item\n Style your portlet by adding CSS to a stylesheet (e.g.,\n \\texttt{webapp/resources/css/main.css}) and linking your template to\n it.\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\\item\n Define your portlet's messages in a properties file (e.g.,\n \\texttt{src/main/resources/content/{[}portlet{]}.properties}). The\n sample \\texttt{user.jspx} template references some of these\n properties:\n\n\\begin{verbatim}\nfirst-name=First Name\ngreetings=Greetings, {0} {1}!\njavax.portlet.display-name=com.mycompany.my.form.jsp.portlet\njavax.portlet.keywords=com.mycompany.my.form.jsp.portlet\njavax.portlet.short-title=com.mycompany.my.form.jsp.portlet\njavax.portlet.title=com.mycompany.my.form.jsp.portlet\nlast-name=Last Name\npersonal-information=Personal Information\nsubmit=Submit\ntodays-date-is=Today''s date is {0}\n\\end{verbatim}\n\\item\n Create a Controller class to handle portlet requests. Here's an\n example:\n\n\\begin{verbatim}\n@Controller\n@RequestMapping(\"VIEW\")\npublic class MyController {\n ...\n}\n\\end{verbatim}\n\n The\n \\href{https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/stereotype/Controller.html}{\\texttt{@Controller}}\n annotation applies the Spring Controller component stereotype. The\n Spring Framework scans Controller classes for Controller annotations.\n\n The\n \\href{https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/RequestMapping.html}{\\texttt{@RequestMapping(\"VIEW\")}}\n annotation marks the class's public methods as request handler methods\n for the portlet's\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{VIEW mode}.\n\\item\n In your Controller, apply \\texttt{@RenderMapping} annotations to\n methods for handling portlet render requests. Import the annotation\n \\texttt{com.liferay.portletmvc4spring.bind.annotation.RenderMapping}\n and make sure each handler method returns a string that matches the\n name of a template to render. Here are the sample's render request\n handler methods:\n\n\\begin{verbatim}\n@RenderMapping\npublic String prepareView() {\n return \"user\";\n}\n\n@RenderMapping(params = \"javax.portlet.action=success\")\npublic String showGreeting(ModelMap modelMap) {\n\n DateFormat dateFormat = new SimpleDateFormat(\"EEEE, MMMM d, yyyy G\");\n\n Calendar todayCalendar = Calendar.getInstance();\n\n modelMap.put(\"todaysDate\", dateFormat.format(todayCalendar.getTime()));\n\n return \"greeting\";\n}\n\\end{verbatim}\n\n The \\texttt{@RenderMapping} annotation causes the \\texttt{prepareView}\n method above to be invoked if no other handler methods match the\n request. \\texttt{prepareView} renders the \\texttt{user} template\n (i.e., \\texttt{user.jspx}).\n\n The \\texttt{@RenderMapping(params\\ =\\ \"javax.portlet.action=success\")}\n annotation causes the \\texttt{showGreeting} method to be invoked if\n the render request has the parameter setting\n \\texttt{javax.portlet.action=success}. \\texttt{showGreeting} renders\n the \\texttt{greeting} template (i.e., \\texttt{greeting.jspx}).\n\\item\n In your Controller, apply \\texttt{@ActionMapping} annotations to your\n portlet action request handling methods. Import the annotation\n \\texttt{com.liferay.portletmvc4spring.bind.annotation.ActionMapping}.\n\n The sample Controller's action handler method below is annotated with\n \\texttt{@ActionMapping}, making it the default action handler if no\n other action handlers match the request. Since this portlet only has\n one action handler, the \\texttt{submitApplicant} method handles all of\n the portlet's action requests.\n\n\\begin{verbatim}\n@ActionMapping\npublic void submitApplicant(@ModelAttribute(\"user\") User user, BindingResult bindingResult, ModelMap modelMap,\n Locale locale, ActionResponse actionResponse, SessionStatus sessionStatus) {\n\n localValidatorFactoryBean.validate(user, bindingResult);\n\n if (!bindingResult.hasErrors()) {\n\n if (logger.isDebugEnabled()) {\n logger.debug(\"firstName=\" + user.getFirstName());\n logger.debug(\"lastName=\" + user.getLastName());\n }\n\n MutableRenderParameters mutableRenderParameters = actionResponse.getRenderParameters();\n\n mutableRenderParameters.setValue(\"javax.portlet.action\", \"success\");\n\n sessionStatus.setComplete();\n }\n}\n\\end{verbatim}\n\n The\n \\href{https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/bind/annotation/ModelAttribute.html}{\\texttt{@ModelAttribute}}\n annotation in method parameter\n \\texttt{@ModelAttribute(\"user\")\\ User\\ user} associates the View's\n \\texttt{user} Model (comprising a first name and last name) to the\n \\texttt{User} object passed to this method.\n\n Note, the \\texttt{submitApplicant} method sets the\n \\texttt{javax.portlet.action} render parameter to\n \\texttt{success}---the previous render handler method\n \\texttt{showGreeting} matches this request parameter.\n\\item\n Configure any additional resources and beans in the project's\n descriptors and Spring context files respectively. (See\n \\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-configuration-files}{PortletMVC4Spring\n Configuration Files} for details).\n\\item\n Build the project WAR using Gradle or Maven.\n\\item\n Deploy the WAR by copying it to your\n \\texttt{{[}Liferay-Home{]}/deploy} folder.\n\\end{enumerate}\n\nLiferay DXP logs the deployment and the portlet is now available in the\nLiferay DXP UI. Find your portlet by selecting the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}) and navigating to\n\\emph{Widgets} and the category you specified to the Liferay Bundle\nGenerator (\\emph{Sample} is the default category).\n\nCongratulations! You created and deployed a PortletMVC4Spring Portlet.\n\n\\section{Related Topics}\\label{related-topics-9}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-project-anatomy}{PortletMVC4Spring\nProject Anatomy}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-annotations}{PortletMVC4Spring\nAnnotations}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/portletmvc4spring-configuration-files}{PortletMVC4Spring\nConfiguration Files}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/migrating-to-portletmvc4spring}{Migrating\nto PortletMVC4Spring}\n\n\\chapter{Migrating to\nPortletMVC4Spring}\\label{migrating-to-portletmvc4spring}\n\nTo continue developing a portlet to use Spring Framework version 5.0\nonward, migrate it from Spring Portlet MVC to\n\\href{/docs/7-2/appdev/-/knowledge_base/a/portletmvc4spring}{PortletMVC4Spring}.\nHere are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n In your \\texttt{pom.xml} or \\texttt{build.gradle} descriptor, use the\n Spring Framework version 5.1.x artifacts by replacing dependencies on\n the \\texttt{spring-webmvc-portlet} artifact with the\n \\texttt{com.liferay.portletmvc4spring.framework} artifact.\n\n Maven:\n\n\\begin{verbatim}\n\n com.liferay.portletmvc4spring\n com.liferay.portletmvc4spring.framework\n 5.1.0 \n\n\n com.liferay.portletmvc4spring\n com.liferay.portletmvc4spring.security\n 5.1.0 \n\n\\end{verbatim}\n\n Gradle:\n\n\\begin{verbatim}\ncompile group: 'com.liferay.portletmvc4spring', name: 'com.liferay.portletmvc4spring.framework', version: '5.1.0'\ncompile group: 'com.liferay.portletmvc4spring', name: 'com.liferay.portletmvc4spring.security', version: '5.1.0'\n\\end{verbatim}\n\\item\n In your \\texttt{WEB-INF/portlet.xml} descriptor, replace uses of\n \\texttt{org.springframework.web.portlet.DispatcherPortlet} with\n \\href{https://liferay.github.io/portletmvc4spring/apidocs/com/liferay/portletmvc4spring/DispatcherPortlet.html}{\\texttt{com.liferay.portletmvc4spring.DispatcherPortlet}}.\n\\item\n Replace uses of the Spring Portlet MVC\n \\href{https://docs.spring.io/spring-framework/docs/4.3.4.RELEASE/javadoc-api/org/springframework/web/portlet/mvc/annotation/AnnotationMethodHandlerAdapter.html}{\\texttt{AnnotationMethodHandlerAdapter}}\n class with the PortletMVC4Spring\n \\href{https://liferay.github.io/portletmvc4spring/apidocs/com/liferay/portletmvc4spring/mvc/method/annotation/PortletRequestMappingHandlerAdapter.html}{\\texttt{PortletRequestMappingHandlerAdapter}}\n class. \\texttt{PortletRequestMappingHandlerAdapter} uses the\n \\texttt{HandlerMethod} infrastructure that\n \\href{https://docs.spring.io/spring/docs/5.1.x/spring-framework-reference/web.html\\#spring-web}{Spring\n Web MVC 5.1.x} is based on.\n\\item\n If you specified \\texttt{AnnotationMethodHandlerAdapter} as a\n \\texttt{\\textless{}bean\\textgreater{}} in a Spring configuration\n descriptor, replace its fully-qualified class name\n \\texttt{org.springframework.web.portlet.mvc.annotation.AnnotationMethodHandlerAdapter}\n with\n \\texttt{com.liferay.portletmvc4spring.mvc.method.annotation.PortletRequestMappingHandlerAdapter}.\n\n Also address these bean property changes:\n\n \\begin{itemize}\n \\item\n \\href{https://docs.spring.io/spring-framework/docs/4.3.4.RELEASE/javadoc-api/org/springframework/web/portlet/mvc/annotation/AnnotationMethodHandlerAdapter.html\\#setCustomModelAndViewResolver-org.springframework.web.servlet.mvc.annotation.ModelAndViewResolver-}{\\texttt{customModelAndViewResolver}}\n (no longer available)\n \\item\n \\href{https://docs.spring.io/spring-framework/docs/4.3.4.RELEASE/javadoc-api/org/springframework/web/portlet/mvc/annotation/AnnotationMethodHandlerAdapter.html\\#setCustomArgumentResolver-org.springframework.web.bind.support.WebArgumentResolver-}{\\texttt{customArgumentResolver}}\n (no longer available)\n \\item\n \\href{https://liferay.github.io/portletmvc4spring/apidocs/com/liferay/portletmvc4spring/mvc/method/annotation/PortletRequestMappingHandlerAdapter.html\\#setCustomArgumentResolvers-java.util.List-}{\\texttt{customArgumentResolvers}}\n (specify a list of\n \\href{https://docs.spring.io/spring/docs/5.1.4.RELEASE/javadoc-api/org/springframework/web/method/support/HandlerMethodArgumentResolver.html}{\\texttt{HandlerMethodArgumentResolver}}\n instead of a list of\n \\href{https://docs.spring.io/spring-framework/docs/4.3.4.RELEASE/javadoc-api/org/springframework/web/bind/support/WebArgumentResolver.html}{\\texttt{WebArgumentResolver}})\n \\end{itemize}\n\\item\n If you're using\n \\href{https://commons.apache.org/proper/commons-fileupload/}{Apache\n Commons Fileupload}, update your Spring configuration descriptor:\n\n \\begin{enumerate}\n \\def\\labelenumii{\\arabic{enumii}.}\n \\item\n Replace this legacy bean:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\n With this new one from PortletMVC4Spring:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n \\end{enumerate}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Alternatively, you can use the native Portlet 3.0 file upload\n support that PortletMVC4Spring provides by setting the\n `portletMultipartResolver` `` element's `class` to\n `com.liferay.portletmvc4spring.multipart.StandardPortletMultipartResolver`\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n2. Remove these dependencies from your `pom.xml` or `build.gradle` \n descriptor:\n\n ```xml\n \n commons-fileupload\n commons-fileupload\n \n \n commons-io\n commons-io\n \n ```\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{4}\n\\item\n Throughout your project, replace all uses of the\n \\texttt{org.springframework.web.portlet} package path with\n \\texttt{com.liferay.portletmvc4spring}.\n\\item\n Continue\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-portlet-using-portletmvc4spring}{developing\n your portlet using PortletMVC4Spring}.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{Build\n and deploy your project}.\n\\end{enumerate}\n\nCongratulations! You migrated your project from Spring Portlet MVC to\nPortletMVC4Spring.\n\n\\section{Related Topics}\\label{related-topics-10}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/portletmvc4spring}{PortletMVC4Spring}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-portlet-using-portletmvc4spring}{Developing\na Portlet Using PortletMVC4Spring}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/configuring-dependencies}{Configuring\nDependencies}\n\n\\chapter{JSF Portlet}\\label{jsf-portlet}\n\nDo you want to develop MVC-based portlets using the Java EE standard? Do\nyou want to use a portlet development framework with a UI component\nmodel that makes it easy to develop sophisticated, rich UIs? Or have you\nbeen writing web apps using JSF that you'd like to use in Liferay DXP?\nIf you answered \\emph{yes} to any of these questions, you're in luck!\nYou can use the JSF portlet technology in Liferay DXP by leveraging the\nLiferay Faces project, which provides all these capabilities and more.\n\nLiferay Faces is an umbrella project that provides support for the\nJavaServer™ Faces (JSF) standard in Liferay DXP. It encompasses the\nfollowing projects:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/understanding-liferay-faces-bridge}{Liferay\n Faces Bridge} lets you deploy JSF web apps as portlets without writing\n portlet-specific Java code. It also contains innovative features that\n make it possible to leverage the power of JSF 2.x inside a portlet\n application. Liferay Faces Bridge implements the JSR 329/378 Portlet\n Bridge Standard.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/understanding-liferay-faces-alloy}{Liferay\n Faces Alloy} lets you use AlloyUI components in a way that is\n consistent with JSF development.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/understanding-liferay-faces-portal}{Liferay\n Faces Portal} lets you leverage Liferay-specific utilities and UI\n components in JSF portlets.\n\\end{itemize}\n\nFor a comprehensive demo for the JSF component suite, visit the\n\\href{https://faces.liferay.dev}{Liferay Faces Developer site}.\n\nIf you're new to JSF, you may want to know its strengths, its\nweaknesses, and how it stacks up to developing portlets with\nCSS/JavaScript.\n\nHere are some good reasons to use JSF and Liferay Faces:\n\n\\begin{itemize}\n\\tightlist\n\\item\n JSF is the Java EE standard for developing web applications that use\n the Model/View/Controller (MVC) design pattern. As a standard, the\n specification is actively maintained by the Java Community Process\n (JCP), and the Oracle reference implementation (Mojarra) has frequent\n releases. Software Architects often choose standards like JSF because\n they are supported by Java EE application server vendors and have a\n guaranteed service life according to Service Level Agreements (SLAs).\n\\item\n JSF was first introduced in 2003 and is a mature technology for\n developing web applications that are (arguably) easy to maintain.\n\\item\n JSF Portlet Bridges (like Liferay Faces Bridge) are also standardized\n by the JCP and make it possible to deploy JSF web applications as\n portlets without writing portlet-specific Java code.\n\\item\n Support for JSF (via Liferay Faces) is included with Liferay DXP\n support.\n\\item\n JSF is a unique framework in that it provides a UI component model\n that makes it easy to develop sophisticated, rich user interfaces.\n\\item\n JSF has built-in Ajax functionality that provides automatic updates to\n the browser by replacing elements in the DOM.\n\\item\n JSF is designed with many extension points that make a variety of\n integrations possible.\n\\item\n There are several JSF component suites available including Liferay\n Faces Alloy, Primefaces, ICEfaces, and RichFaces. Each of these\n component suites fortify JSF with a variety of UI components and\n complimentary technologies.\n\\item\n JSF is a good choice for server-side developers that need to build web\n user interfaces. This enables server-side developers to focus on their\n core competencies rather than being experts in HTML/CSS/JavaScript.\n\\item\n JSF provides the Facelets templating engine which makes it possible to\n create reusable UI components that are encapsulated as markup.\n\\item\n JSF provides good integration with HTML5 markup\n\\item\n JSF provides the Faces Flows feature which makes it easy for\n developers to create wizard-like applications that flow from\n view-to-view.\n\\item\n JSF has good integration with dependency injection frameworks such as\n CDI and Spring that make it easy for developers to create beans that\n are placed within a scope managed by a container:\n \\texttt{@RequestScoped}, \\texttt{@ViewScoped},\n \\texttt{@SessionScoped}, \\texttt{@FlowScoped}\n\\item\n Since JSF is a stateful technology, the framework encapsulates the\n complexities of managing application state so the developer doesn't\n have to write state management code. It is also possible to use JSF in\n a stateless manner, but some of the features of application state\n management become effectively disabled.\n\\end{itemize}\n\nThere are some reasons not to use JSF. For example, if you are a\nfront-end developer who makes heavy use of HTML/CSS/JavaScript, you\nmight find that JSF UI components render HTML in a manner that gives you\nless control over the overall HTML document. Sticking with a JavaScript\nframework may be better for you. Or, perhaps standards aren't a major\nconsideration for you or you may simply prefer developing portlets using\nyour current framework.\n\nWhether you develop your next portlet application with JSF and Liferay\nFaces or with HTML/CSS/JavaScript is entirely up to you. But you\nprobably want to learn more about Liferay Faces and try it out for\nyourself.\n\n\\chapter{Developing a JSF Portlet\nApplication}\\label{developing-a-jsf-portlet-application}\n\nTo run an existing JSF web app on Liferay DXP, you must leverage the\nLiferay Faces project. The\n\\href{/docs/7-2/reference/-/knowledge_base/r/understanding-liferay-faces-bridge}{Liferay\nFaces Bridge} enables you to deploy JSF web apps as portlets without\nwriting portlet-specific code. You must also provide portlet-specific\ndescriptor files to make it compatible with the Liferay DXP platform.\nThe easiest way to do this is by generating a new Liferay JSF Portlet\nproject and migrating your code to it. Then you can deploy your new JSF\nportlet project to Liferay DXP.\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a new JSF portlet project. The following Maven archetypes are\n available:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com.liferay.faces.archetype.alloy.portlet} (Liferay Faces\n Alloy portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.bootsfaces.portlet} (Liferay\n BootsFaces portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.butterfaces.portlet} (Liferay\n ButterFaces portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.icefaces.portlet} (Liferay\n ICEFaces portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.jsf.portlet} (Liferay JSF\n portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.primefaces.portlet} (Liferay\n PrimeFaces portlet)\n \\item\n \\texttt{com.liferay.faces.archetype.richfaces.portlet} (Liferay\n RichFaces portlet)\n \\end{itemize}\n\n Choose the archetype that matches your web app's JSF component suite.\n For example,\n\n\\begin{verbatim}\nmvn archetype:generate \\\n -DarchetypeGroupId=com.liferay.faces.archetype \\\n -DarchetypeArtifactId=com.liferay.faces.archetype.jsf.portlet \\\n -DarchetypeVersion=5.0.6 \\\n -DgroupId=com.mycompany \\\n -DartifactId=com.mycompany.my.jsf.portlet\n\\end{verbatim}\n\n The above archetypes support both Gradle and Maven development by\n providing a \\texttt{build.gradle} and \\texttt{pom.xml}, respectively.\n For more information, visit\n \\href{https://faces.liferay.dev}{faces.liferay.dev}.\n\n Here's the resulting project structure for a JSF Standard portlet:\n\n \\begin{itemize}\n \\tightlist\n \\item\n {[}liferay-jsf-portlet{]}/ → Arbitrary project name\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java/{[}my-package-path{]}/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{bean/} → Sub-package for managed Java beans\n (optional)\n \\item\n \\texttt{dto/} → Sub-package for model (data transfer object)\n classes (optional)\n \\end{itemize}\n \\item\n \\texttt{resources/} → Resources to include in the class path\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{i18n.properties} → Internationalization\n configuration\n \\item\n \\texttt{log4j.properties} → Log4J logging configuration\n \\end{itemize}\n \\item\n \\texttt{webapp/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{resources/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{images/} → Images\n \\end{itemize}\n \\item\n \\texttt{WEB-INF/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{resources/} Frontend files (e.g., CSS, JS, XHTML,\n etc.) that shouldn't be accessed directly by the browser\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{css/} → Stylesheets\n \\end{itemize}\n \\item\n \\texttt{views/} → View templates\n \\item\n \\texttt{faces-config.xml} → JSF application configuration\n file\n \\item\n \\texttt{liferay-display.xml} → Portlet display\n configuration\n \\item\n \\texttt{liferay-plugin-package.properties} → Packaging\n descriptor\n \\item\n \\texttt{liferay-portlet.xml} → Liferay-specific portlet\n configuration\n \\item\n \\texttt{portlet.xml} → Portlet configuration\n \\item\n \\texttt{web.xml} → Web application configuration\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{test/java/} → Test source files\n \\end{itemize}\n \\end{itemize}\n\\item\n Update your dependencies as desired. The generated portlet already\n includes the required artifacts required to deploy a simple JSF\n portlet to Liferay DXP. For example, the\n \\href{/docs/7-2/reference/-/knowledge_base/r/understanding-liferay-faces-bridge}{Liferay\n Faces Bridge} artifacts look like this:\n\n \\textbf{Maven:}\n\n\\begin{verbatim}\n\n \n com.liferay.faces\n com.liferay.faces.bridge.ext\n 5.0.4\n runtime\n \n \n com.liferay.faces\n com.liferay.faces.bridge.impl\n 4.1.3\n runtime\n \n\n\\end{verbatim}\n\n \\textbf{Gradle:}\n\n\\begin{verbatim}\ndependencies {\n runtime group: 'com.liferay.faces', name: 'com.liferay.faces.bridge.ext', version: '5.0.4'\n runtime group: 'com.liferay.faces', name: 'com.liferay.faces.bridge.impl', version: '4.1.3'\n}\n\\end{verbatim}\n\\item\n Copy your Java classes to the new \\texttt{java/{[}my-package-path{]}/}\n folder.\n\\item\n Copy your view templates to the new\n \\texttt{src/main/webapp/WEBINF/views} folder.\n\\item\n Add your frontend files (e.g., CSS, JS, etc.) that shouldn't be\n accessed directly by the browser to the\n \\texttt{webapp/WEB-INF/resources/} folder. For example, your web app's\n CSS files would reside in the \\texttt{webapp/WEB-INF/resources/css}\n folder.\n\\item\n Add your image files to the \\texttt{webapp/resources/images} folder.\n\\item\n Add localized messages to the \\texttt{resources/i18n.properties} file.\n The messages in the \\texttt{i18n.properties} file can be accessed via\n the Expression Language using the implicit \\texttt{i18n} object\n provided by Liferay Faces Util. The \\texttt{i18n} object can access\n messages both from a resource bundle defined in the portlet's\n \\texttt{portlet.xml} file, and from Liferay DXP's\n \\texttt{Language.properties} file.\n\\item\n Configure your portlet's logging configuration as desired. The\n \\texttt{log4j.properties} file in the \\texttt{src/main/resources}\n folder sets properties for the Log4j logging utility defined in your\n JSF portlet (i.e., \\texttt{faces-config.xml}).\n\\item\n Replace your new JSF portlet's\n \\texttt{webapp/WEB-INF/faces-config.xml} with your web app's\n \\texttt{faces-config.xml} file. The \\texttt{faces-config.xml} file is\n a JSF portlet's application configuration file, which is used to\n register and configure objects and navigation rules.\n\\item\n Replace your new JSF portlet's \\texttt{webapp/WEB-INF/web.xml} with\n your web app's \\texttt{web.xml} file. The \\texttt{web.xml} file serves\n as a deployment descriptor that provides necessary configurations for\n your JSF portlet to deploy and function in Liferay DXP.\n\n Make sure the Faces Servlet is configured in your \\texttt{web.xml}:\n\n\\begin{verbatim}\n\n Faces Servlet\n javax.faces.webapp.FacesServlet\n 1\n\n\\end{verbatim}\n\n This is required to initialize JSF and should be defined in all JSF\n portlets deployed to Liferay DXP.\n\\item\n Modify your \\texttt{webapp/WEB-INF/portlet.xml} as desired. The\n \\texttt{portlet.xml} descriptor describes the portlet to the portlet\n container. For example, it describes portlet info, security settings,\n etc. Also, the \\texttt{javax.portlet.faces.GenericFacesPortlet} is\n defined here, which handles invocations to your JSF portlet and makes\n your portlet, since it relies on Liferay Faces Bridge, easy to develop\n by acting as a turnkey implementation.\n\n The \\texttt{init-param} is also defined here, which ensures your\n portlet is visible when deployed to Liferay DXP by pointing to your\n default view template:\n\n\\begin{verbatim}\n\n javax.portlet.faces.defaultViewId.view\n /WEB-INF/views/view.xhtml\n\n\\end{verbatim}\n\\item\n Modify your \\texttt{webapp/WEB-INF/liferay-portlet.xml} as desired. It\n specifies additional information Liferay DXP uses to enhance your\n portlet: supported security roles, portlet icon, CSS and JavaScript\n locations, and more. The\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/definitions/liferay-portlet-app_7_2_0.dtd.html}{liferay-portlet-app\n DTD} defines the \\texttt{liferay-portlet.xml} elements.\n\\item\n Modify your \\texttt{webapp/WEB-INF/liferay-display.xml} as desired. It\n configures characteristics for displaying your portlet. For example,\n this \\texttt{liferay-display.xml} snippet specifies the Widget\n category in the Add Widget menu:\n\n\\begin{verbatim}\n\n\n\n\n\n \n\n\n\\end{verbatim}\n\\item\n Modify your \\texttt{webapp/WEB-INF/liferay-plugin-package.properties}\n as desired. It describes the portlet application's packaging and\n version information and specifies any required OSGi metadata. For\n example, this \\texttt{liferay-plugin-package.properties} snippet tells\n the OSGi container not to scan for CDI annotations in Liferay DXP.\n\n\\begin{verbatim}\n-cdiannotations:\n\\end{verbatim}\n\n This is required for JSF portlets leveraging CDI deployed to Liferay\n DXP. They must reference their own included CDI implementation.\n\n On deploying the WAR file, the\n \\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{WAB\n Generator} adds the specified OSGi metadata to the resulting web\n application bundle (WAB) that's deployed to Liferay DXP's runtime\n framework.\n\n The\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/liferay-plugin-package_7_2_0.properties.html}{liferay-plugin-package\n reference document} describes the\n \\texttt{liferay-plugin-package.properties} file.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{Build\n and deploy your project}.\n\\end{enumerate}\n\nLiferay DXP logs the deployment.\n\n\\begin{verbatim}\n2019-05-30 14:10:59.405 INFO [com.liferay.portal.kernel.deploy.auto.AutoDeployScanner][AutoDeployDir:261] Processing guestbook-jsf-portlet.war\n...\n2019-05-30 14:11:11.401 INFO [fileinstall-C:/liferay-ce-portal-7.2.0-ga1/osgi/war][BaseDeployer:877] Deploying guestbook-jsf-portlet.war\n...\n2019-05-30 14:11:26.379 INFO [fileinstall-C:/liferay-ce-portal-7.2.0-ga1/osgi/war][BundleStartStopLogger:39] STARTED guestbook-jsf-portlet_7.2.0.1 [2155]\n...\n2019-05-30 14:11:67.569 INFO [fileinstall-C:/liferay-ce-portal-7.2.0-ga1/osgi/war][PortletHotDeployListener:288] 1 portlet for guestbook-jsf-portlet is available for use\n\\end{verbatim}\n\nThe portlet is now available in the Liferay DXP UI. Find your portlet by\nselecting the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}) and navigating to\n\\emph{Widgets} and the category you specified (\\emph{Sample} is the\ndefault category).\n\nGreat! You've successfully developed a Liferay JSF portlet and migrated\nyour web app logic to it.\n\n\\chapter{Bean Portlet}\\label{bean-portlet}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Bean Portlet is in development and is not yet\navailable.\n\n\\noindent\\hrulefill\n\nPortlet 3.0, the \\href{https://jcp.org/en/jsr/detail?id=362}{JSR 362}\nstandard, features a new style of portlet development called Bean\nPortlets that use Contexts and Dependency Injection (CDI). Bean Portlets\nfully leverage\n\\href{https://portals.apache.org/pluto/v301/v3Features.html}{all the new\nPortlet 3.0 features} in compliant portals, and are fully supported in\nLiferay DXP.\n\nBean Portlets are plain old Java objects (POJOs): they don't need to\nextend anything. Portlet descriptors declare them to be portlets.\n\nConfiguration annotations, phase method annotations, and CDI are some of\nthe features you'll use in Portlet 3.0.\n\n\\section{Portlet Configuration\nAnnotations}\\label{portlet-configuration-annotations}\n\nThe\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/PortletConfiguration.html}{\\texttt{@PortletConfiguration}}\nannotation describes your portlet to the portlet container. You can use\nthe annotation instead of or in addition to the traditional\n\\texttt{portlet.xml} descriptor file. The \\texttt{@PortletConfiguration}\nannotation describes your portlet in the portlet code instead of a\nseparate file.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} You can configure Bean Portlets using configuration\nannotations, descriptors, or both. If using annotations and descriptors,\nthe descriptors take precedence.\n\n\\noindent\\hrulefill\n\nThis example portlet was generated using the\n\\texttt{com.liferay.project.templates.cdi.bean.portlet} archetype, and\nit uses \\texttt{@PortletConfiguration} and\n\\texttt{@LiferayPortletConfiguration} annotations:\n\n\\begin{verbatim}\nimport com.mycompany.constants.FooPortletKeys;\n\nimport com.liferay.bean.portlet.LiferayPortletConfiguration;\n\nimport javax.portlet.annotations.LocaleString;\nimport javax.portlet.annotations.PortletConfiguration;\n\n@PortletConfiguration(\n portletName = FooPortletKeys.Foo,\n title = @LocaleString(value = FooPortletKeys.Foo))\n@LiferayPortletConfiguration(\n portletName = FooPortletKeys.Foo,\n properties = {\n \"com.liferay.portlet.display-category=category.sample\",\n \"com.liferay.portlet.instanceable=true\"\n }\n)\npublic class FooPortlet {\n ...\n}\n\\end{verbatim}\n\n\\texttt{@PortletConfiguration}'s \\texttt{portletName} attribute names\nthe portlet. It's the only required attribute. The \\texttt{title}\nattribute typically uses a nicer looking name (e.g., uses spaces and\ncapitalization). The \\texttt{title} above is assigned the key constant\n\\texttt{FooPortletKeys.Foo}. You can also localize a title to one or\nmore languages using an array of\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/LocaleString.html}{\\texttt{@LocaleString}}\nannotations, each specifying a different value for the \\texttt{locale}\nelement.\n\nThe \\texttt{@LiferayPortletConfiguration} annotation specifies\nadditional Liferay-specific configuration properties. For example, the\n\\texttt{com.liferay.portlet.display-category} property lets you assign\nthe Widget category where users will find your portlet. Setting the\n\\texttt{com.liferay.portlet.instanceable=true} enables adding multiple\ninstances of the portlet to a page.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The \\texttt{@PortletConfiguration} and\n\\texttt{@LiferayPortletConfiguration} annotations are respectively\nsynonymous with the \\texttt{javax.portlet.*} and\n\\texttt{com.liferay.portlet.*} properties in the OSGi\n\\texttt{@Component} annotation (used in\n\\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{Liferay\nMVC Portlets}, for example). If you're familiar with the\n\\texttt{portlet.xml} and \\texttt{liferay-portlet.xml} descriptors, the\n\\href{/docs/7-2/reference/-/knowledge_base/r/portlet-descriptor-to-osgi-service-property-map}{Portlet\nDescriptor to OSGi Service Property Map} shows you the OSGi\n\\texttt{@Component} property equivalent. There's an\n\\texttt{@PortletConfiguration} or \\texttt{@LiferayPortletConfiguration}\nequivalent setting for each \\texttt{@Component} property.\n\n\\noindent\\hrulefill\n\nTo opt-in to Portlet 3.0 features, add the following\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/PortletApplication.html}{\\texttt{@PortletApplication}}\nannotation to the class.\n\n\\begin{verbatim}\n@PortletApplication(version=\"3.0\")\n\\end{verbatim}\n\nOnce you've configured your portlet, you should declare the objects it\nuses (depends on).\n\n\\section{Dependency Injection}\\label{dependency-injection}\n\nBean Portlets use the \\texttt{@Inject} CDI annotation (by default) to\ninject dependencies. Apply the annotation to a field you want injected\nwith an object of the specified type. This example portlet injects the\nportlet's \\texttt{PortletConfig} object.\n\n\\begin{verbatim}\nimport javax.inject.Inject;\n\nimport javax.portlet.PortletConfig;\n\npublic class FooPortlet {\n\n @Inject\n PortletConfig portletConfig;\n\n // Invoke methods on portletConfig ...\n\n}\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:}\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/osgi-cdi-integration}{OSGi\nIntegration} allows you to use OSGi services (e.g., Liferay's\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/service/UserLocalService.html}{\\texttt{UserLocalService}})\nin your Bean Portlets.\n\n\\noindent\\hrulefill\n\nPortlet 3.0 defines annotations for declaring methods that handle\nportlet phases.\n\n\\section{Portlet Phase Methods}\\label{portlet-phase-methods}\n\nPhase method annotations apply methods for handling a portlet's phases.\nYou can add them to methods in any class anywhere in the portlet WAR.\nThere's no mandatory method naming convention: assign a phase annotation\nto the methods you want to invoke to process the phase. Here are the\nannotations:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.6154}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.3846}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nPhase\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nAnnotation\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\nHeader (new) &\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/HeaderMethod.html}{\\texttt{@HeaderMethod}} \\\\\nRender &\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/RenderMethod.html}{\\texttt{@RenderMethod}} \\\\\nAction &\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/ActionMethod.html}{\\texttt{@ActionMethod}} \\\\\nEvent &\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/EventMethod.html}{\\texttt{@EventMethod}} \\\\\nResource-serving &\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/annotations/ServeResourceMethod.html}{\\texttt{@ServeResourceMethod}} \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\nYou can specify resource dependencies, such as CSS, in the Header phase\nprior to the Render phase. It helps you avoid loading the same resources\nmultiple times.\n\nYou'll definitely want to define a Render method. For example, here's a\nmethod invoked during the Render phase:\n\n\\begin{verbatim}\nimport javax.portlet.annotations.RenderMethod;\n\n@RenderMethod(\n include = \"/WEB-INF/jsp/view.jsp\",\n portletNames = {FooPortletKeys.Foo})\npublic String doView() {\n return \"Hello from \" + portletConfig.getPortletName();\n}\n\\end{verbatim}\n\nThe \\texttt{@RenderMethod} annotation sets the method to be invoked\nduring the Render phase of the WAR's portlets matching any of the names\nlisted for the \\texttt{portletNames} attribute.\n\nThe example Render method produces this content:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n A string greeting\n \\texttt{\"Hello\\ from\\ \"\\ +\\ portletConfig.getPortletName()}\n\\item\n The JSP template \\texttt{/WEB-INF/jsp/view.jsp}---the\n \\texttt{@RenderMethod} annotation's \\texttt{include} attribute\n references it.\n\\end{enumerate}\n\nThese are just a few of the Portlet 3.0 features that facilitate\ndeveloping applications. This section covers more Portlet 3.0 features\nand Bean Portlet demonstrations. Creating and deploying your own Bean\nPortlet is next.\n\n\\chapter{Creating a Bean Portlet}\\label{creating-a-bean-portlet}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Bean Portlet is in development and is not yet\navailable.\n\n\\noindent\\hrulefill\n\nYour first step in developing a Bean Portlet is to create one. Here\nyou'll generate a Bean Portlet project and deploy your Bean Portlet to\nLiferay DXP.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Generate a Bean Portlet project using a Maven command like this:\n\n\\begin{verbatim}\nmvn archetype:generate \\\n-DarchetypeGroupId=com.liferay \\\n-DarchetypeArtifactId=com.liferay.project.templates.cdi.bean.portlet \\\n-DarchetypeVersion=1.0.0 \\\n-DgroupId=com.mycompany \\\n-DartifactId=com.mycompany.demo.bean.portlet\n\\end{verbatim}\n\n Here's the resulting folder structure for a Bean Portlet class named\n \\texttt{Foo}:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com.mycompany.demo.bean.portlet} → Arbitrary project name.\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src/main/java/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com.mycompany.constants.FooPortletKeys} → Declares\n portlet constants.\n \\item\n \\texttt{com.mycompany.portlet.FooPortlet} → Bean Portlet class.\n \\end{itemize}\n \\item\n \\texttt{src/main/webapp/WEB-INF/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{jsp/view.jsp} → Default view template.\n \\item\n \\texttt{beans.xml} → Signals CDI to scan the portlet for\n annotations.\n \\end{itemize}\n \\item\n \\texttt{pom.xml} → Specifies the project's dependencies and\n packaging.\n \\end{itemize}\n \\end{itemize}\n\n Here's the example Bean Portlet class:\n\n\\begin{verbatim}\npackage com.mycompany.portlet;\n\nimport com.mycompany.constants.FooPortletKeys;\n\nimport com.liferay.bean.portlet.LiferayPortletConfiguration;\n\nimport javax.inject.Inject;\n\nimport javax.portlet.PortletConfig;\nimport javax.portlet.annotations.LocaleString;\nimport javax.portlet.annotations.PortletConfiguration;\nimport javax.portlet.annotations.RenderMethod;\n\n@PortletConfiguration(\n portletName = FooPortletKeys.Foo,\n title = @LocaleString(value = FooPortletKeys.Foo))\n@LiferayPortletConfiguration(\n portletName = FooPortletKeys.Foo,\n properties = {\n \"com.liferay.portlet.display-category=category.sample\",\n \"com.liferay.portlet.instanceable=true\"\n }\n)\npublic class FooPortlet {\n\n @Inject\n PortletConfig portletConfig;\n\n @RenderMethod(\n include = \"/WEB-INF/jsp/view.jsp\",\n portletNames = {FooPortletKeys.Foo})\n public String doView() {\n return \"Hello from \" + portletConfig.getPortletName();\n }\n\n}\n\\end{verbatim}\n\\item\n Set any portlet configuration or Liferay portlet configuration values\n using\n \\href{/docs/7-2/reference/-/knowledge_base/r/portlet-descriptor-to-osgi-service-property-map}{\\texttt{@PortletConfiguration}\n and \\texttt{Liferay@PortletConfiguration} attributes}.\n\\item\n Inject any CDI beans using the \\texttt{@Inject} annotation.\n\\item\n Update your render method \\texttt{doView} (it's annotated with\n \\texttt{@RenderMethod}). It displays the template\n \\texttt{WEB-INF/jsp/view.jsp} by default.\n\\item\n Add any other logic you like to your portlet class.\n\\item\n Build your portlet:\n\n\\begin{verbatim}\nmvn clean package\n\\end{verbatim}\n\\item\n Deploy your portlet by copying the portlet WAR to your\n \\texttt{{[}Liferay\\ \\ \\ \\ \\ Home{]}/deploy} folder. The\n \\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{WAB\n Generator} converts the WAR to an OSGi Web Application Bundle (WAB)\n and installs it to Liferay's OSGi container.\n\\end{enumerate}\n\nLiferay DXP logs the deployment.\n\n\\begin{verbatim}\nINFO [main][HotDeployImpl:226] Deploying com.mycompany.demo.bean.portlet from queue\nINFO [main][PluginPackageUtil:1001] Reading plugin package for com.mycompany.demo.bean.portlet\n...\nINFO [main][PortletHotDeployListener:181] 1 bean portlets for com.mycompany.demo.bean.portlet are available for use\n\\end{verbatim}\n\nThe Bean Portlet is now available in the Liferay DXP UI. The example\nportlet is in the Widget category you assigned it.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portlet-3-portlet.png}\n\\caption{The Foo portlet prints the message returned from\n\\texttt{doView} method and shows the included JSP's contents.}\n\\end{figure}\n\nCongratulations on creating and deploying a Bean Portlet!\n\n\\section{Related Topics}\\label{related-topics-11}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/osgi-cdi-integration}{OSGi\nCDI Integration}\n\n\\chapter{Service Builder}\\label{service-builder}\n\nAn application without reliable business logic or persistence isn't much\nof an application at all. Unfortunately, writing your own persistence\ncode often takes a great deal of time. Service Builder is an\nobject-relational mapping tool that can generate your model,\npersistence, and service layers from a single \\texttt{xml} file. Once\ngenerated, the code is completely customizable: you can write your own\npersistence code along with custom SQL if necessary. Regardless of how\nyou produce your persistence code, you can then use Service Builder to\nimplement your app's business logic.\n\nThis section demonstrates using Service Builder to\n\n\\begin{itemize}\n\\item\n Generate and customize your persistence framework\n\\item\n Implement your business logic\n\\end{itemize}\n\nWhen you configure your model and its relationships in your\n\\texttt{service.xml} file and run Service Builder, it generates these\nlayers of code:\n\n\\begin{itemize}\n\\item\n \\textbf{Model layer:} defines objects to represent your project's\n entities.\n\\item\n \\textbf{Persistence layer:} saves entities to and retrieves entities\n from the database and updates entities.\n\\item\n \\textbf{Service layer:} a blank layer ready for you to create your API\n and business logic. .\n\\end{itemize}\n\nHere are some key features these layers contain:\n\n\\begin{itemize}\n\\item\n Stubbed-out classes for implementing custom business logic\n\\item\n Hibernate configurations\n\\item\n Configurable caching support\n\\item\n Flexibility and support for adding custom SQL queries and dynamic\n queries\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} You don't have to use Service Builder for your back-end\nservices on @product. It's entirely possible to use your persistence\nframework of choice, such as JPA or Hibernate. Note that ``under the\nhood,'' Service Builder uses Hibernate.\n\n\\noindent\\hrulefill\n\n\\section{Customization via Implementation\nClasses}\\label{customization-via-implementation-classes}\n\nEach entity Service Builder generates contains these\n\\emph{implementation} classes:\n\n\\begin{itemize}\n\\item\n \\textbf{Entity implementation} (\\texttt{*Impl.java}): Is responsible\n for customizing the entity.\n\\item\n \\textbf{Local service implementation}\n (\\texttt{*LocalServiceImpl.java}): Is responsible for calling the\n persistence layer to retrieve and store data entities. Local services\n contain the business logic and access the persistence layer. They can\n be invoked by client code running in the same Java Virtual Machine.\n\\item\n \\textbf{Remote service implementation} (\\texttt{*ServiceImpl.java}):\n Generated if the \\texttt{service.xml} is configured for remote\n services. Remote services usually contain permission checking code and\n are meant to be accessible from outside the JVM. Service Builder\n automatically generates code that makes the remote services available\n via JSON or SOAP, and you can also create your own remote APIs through\n \\href{/docs/7-2/appdev/-/knowledge_base/a/rest-builder}{REST Builder}\n or \\href{/docs/7-2/frameworks/-/knowledge_base/f/jax-rs}{JAX-RS}.\n\\end{itemize}\n\nThese classes are where you implement custom business logic. They're the\nonly classes generated by Service Builder intended for customization.\n\n\\section{Hibernate Configurations}\\label{hibernate-configurations}\n\nService Builder uses the Hibernate persistence framework for\nobject-relational mapping. Service Builder hides the complexities of\nHibernate, while still giving you access to technology like dynamic\nqueries and custom SQL. You can take advantage of Object-Relational\nMapping (ORM) in your projects without having to manually set up a\nHibernate environment or make any configurations.\n\n\\section{Caching}\\label{caching}\n\nService Builder caches objects at three levels: \\emph{entity},\n\\emph{finder}, and \\emph{Hibernate}. By default, Liferay uses Ehcache as\nan underlying cache provider for each of these cache levels. However,\nthis is configurable via\n\\href{/docs/7-2/deploy/-/knowledge_base/d/portal-properties}{portal\nproperties}. All you must do to enable entity and finder caching in your\nproject is to set the \\texttt{cache-enabled=true} attribute of your\nentity's \\texttt{\\textless{}entity\\textgreater{}} element in your\n\\texttt{service.xml} file.\n\\href{/docs/7-2/deploy/-/knowledge_base/d/enabling-cluster-link}{Liferay\nClustering} describes Liferay caching in a cluster.\n\n\\section{Dynamic Query and Custom SQL\nQuery}\\label{dynamic-query-and-custom-sql-query}\n\nService Builder automates many of the common tasks associated with\ncreating database persistence code but it doesn't prevent you from\ncreating \\href{/docs/7-2/appdev/-/knowledge_base/a/custom-sql}{custom\nSQL queries}. You can define custom SQL queries in an XML file and\nimplement finder methods to run the queries. If you have some crazy join\nto do, Service Builder gets out of your way. You can also use\n\\href{/docs/7-2/appdev/-/knowledge_base/a/dynamic-query}{dynamic query}\nto access Hibernate's criteria API.\n\nService Builder is used exclusively throughout Liferay DXP and its\napplications, so it's well-tested and robust. It saves lots of\ndevelopment time, both initial development time and time that would have\nto be spent maintaining, extending, or customizing a project. Now\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-a-service-builder-project}{create\nyour own Service Builder project}.\n\n\\chapter{Creating a Service Builder\nProject}\\label{creating-a-service-builder-project}\n\nTo use\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}, you must generate the projects where you'll configure your\nobject-relational map. There's an API project and an implementation\nproject.\n\n\\begin{itemize}\n\\item\n \\texttt{{[}project{]}/{[}project{]}-api/} → Service interfaces.\n\\item\n \\texttt{{[}project{]}/{[}project{]}-service/} → Service\n implementations and supporting files.\n\\end{itemize}\n\nHere's how to create a Service Builder project.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Decide on a project name. If the project is part of an application,\n name the project after the application.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Create\n a project} using\n \\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI} and\n the\n \\href{/docs/7-2/reference/-/knowledge_base/r/using-the-service-builder-template}{\\texttt{service-builder}\n project template}, passing your project name as a parameter. For\n example, here are Gradle and Maven commands for creating a Service\n Builder project called \\texttt{guestbook}.\n\n Gradle:\n\n\\begin{verbatim}\nblade create -t service-builder -p com.liferay.docs.guestbook guestbook\n\\end{verbatim}\n\n Maven:\n\n\\begin{verbatim}\nmvn archetype:generate \\\n-DarchetypeGroupId=com.liferay \\\n-DarchetypeArtifactId=com.liferay.project.templates.service.builder \\\n-DgroupId=com.liferay \\\n-DartifactId=guestbook \\\n-Dpackage=com.liferay.docs.guestbook \\\n-Dversion=1.0 \\\n-DapiPath=com.liferay.api.path \\\n-DliferayVersion=7.2\n\\end{verbatim}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} To use the Spring dependency injector instead of the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{Declarative\nServices} dependency injector, use the\n\\texttt{-\\/-dependency-injector\\ spring} option (Blade CLI) or\n\\texttt{-DdependencyInjector=spring} (Maven).\n\n\\noindent\\hrulefill\n\nA message like this one reports project creation success:\n\n\\begin{verbatim}\nSuccessfully created project bookmarks in C:\\workspaces_liferay\\72-ws\\modules\n\\end{verbatim}\n\nBlade CLI generates the parent project folder and sub-folders for the\n\\texttt{*-api} and \\texttt{*-service} module projects.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{guestbook/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{guestbook-api/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{bnd.bnd}\n \\item\n \\texttt{build.gradle}\n \\end{itemize}\n \\item\n \\texttt{guestbook-service/}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{bnd.bnd}\n \\item\n \\texttt{build.gradle}\n \\item\n \\texttt{service.xml} → Service definition file.\n \\end{itemize}\n \\item\n \\texttt{build.gradle}\n \\end{itemize}\n\\end{itemize}\n\nCongratulations! You've created your Service Builder project. The\n\\texttt{service.xml} file is where you'll define your model objects\n(entities) and services.\n\n\\section{Related Topics}\\label{related-topics-12}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Service Builder\nSamples}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-gradle-plugin}{Service\nBuilder Gradle Plugin}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-plugin}{Service\nBuilder Maven Plugin}\n\n\\chapter{Creating the service.xml\nFile}\\label{creating-the-service.xml-file}\n\nTo define a service for your portlet project, you must create a\n\\texttt{service.xml} file. The DTD (Document Type Declaration) file\n\\href{https://docs.liferay.com/ce/portal/7.2-latest/definitions/liferay-service-builder_7_2_0.dtd.html}{liferay-service-builder\\_7\\_2\\_0.dtd}\nspecifies the format and requirements of the XML to use.\n\nA \\texttt{service.xml} was created for you when you\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-a-service-builder-project}{created\nyour Service Builder project}. It's in your \\texttt{*-service} module's\nroot folder with an \\texttt{entity} element named \\emph{Foo}. This is\n(obviously) an example entity, but you can use it as a pattern for\ncreating your own.\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP} provides a Diagram mode and a Source mode to give you\ndifferent perspectives of the service information in your\n\\texttt{service.xml} file.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Diagram mode} facilitates creating and visualizing\n relationships between service entities.\n\\item\n \\textbf{Source mode} brings up the \\texttt{service.xml} file's raw XML\n content in the editor.\n\\end{itemize}\n\nIf you use Liferay Dev Studio DXP, you can switch between these modes.\nOf course, you don't have to use Liferay Dev Studio DXP to work on\nLiferay projects.\n\nNext, you'll specify your service's global information.\n\n\\chapter{Defining Global Service\nInformation}\\label{defining-global-service-information}\n\nA service's global information applies to all its entities. It contains\nthe\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[dependency-injector]{Dependency Injector}\n\\item\n \\hyperref[package-path]{Package path}\n\\item\n \\hyperref[namespace-options]{Namespace options}\n\\item\n \\hyperref[multiversion-concurrency-control-mvcc]{Multiversion\n concurrency control}\n\\item\n \\hyperref[author]{Author}\n\\end{itemize}\n\n\\section{Dependency Injector}\\label{dependency-injector}\n\nThe default dependency injector is\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\nDeclarative Services}. This makes Service Builder work consistently the\nway other modules do. Prior versions of Liferay used Spring. The only\ndifference is how you inject the services when you\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{go to\nuse them later}.\n\nDeclarative Services Dependency Injector:\n\n\\begin{verbatim}\n\n\n\n\n\\end{verbatim}\n\nSpring Dependency Injector:\n\n\\begin{verbatim}\n\n\n\n\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} When a project is created using the\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-the-service-builder-template}{Service\nBuilder template}, the Declarative Services dependency injector and its\ndependencies are configured for the project by default. To use the\nSpring dependency injector instead, create the project using the Service\nBuilder template and the \\texttt{-\\/-dependency-injector\\ spring} option\n(Blade CLI) or \\texttt{-DdependencyInjector=spring} (Maven).\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Prior to Liferay DXP 7.2, Spring was the sole dependency\ninjector. The services were Spring beans. Liferay's Spring bean\nframework accommodates Spring beans referencing each other: for example,\nSpring bean A has a Spring bean B field and vice versa. When Spring is\nthe dependency injector, the base services Service Builder generates\ninclude local service and persistence fields of all the\n\\texttt{service.xml}'s entities. This causes circular references. Since\nOSGi Declarative Services doesn't accommodate circular references,\nService Builder does not create these fields in the base classes when DS\nis the dependency injector. For more details, see\n\\href{understanding-the-code-generated-by-service-builder}{Understanding\nthe Code}.\n\n\\noindent\\hrulefill\n\n\\section{Package Path}\\label{package-path}\n\nThe package path specifies the package where the service and persistence\nclasses are generated. The package path for Guestbook ensures that the\n\\texttt{*-api} module's service classes are generated in the\n\\texttt{com.liferay.docs.guestbook} package. The persistence classes are\ngenerated in a package of the same name in the \\texttt{*-service}\nmodule. A later article\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{describes\nthe package content}.\n\n\\section{Multiversion concurrency control\n(MVCC)}\\label{multiversion-concurrency-control-mvcc}\n\nThe \\texttt{service-builder} element's \\texttt{mvcc-enabled} attribute\nis \\texttt{false} by default. Setting \\texttt{mvcc-enabled=\"true\"}\n(hint: edit \\texttt{service.xml} in \\emph{Source} view) enables\n\\href{https://en.wikipedia.org/wiki/Multiversion_concurrency_control}{multiversion\nconcurrency control} (MVCC) for all of the service's entities. In\nsystems, concurrent updates are common. Without MVCC people may read or\noverwrite data from an invalid state unknowingly. With MVCC, each\nmodification is made upon a given base version number. When Hibernate\nreceives the update, it generates an \\texttt{update} SQL statement that\nuses a \\texttt{where} clause to make sure the current data version is\nthe version you expect.\n\nIf the current data version\n\n\\begin{itemize}\n\\item\n \\textbf{matches the expected version}, your data operation is based on\n up-to-date data and is accepted.\n\\item\n \\textbf{doesn't match the expected version}, the data you're operating\n on is outdated. Liferay DXP rejects your data operation and throws an\n exception, which you can catch to help the user handle the exception\n (e.g., suggest retrying the operation).\n\\end{itemize}\n\n\\textbf{Important:} Enable MVCC for all your services by setting\n\\texttt{mvcc-enabled=\"true\"} in your\n\\texttt{\\textless{}service-builder/\\textgreater{}} element. When\ninvoking service entity updates (e.g.,\n\\texttt{fooService.update(object)}), make sure to do so in transactions.\nPropagate rejected transactions to the UI for the user to handle.\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\n\\section{Namespace Options}\\label{namespace-options}\n\nService Builder names the database tables using the service namespace.\nFor example, \\emph{GB} could serve as the namespace for a Guestbook\napplication service.\n\n\\begin{verbatim}\nGB\n\\end{verbatim}\n\nService Builder uses the namespace in the following SQL scripts it\ngenerates in your \\texttt{src/main/resources/sql} folder:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{indexes.sql}\n\\item\n \\texttt{sequences.sql}\n\\item\n \\texttt{tables.sql}\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The generated SQL script folder location is configurable.\nFor example, if you're using Gradle, you can define the \\texttt{sqlDir}\nsetting in the project's Gradle \\texttt{build.gradle} file or Maven\n\\texttt{pom.xml} file, the same way the \\texttt{databaseNameMaxLength}\nsetting is applied in the examples below.\n\n\\noindent\\hrulefill\n\nService Builder uses the SQL scripts to create database tables for all\nthe entities the \\texttt{service.xml} defines. The database table names\nhave the namespace prepended when they are created. Since the example\nnamespace value is \\texttt{GB}, the database table names created for the\nentities start with \\texttt{GB\\_\\_} as their prefix. Each Service\nBuilder project's namespace must be unique. Separate plugins should use\nseparate namespaces and should not use a namespace already used by\nLiferay entities (such as \\texttt{Users} or \\texttt{Groups}). Check the\ntable names in Liferay's database to see the namespaces already in use.\n\n\\textbf{Warning:} Use caution when assigning namespace values. Some\ndatabases have strong restrictions on database table and column name\nlengths. The Service Builder\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-gradle-plugin\\#task-properties}{Gradle}\nand\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-plugin\\#available-parameters}{Maven}\nplugin parameter \\texttt{databaseNameMaxLength} sets the maximum length\nyou can use for your table and column names. Here are paraphrased\nexamples of setting \\texttt{databaseNameMaxLength} in build files:\n\n\\textbf{Gradle \\texttt{build.gradle}}\n\n\\begin{verbatim}\nbuildService {\n ...\n databaseNameMaxLength = 64\n ...\n}\n\\end{verbatim}\n\n\\textbf{Maven \\texttt{pom.xml}}\n\n\\begin{verbatim}\n\n ...\n 64\n ...\n\n\\end{verbatim}\n\n\\section{Author}\\label{author}\n\nAs the last piece of global information, enter your name as the\nservice's \\emph{author} in your \\texttt{service.xml} file. Service\nBuilder adds \\texttt{@author} annotations with the specified name to all\nthe Java classes and interfaces it generates. Save your\n\\texttt{service.xml} file. Next, you'll add entities for your services.\n\n\\begin{verbatim}\nLiferay\n\\end{verbatim}\n\n\\chapter{Defining Service Entities}\\label{defining-service-entities}\n\nEntities are the heart and soul of a service. They represent the map\nbetween the model objects in Java and your database fields and tables.\nService Builder maps your Java model to the entities you define\nautomatically, giving you a facility for taking Java objects and\npersisting them. For the Guestbook application, two entities are created\naccording to its \\texttt{service.xml}: one for Guestbooks and one for\nGuestbook Entries.\n\nHere's a summary of the \\texttt{Guestbook} entity information:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Name:} \\texttt{Guestbook}\n\\item\n \\textbf{Local service:} \\emph{yes}\n\\item\n \\textbf{Remote service:} \\emph{yes}\n\\end{itemize}\n\nAnd here's what is used for the \\texttt{GuestbookEntry} entity:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Name:} \\texttt{GuestbookEntry}\n\\item\n \\textbf{Local service:} \\emph{yes}\n\\item\n \\textbf{Remote service:} \\emph{yes}\n\\end{itemize}\n\nHere's how you define entities:\n\n\\begin{verbatim}\n\n\n\n\n\n\\end{verbatim}\n\nThe entity's database table name includes the entity name prefixed with\nthe namespace. The Guestbook example creates one database table named\n\\texttt{GW\\_Guestbook} and another named \\texttt{GB\\_GuestbookEntry}.\n\nSetting \\emph{Local Service} (the \\texttt{local-service} attribute) to\n\\texttt{true} instructs Service Builder to generate local interfaces for\nthe entity's services. Local services can only be invoked from the\nLiferay server on which they're deployed.\n\nSetting \\emph{Remote Service} (the \\texttt{remote-service} attribute) to\n\\texttt{true} instructs Service Builder to generate remote interfaces\nfor the service. You can build a fully-functional application without\ngenerating remote services. In that case, you could set your entity\nlocal services to \\texttt{true} and remote services to \\texttt{false}.\nIf, however, you want to enable remote access to your application's\nservices, set both local service and remote service to \\texttt{true}.\n\n\\noindent\\hrulefill\n\n\\textbf{Tip:} Suppose you have an existing Data Access Object (DAO)\nservice for an entity built using some other framework such as JPA. You\ncan set local service to \\texttt{false} and remote service to\n\\texttt{true} so that the methods of your remote \\texttt{-Impl} class\ncan call the methods of your existing DAO. This enables your entity to\nintegrate with Liferay's permission-checking system and provides access\nto the web service APIs generated by Service Builder. This is a very\nhandy, quite powerful, and often used feature of Liferay.\n\n\\noindent\\hrulefill\n\nNow that you've seen how to create your application's entities, you'll\nlearn how to describe their attributes using entity \\emph{columns}.\n\n\\chapter{Defining the Columns (Attributes) for Each Service\nEntity}\\label{defining-the-columns-attributes-for-each-service-entity}\n\nAn entity's columns represent its attributes. These attributes map table\nfields to Java object fields. To add attributes for your entity, add\n\\texttt{\\textless{}column\\ /\\textgreater{}} tags to your entity\ndefinition:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\nService Builder creates a database field for each column you add to the\n\\texttt{service.xml} file. It maps a database field type appropriate to\nthe Java type specified for each column, and it does this across all the\ndatabases Liferay supports. Once Service Builder runs, it generates a\nHibernate configuration that handles the object-relational mapping.\nService Builder automatically generates getter/setter methods in the\nmodel class for these attributes. The column's name specifies the name\nused in the getters and setters that are created for the entity's Java\nfield. The column's type indicates the Java type of this field for the\nentity. If a column's \\texttt{primary} (i.e., primary key) attribute is\nset to \\texttt{true}, the column becomes part of the primary key for the\nentity. If only one column has \\texttt{primary} set to \\texttt{true},\nthat column represents the entire primary key for the entity. This is\nthe case in the Guestbook application. If you define multiple columns\nwith the \\texttt{primary} attribute set to true, the combination of\ncolumns makes up a compound primary key for the entity.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method\\#step-3-generate-a-primary-key}{Implementing\nan Add Method} article demonstrates how to generate unique primary keys\nfor entity instances.\n\n\\noindent\\hrulefill\n\n\\section{Create Entity Columns}\\label{create-entity-columns}\n\nDefine the columns you need for your first entity. The Guestbook entity\nis simple: it has only two attributes; a primary key and a name:\n\n\\begin{verbatim}\n\n\n\\end{verbatim}\n\n\\textbf{Note}: On deploying a \\texttt{*service} module, Service Builder\nautomatically generates indexes for all entity primary keys.\n\nCreate a column for each attribute of your entity or entities, using the\nJava type you'll use in your application. Service Builder handles\nmapping it to SQL for you.\n\n\\section{Support Multi-tenancy}\\label{support-multi-tenancy}\n\nIn addition to columns for your entity's primary key and attributes, add\nportal instance ID and site ID columns. Then you can support Liferay's\nmulti-tenancy features, so that each portal instance and each Site in a\nportal instance can have independent sets of your application's data. To\nhold the site's ID, add a column called \\texttt{groupId} of type\n\\texttt{long}. To hold the portal instance's ID, add a column called\n\\texttt{companyId} of type \\texttt{long}:\n\n\\begin{verbatim}\n\n\n\n\n\\end{verbatim}\n\n\\section{Workflow Fields}\\label{workflow-fields}\n\nYou can support Liferay's\n\\href{/docs/7-2/user/-/knowledge_base/u/workflow}{workflow system} by\nadding the fields it needs to track an entity's progress:\n\n\\begin{verbatim}\n\n\n\n\n\n\n\\end{verbatim}\n\n\\section{Audit Entities}\\label{audit-entities}\n\nFinally, you can add columns to help audit your entities. To track each\nentity instance's owner, add a column called \\texttt{userId} of type\n\\texttt{long}. Create a column named \\texttt{createDate} of type\n\\texttt{Date} to note an entity instance's creation date. Add a column\nnamed \\texttt{modifiedDate} of type \\texttt{Date} to track the last time\nan entity instance was modified.\n\n\\begin{verbatim}\n\n\n\n\n\n\n\\end{verbatim}\n\nGreat! Your entities have columns that not only represent their\nattributes, but also support multi-tenancy, workflow, and auditing.\nNext, you'll learn how to specify the relationship service entities.\n\n\\chapter{Defining Relationships Between Service\nEntities}\\label{defining-relationships-between-service-entities}\n\nRelationships between database entities or Java objects are necessary\nfor most applications. The Guestbook application, therefore, defines a\nrelationship between a Guestbook and its entries.\n\nAs mentioned earlier, each entry must belong to a particular Guestbook.\nTherefore, each \\texttt{GuestbookEntry} entity must relate to a\n\\texttt{Guestbook} entity.\n\nCreate the \\texttt{GuestbookEntry} entity's fields:\n\n\\begin{verbatim}\n\n\n \n \n \n \n \n\\end{verbatim}\n\nNote the last field in the list is the \\texttt{guestbookId} field. Since\nit's the same name as the \\texttt{Guestbook} object's primary key, a\nrelationship is created between the two objects. If you're using Liferay\nDev Studio DXP, you can see this relationship in its diagram mode.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/service-builder-relate-entities.png}\n\\caption{Relating entities is a snap in Liferay Dev Studio DXP's\n\\emph{Diagram} mode for \\texttt{service.xml}.}\n\\end{figure}\n\nCongratulations! You've related two entities.\n\nNext, add the instance, audit, and status fields mentioned from the\nprevious step to enable Liferay's multi-tenancy, audit, and workflow\nfeatures.\n\nNow that your entity columns are in place and entity relationships are\nestablished, you can specify the default order in which the entity\ninstances are retrieved from the database.\n\n\\chapter{Defining Ordering of Service Entity\nInstances}\\label{defining-ordering-of-service-entity-instances}\n\nOften, you want to retrieve multiple instances of a given entity and\nlist them in a particular order. The \\texttt{service.xml} file lets you\nspecify the default order of your entities.\n\nSuppose you want to return \\texttt{GuestbookEntry} entities by their\ncreation date. It's easy to specify these default orderings:\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\nYou can enter \\texttt{asc} or \\texttt{desc} for ascending or descending\norder.\n\nNow that you know how to order your service entities, the last thing to\ndo is to define the finder methods for retrieving entity instances from\nthe database.\n\n\\chapter{Defining Service Entity Finder\nMethods}\\label{defining-service-entity-finder-methods}\n\nFinder methods retrieve entity objects from the database based on\nspecified parameters. For each finder defined, Service Builder generates\nseveral methods to fetch, find, remove, and count entity instances based\non the finder's parameters.\n\nWhen supporting Liferay's multi-tenancy, it's important to be able to\nfind its entities per Site.\n\n\\section{Creating Finders}\\label{creating-finders}\n\nFinders are easy to create:\n\n\\begin{verbatim}\n\n \n \n\\end{verbatim}\n\nThe example above is among the simplest of finders, and is one you\nshould always add if you're supporting multi-tenancy. This finder\nreturns a collection of objects that belong to the Site on which your\napplication has been placed. Service Builder generates finder-related\nmethods (e.g., \\texttt{fetchByGroupId}, \\texttt{findByGroupId},\n\\texttt{removeByGroupId}, \\texttt{countByGroupId}) for the your entities\nin the \\texttt{*Persistence} and \\texttt{*PersistenceImpl} classes. The\nfirst of these classes is the interface; the second is its\nimplementation. For example, the Guestbook application generates its\nentity finder methods in the \\texttt{-Persistence} classes found in the\n\\texttt{/guestbook-api/src/main/java/com/liferay/docs/guestbook/service/persistence}\nfolder and the \\texttt{-PersistenceImpl} classes in the\n\\texttt{/guestbook/src/main/java/com/liferay/docs/service/persistence/impl}\nfolder.\n\nYou're not limited to finding by one column, however; you can create\nmulti-column finders:\n\n\\begin{verbatim}\n\n \n \n\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Important}: DO NOT create finders that use entity primary key as\nparameters. They're unnecessary as Service Builder automatically\ngenerates \\texttt{findByPrimaryKey} and \\texttt{fetchByPrimaryKey}\nmethods for all entity primary keys. On deploying a \\texttt{*service}\nmodule, Service Builder creates indexes for all entity primary key\ncolumns and finder columns. Adding finders that use entity primary keys\nresults in attempts to create multiple indexes for the same\ncolumns---Oracle DB, for example, reports these attempts as errors.\n\n\\noindent\\hrulefill\n\nNow you know to configure Service Builder to create finder methods for\nyour entity. Terrific!\n\nNow that you've specified the service for your project, you're ready to\n\\emph{build} the service by running Service Builder. It's time to\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{run\nService Builder and examine the code it generates}.\n\n\\chapter{Running Service Builder}\\label{running-service-builder}\n\nHere you'll learn how to run Service Builder. If want to use Service\nBuilder in your application but haven't yet\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{created\na \\texttt{service.xml} file that defines an object-relational map for\nyou application}, make sure to do so before proceeding.\n\nOpen a command line and navigate to your application folder (the folder\nthat contains your \\texttt{*-api} and \\texttt{*-service} modules).\n\n\\section{Gradle}\\label{gradle}\n\nTo build your services using Gradle, enter the following command:\n\n\\begin{verbatim}\nblade gw buildService\n\\end{verbatim}\n\nor\n\n\\begin{verbatim}\ngradlew buildService\n\\end{verbatim}\n\nBlade's \\texttt{gw} command works in any project that has a Gradle\nWrapper available to it. Projects generated using Liferay project\ntemplates have a Gradle Wrapper.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Liferay Workspace's Gradle Wrapper script is in the\nworkspace root folder. If your application project folder is located at\n\\texttt{{[}workspace{]}/modules/{[}application{]}}, for example, the\nGradle Wrapper is available at \\texttt{../../gradlew}.\n\n\\noindent\\hrulefill\n\n\\section{Maven}\\label{maven}\n\nIf you're using Maven, build the services by running the following\ncommand:\n\n\\begin{verbatim}\nmvn service-builder:build\n\\end{verbatim}\n\n\\textbf{Important:} The \\texttt{mvn\\ service-builder:build} command only\nworks if you're using the\n\\texttt{com.liferay.portal.tools.service.builder} plugin version\n1.0.145+. Maven projects using an earlier version of the Service Builder\nplugin should update their POM accordingly. More information is\navailable on\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-service-builder-in-a-maven-project}{using\nMaven to run Service Builder}.\n\nOn successfully building the services, Service Builder prints the\nmessage \\texttt{BUILD\\ SUCCESSFUL}. Many generated files appear in your\nproject. They represent a model layer, service layer, and persistence\nlayer for your entities. Don't worry about the number of generated\nfiles---they're explained in the next article, where you can review the\ncode Service Builder generates for your entities.\n\n\\chapter{Understanding the Code Generated by Service\nBuilder}\\label{understanding-the-code-generated-by-service-builder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Service\nBuilder generates code} to support your entities. The files listed under\nLocal Service and Remote Service below are only generated for an entity\nthat has both \\texttt{local-service} and \\texttt{remote-service}\nattributes set to \\texttt{true}. Service Builder generates services for\nthese entities in your application's \\texttt{*-api} and\n\\texttt{*-service} modules in the packages you specified in\n\\texttt{service.xml}. For example, here are the package paths for\nLiferay's Bookmarks application:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{/guestbook-api/src/main/java/com/liferay/docs/guestbook}\n\\item\n \\texttt{/guestbook-service/src/main/java/com/liferay/docs/guestbook}\n\\end{itemize}\n\nThe \\texttt{guestbook-api} module's interfaces define the Guestbook\napplication API. The \\texttt{*-api} module interfaces define the\napplication's persistence layer, service layer, and model layer.\nWhenever you compile and deploy the \\texttt{*-api} module, all its\nclasses and interfaces are packaged in a \\texttt{.jar} file called\n\\texttt{PROJECT\\_NAME-api.jar} in the module's \\texttt{build/libs}\nfolder. Deploying this JAR to Liferay \\emph{defines} the API as OSGi\nservices.\n\nThe \\texttt{guestbook-service} module classes implement the\n\\texttt{guestbook-api} module interfaces. The \\texttt{*-service} module\nprovides the OSGi service implementations to deploy to Liferay's OSGi\nframework.\n\nNext, examine the classes and interfaces generated for the entities you\nspecified. Similar classes are generated for each entity, depending on\nhow each entity is specified in the \\texttt{service.xml}. Here are the\nthree types of customizable classes:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{*LocalServiceImpl}\n\\item\n \\texttt{*ServiceImpl}\n\\item\n \\texttt{*Impl}\n\\end{itemize}\n\nThe \\texttt{*} represents the entity name in the classes listed above.\n\nHere are the persistence, service, and model classes:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Persistence\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Persistence}: Persistence interface that\n defines CRUD methods for the entity such as \\texttt{create},\n \\texttt{remove}, \\texttt{countAll}, \\texttt{find}, \\texttt{findAll},\n etc.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}PersistenceImpl}: Persistence\n implementation class that implements\n \\texttt{{[}ENTITY\\_NAME{]}Persistence}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Util}: Persistence utility class that\n wraps \\texttt{{[}ENTITY\\_NAME{]}PersistenceImpl} and provides direct\n access to the database for CRUD operations. This utility should only\n be used by the service layer; in your portlet classes, use the\n \\texttt{{[}ENTITY\\_NAME{]}} class by referencing it with the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{\\texttt{@Reference}\n annotation}.\n \\end{itemize}\n\n \\begin{figure}\n \\centering\n \\includegraphics{./images/service-builder-persistence-diagram.png}\n \\caption{Service Builder generates these persistence classes and\n interfaces for an example entity called \\emph{Event}. You shouldn't\n (and you won't need to) customize any of these classes or interfaces.}\n \\end{figure}\n\\item\n Local Service (generated for an entity only if the entity's\n \\texttt{local-service} attribute is set to \\texttt{true} in\n \\texttt{service.xml})\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}LocalService}: Local service interface.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}LocalServiceImpl} (\\textbf{LOCAL SERVICE\n IMPLEMENTATION}): Local service implementation. This is the only\n class in the local service that you should modify: it's where you\n add your business logic. For any methods added here, Service Builder\n adds corresponding methods to the\n \\texttt{{[}ENTITY\\_NAME{]}LocalService} interface the next time you\n run it.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}LocalServiceBaseImpl}: Local service base\n implementation. This is an abstract class. Service Builder injects a\n number of instances of various service and persistence classes into\n this class. \\texttt{@abstract}\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}LocalServiceUtil}: Local service utility\n class which wraps \\texttt{{[}ENTITY\\_NAME{]}LocalServiceImpl}. This\n class is generated for backwards compatibility purposes only. Use\n the \\texttt{*LocalService} class by referencing it with the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{\\texttt{@Reference}\n annotation}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}LocalServiceWrapper}: Local service\n wrapper which implements \\texttt{{[}ENTITY\\_NAME{]}LocalService}.\n This class is designed to be extended and it lets you\n \\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{customize\n the entity's local services}.\n \\end{itemize}\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/service-builder-service-diagram.png}\n\\caption{Service Builder generates these service classes and interfaces.\nOnly the {[}ENTITY\\_NAME{]}LocalServiceImpl (e.g., EventLocalServiceImpl\nfor the Event entity) allows custom methods to be added to the service\nlayer.}\n\\end{figure}\n\n\\begin{itemize}\n\\tightlist\n\\item\n Remote Service (generated for an entity only if an entity's\n \\texttt{remote-service} attribute is \\emph{not} set to \\texttt{false}\n in \\texttt{service.xml})\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Service}: Remote service interface.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ServiceImpl} (\\textbf{REMOTE SERVICE\n IMPLEMENTATION}): Remote service implementation. This is the only\n class in the remote service that you should modify manually. Here,\n you can write code that adds additional security checks and invokes\n the local services. For any custom methods added here, Service\n Builder adds corresponding methods to the\n \\texttt{{[}ENTITY\\_NAME{]}Service} interface the next time you run\n it.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ServiceBaseImpl}: Remote service base\n implementation. This is an abstract class. \\texttt{@abstract}\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ServiceUtil}: Remote service utility class\n which wraps \\texttt{{[}ENTITY\\_NAME{]}ServiceImpl}. This class is\n generated for backwards compatibility purposes only. Use the\n \\texttt{*Service} class by referencing it with the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{\\texttt{@Reference}\n annotation}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ServiceWrapper}: Remote service wrapper\n which implements \\texttt{{[}ENTITY\\_NAME{]}Service}. This class is\n designed to be extended and it lets you\n \\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{customize\n the entity's remote services}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ServiceSoap}: SOAP utility which the\n remote \\texttt{{[}ENTITY\\_NAME{]}ServiceUtil} remote service utility\n can access.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Soap}: SOAP model, similar to\n \\texttt{{[}ENTITY\\_NAME{]}ModelImpl}.\n \\texttt{{[}ENTITY\\_NAME{]}Soap} is serializable; it does not\n implement \\texttt{{[}ENTITY\\_NAME{]}}.\n \\end{itemize}\n\\item\n Model\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Model}: Base model interface. This\n interface and its \\texttt{{[}ENTITY\\_NAME{]}ModelImpl}\n implementation serve only as a container for the default property\n accessors Service Builder generates. Any helper methods and all\n application logic should be added to\n \\texttt{{[}ENTITY\\_NAME{]}Impl}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}ModelImpl}: Base model implementation.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}}: \\texttt{{[}ENTITY\\_NAME{]}} model\n interface which extends \\texttt{{[}ENTITY\\_NAME{]}Model}.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Impl}: (\\textbf{MODEL IMPLEMENTATION})\n Model implementation. You can use this class to add helper methods\n and application logic to your model. If you don't add any helper\n methods or application logic, only the auto-generated field getters\n and setters are available. Whenever you add custom methods to this\n class, Service Builder adds corresponding methods to the\n \\texttt{{[}ENTITY\\_NAME{]}} interface the next time you run it.\n \\item\n \\texttt{{[}ENTITY\\_NAME{]}Wrapper}: Wrapper, wraps\n \\texttt{{[}ENTITY\\_NAME{]}}. This class is designed to be extended\n and it lets you\n \\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{customize\n the entity}.\n \\end{itemize}\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/service-builder-model-diagram.png}\n\\caption{Service Builder generates these model classes and interfaces.\nOnly \\texttt{{[}ENTITY\\_NAME{]}Impl} (e.g., \\texttt{EventImpl} for the\nEvent entity) allows custom methods to be added to the service layer.}\n\\end{figure}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} \\texttt{*Util} classes are generated for backwards\ncompatibility purposes only. Your module applications should avoid\ncalling the util classes. Use the non-util classes instead--you can\nreference them using the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{\\texttt{@Reference}\nannotation}.\n\n\\noindent\\hrulefill\n\nEach file that Service Builder generates is assembled from an associated\nFreeMarker template. The FreeMarker templates are in the\n\\href{https://github.com/liferay/liferay-portal/tree/master/modules/util/portal-tools-service-builder}{portal-tools-service-builder\nmodule's}\n\\texttt{src/main/resources/com/liferay/portal/tools/service/builder/dependencies/}\nfolder. For example, Service Builder uses the \\texttt{service\\_impl.ftl}\ntemplate to generate the \\texttt{*ServiceImpl.java} classes.\n\nYou can modify any \\texttt{*Impl} class Service Builder generates. The\nmost common are \\texttt{*LocalServiceImpl}, \\texttt{*ServiceImpl} and\n\\texttt{*Impl}. If you modify the other classes, Service Builder\noverwrites the changes the next time you run it. Whenever you add\nmethods to, remove methods from, or change a method signature of a\n\\texttt{*LocalServiceImpl} class, \\texttt{*ServiceImpl} class, or\n\\texttt{*Impl} class, you should run Service Builder again to regenerate\nthe affected interfaces and the service JAR.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Service Builder may generate code that requires adding\ndependencies to your \\texttt{*-service} module build file.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} When \\texttt{spring} is the dependency injector (see\n\\emph{Dependency Injector} in\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information}{Defining\nGlobal Service Information}), the \\texttt{-LocalServiceBaseImpl} classes\nService Builder generates include \\texttt{-LocalService} and\n\\texttt{-Persistence} member fields of all the \\texttt{service.xml}'s\nentities. \\texttt{-LocalServiceImpl} classes inherit these fields and\nare Spring beans. The Spring beans can reference each other. For\nexample, Spring bean A can have a Spring bean B field and vice versa.\nLiferay's \\texttt{spring} dependency injector accommodates Spring bean\ncircular references. The \\texttt{ds} dependency injector does not\naccommodate circular references.\n\nWhen using \\texttt{ds} as the dependency injector,\n\\texttt{-LocalServiceImpl} classes are OSGi Declarative Services. Such\nservices start only after all the other services they reference have\nstarted. If declarative service A has a declarative service B member\nfield and vice versa, neither service can start. For this reason, the\n\\texttt{-LocalServiceBaseImpl} classes Service Builder generates don't\ninclude \\texttt{-LocalService} member fields of the\n\\texttt{service.xml}'s other entities. When using the \\texttt{ds}\ndependency injector, you must make sure member fields you add to service\nclasses don't create circular dependencies.\n\n\\noindent\\hrulefill\n\nCongratulations! You've generated your application's initial model,\npersistence, and service layers and you understand the generated code.\n\n\\textbf{Related Topics}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Running\nService Builder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/understanding-servicecontext}{Understanding\nService Context}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Services}\n\n\\chapter{Iterative Development}\\label{iterative-development}\n\nAs you develop an application, you might need to add fields to your\ndatabase. This is a normal process of iterative development: you get an\nidea for a new feature, or it's suggested to you, and that feature\nrequires additional data in the database. \\textbf{New fields added to\n\\texttt{service.xml} are not automatically added to the database.} To\nadd the fields, you must do one of two things:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Write an\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/upgrade-processes}{upgrade\n process} to modify the tables and preserve the data, or\n\\item\n Run the \\texttt{cleanServiceBuilder}\n \\href{/docs/7-2/reference/-/knowledge_base/r/db-support-gradle-plugin}{Gradle\n task} (also supported on Maven and Ant), which drops your tables so\n they get re-created the next time your app is deployed. The\n \\href{/docs/7-2/reference/-/knowledge_base/r/db-support-plugin}{Maven\n DB Support Plugin} reference article explains how to run this command\n from a Maven project.\n\\end{enumerate}\n\nUse the first option if you have a released application and you must\npreserve user data. Use the second option if you're adding new columns\nduring development.\n\n\\section{Related Topics}\\label{related-topics-13}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/upgrade-processes}{Upgrade\nProcesses}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/db-support-gradle-plugin}{Gradle\nDB Support Plugin}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/db-support-plugin}{Maven DB\nSupport Plugin}\n\n\\chapter{Customizing Model Entities With Model\nHints}\\label{customizing-model-entities-with-model-hints}\n\nOnce you've used Service Builder to define model entities, you may want\nto further refine how users enter that data. For example, model hints\ncan define a calendar field with selectable dates only in the future.\nModel hints specify entity data restrictions and other formatting.\n\nYou define model hints in a file called\n\\texttt{portlet-model-hints.xml}. The \\texttt{portlet-model-hints.xml}\nfile goes in the service module's \\texttt{src/main/resources/META-INF}\nfolder.\n\nModel hints define two things:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n How entities are presented to users\n\\item\n The size of database columns\n\\end{enumerate}\n\nAs Liferay renders your form fields, it customizes the form's input\nfields based on your configuration.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} If you chose Spring as the dependency injector, Service\nBuilder generates a number of XML configuration files in your service\nmodule's \\texttt{src/main/resources/META-INF} folder. Service Builder\nuses most of these files to manage Spring and Hibernate configurations.\nDon't modify the Spring or Hibernate configuration files; changes to\nthem are overwritten when Service Builder runs. You can, however, safely\nedit the \\texttt{portlet-model-hints.xml} file.\n\n\\noindent\\hrulefill\n\nSince the Guestbook doesn't have much of a model hints file, as an\nexample, consider the\n\\href{https://repository.liferay.com/nexus/content/repositories/liferay-public-releases/com/liferay/com.liferay.bookmarks.service/}{Bookmarks\napp service module's} model hints file:\n\n\\begin{verbatim}\n\n\n\n \n \n \n \n \n \n \n \n \n \n \n 4000\n \n \n 255\n \n \n \n \n \n \n \n \n \n \n \n 20\n \n \n \n \n \n \n \n \n ...\n \n\n\\end{verbatim}\n\nThe root-level element is \\texttt{model-hints}. Model entities are\nrepresented by \\texttt{model} sub-elements of the \\texttt{model-hints}\nelement. Each \\texttt{model} element must have a \\texttt{name} attribute\nspecifying the fully-qualified class name. Models have \\texttt{field}\nelements representing their entity's columns. Lastly, \\texttt{field}\nelements must have a name and a type. Each \\texttt{field} element's name\nand type maps to the name and type specified for the entity's column in\nthe service module's \\texttt{service.xml} file. Service Builder\ngenerates all these elements for you, based on the \\texttt{service.xml}.\n\nTo add hints to a field, add a \\texttt{hint} child element. For example,\nyou can add a \\texttt{display-width\\ hint} to specify the pixel width to\nuse in displaying the field. The default pixel width is \\texttt{350}. To\nshow a \\texttt{String} field with 50 pixels, you could nest a\n\\texttt{hint} element named \\texttt{display-width} and give it a value\nof \\texttt{50}.\n\nTo see the effect of a hint on a field,\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{run\nService Builder} again and\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{redeploy\nyour module}. Note that changing \\texttt{display-width} doesn't limit\nthe number of characters a user can enter into the \\texttt{name} field;\nit only controls the field's width in the AlloyUI input form.\n\nTo configure the maximum size of a model field's database column (i.e.,\nthe maximum number of characters that can be saved for the field), use\nthe \\texttt{max-length} hint. The default \\texttt{max-length} value is\n\\texttt{75} characters. If you want the \\texttt{name} field to persist\nup to 100 characters, add a \\texttt{max-length} hint to that field:\n\n\\begin{verbatim}\n\n 50\n 100\n\n\\end{verbatim}\n\nRemember to run Service Builder and redeploy your project after updating\nthe \\texttt{portlet-model-hints.xml} file.\n\n\\section{Model Hint Types}\\label{model-hint-types}\n\nSo far, you've seen a few different hints. The following table describes\nthe portlet model hints available for use.\n\n\\textbf{Model Hint Values and Descriptions}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n Name | Value Type | Description | Default |\n\\end{verbatim}\n\n\\texttt{auto-escape} \\textbar{} boolean \\textbar{} sets whether text\nvalues should be escaped via \\texttt{HtmlUtil.escape} \\textbar{} true\n\\textbar{} \\texttt{autoSize} \\textbar{} boolean \\textbar{} displays the\nfield in a for scrollable text area \\textbar{} false \\textbar{}\n\\texttt{day-nullable} \\textbar{} boolean \\textbar{} allows the day to be\nnull in a date field \\textbar{} false \\textbar{} \\texttt{default-value}\n\\textbar{} String \\textbar{} sets the default value of the form field\nrendered using the aui taglib \\textbar{} (empty String) \\textbar{}\n\\texttt{display-height} \\textbar{} integer \\textbar{} sets the display\nheight of the form field rendered using the aui taglib \\textbar{} 15\n\\textbar{} \\texttt{display-width} \\textbar{} integer \\textbar{} sets the\ndisplay width of the form field rendered using the aui taglib \\textbar{}\n350 \\textbar{} \\texttt{editor} \\textbar{} boolean \\textbar{} sets\nwhether to provide an editor for the input \\textbar{} false \\textbar{}\n\\texttt{max-length} \\textbar{} integer \\textbar{} sets the maximum\ncolumn size for SQL file generation \\textbar{} 75 \\textbar{}\n\\texttt{month-nullable} \\textbar{} boolean \\textbar{} allows the month\nto be null in a date field \\textbar{} false \\textbar{} \\texttt{secret}\n\\textbar{} boolean \\textbar{} sets whether to hide the characters input\nby the user \\textbar{} false \\textbar{} \\texttt{show-time} \\textbar{}\nboolean \\textbar{} sets whether to show the time along with the date\n\\textbar{} true \\textbar{} \\texttt{upper-case} \\textbar{} boolean\n\\textbar{} converts all characters to upper case \\textbar{} false\n\\textbar{} \\texttt{year-nullable} \\textbar{} boolean \\textbar{} allows a\ndate field's year to be null \\textbar{} false \\textbar{}\n\\texttt{year-range-delta} \\textbar{} integer \\textbar{} specifies the\nnumber of years to display from today's date in a date field rendered\nwith the aui taglib \\textbar{} 5 \\textbar{} \\texttt{year-range-future}\n\\textbar{} boolean \\textbar{} sets whether to include future dates\n\\textbar{} true \\textbar{} \\texttt{year-range-past} \\textbar{} boolean\n\\textbar{} sets whether to include past dates \\textbar{} true \\textbar{}\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: The aui taglib is fully supported and not related to\nAlloyUI (the JavaScript library) that's deprecated.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: You can use a mix of Clay and aui tags in a form. Model\nhints, however, affect aui tags only.\n\n\\noindent\\hrulefill\n\nNote that Liferay has its own model hints file\n(\\texttt{portal-model-hints.xml}). It's in \\texttt{portal-impl.jar}'s\n\\texttt{META-INF} folder. This file contains many hint examples, so you\ncan reference it when creating \\texttt{portlet-model-hints.xml} files.\n\n\\section{Default Hints}\\label{default-hints}\n\nYou can use the \\texttt{default-hints} element to define a list of hints\nto apply to every field of a model. For example, adding the following\nelement inside a model element applies a \\texttt{display-width} of 300\npixels to each field:\n\n\\begin{verbatim}\n\n 300\n\n\\end{verbatim}\n\n\\section{Hint Collections}\\label{hint-collections}\n\nYou can define \\texttt{hint-collection} elements inside the\n\\texttt{model-hints} root-level element to define a list of hints to\napply together. A hint collection must have a name. For example,\nLiferay's \\texttt{portal-model-hints.xml} defines the following hint\ncollections:\n\n\\begin{verbatim}\n\n 2000000\n\n\n true\n 2000000\n\n\n 254\n\n\n 200\n\n\n true\n true\n true\n false\n\n\n 105\n 500\n 4000\n\n\n 4000\n\n\\end{verbatim}\n\nYou can apply a hint collection to a model field by referencing the hint\ncollection's name. For example, if you define a \\texttt{SEARCHABLE-DATE}\ncollection like the one above in your \\texttt{model-hints} element, you\ncan apply it to your model's date field by using a\n\\texttt{hint-collection} element that references the collection by its\nname:\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\nSuppose you want to use a couple of model hints in your project. Start\nby providing users with an editor for filling in their comment fields.\nTo apply the same hint to multiple entities, define it as a hint\ncollection. Then reference the hint collection in each entity.\n\nTo define a hint collection, add a \\texttt{hint-collection} element\ninside the \\texttt{model-hints} root element in your\n\\texttt{portlet-model-hints.xml} file. For example:\n\n\\begin{verbatim}\n\n 105\n 500\n 4000\n\n\\end{verbatim}\n\nTo reference a hint collection for a specific field, add the\n\\texttt{hint-collection} element inside the field's \\texttt{field}\nelement:\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\nAfter defining hint collections and adding hint collection references,\nrebuild your services, redeploy your project, and check that the hints\ndefined in your hint collection have taken effect.\n\nNice work! Now you can not only influence how your model's input fields\nare displayed, but you can also can set its database table column sizes.\nYou can organize hints, insert individual hints directly into your\nfields, apply a set of default hints to all of a model's fields, or\ndefine collections of hints to apply at either of those scopes.\n\n\\chapter{Configuring\nservice.properties}\\label{configuring-service.properties}\n\nService Builder generates a \\texttt{service.properties} file in your\n\\texttt{*-service} module's \\texttt{src/main/resources} folder. Liferay\nDXP uses this file's properties to alter your service's database schema.\nYou should not modify this file directly, but rather make any necessary\nproperty overrides in a \\texttt{service-ext.properties} file in that\nsame folder.\n\nHere are some of the properties the \\texttt{service.properties} file\nincludes:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{build.namespace}: This is the\n \\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{namespace\n you defined in your \\texttt{service.xml}}. Liferay distinguishes\n different modules from each other using their namespaces.\n\\item\n \\texttt{build.number}: Liferay distinguishes your module's different\n Service Builder builds. Each time you deploy a distinct Service\n Builder build to Liferay, Liferay increments this number.\n\\item\n \\texttt{build.date}: This is the time of your module's latest Service\n Builder build.\n\\item\n \\texttt{include-and-override}: The default value of this property\n defines \\texttt{service-ext.properties} as an override file for\n \\texttt{service.properties}.\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: In Liferay Portal 6.x Service Builder portlets, the\n\\texttt{build.auto.upgrade} property in \\texttt{service.properties}\napplies Liferay Service schema changes upon rebuilding services and\nredeploying the portlets. This property was deprecated in Liferay 7.0.\n\nThe Build Auto Upgrade feature is now different and is set in a global\nproperty \\texttt{schema.module.build.auto.upgrade} in the file\n\\texttt{{[}Liferay\\_Home{]}/portal-developer.properties}.\n\n\\noindent\\hrulefill\n\nAwesome! You now have all the tools necessary to set up your own\n\\texttt{service-ext.properties} file.\n\n\\section{Related Topics}\\label{related-topics-14}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder?}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Services}\n\n\\chapter{Connecting Service Builder to an External\nDatabase}\\label{connecting-service-builder-to-an-external-database}\n\nIf you want to use a database separate from Liferay DXP's, follow these\nsteps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Specify your database and a data source name in your\n \\texttt{service.xml}.\n\\item\n Create the database manually.\n\\item\n Define the data source.\n\\item\n Connect your Service Builder module to the data source.\n\\item\n Run Service Builder.\n\\end{enumerate}\n\nThere are two different ways to create the connection:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\textbf{\\texttt{DataSourceProvider}:} This approach involves\n implementing a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/jdbc/DataSourceProvider.html}{\\texttt{DataSourceProvider}}\n \\href{https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html}{\\texttt{ServiceProviderInterface}}\n (SPI). This way requires the fewest files and steps and works\n regardless of whether your Service Builder module uses the \\texttt{ds}\n or \\texttt{spring}\n \\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#dependency-injector}{dependency\n injector}.\n\\item\n \\textbf{Spring Beans:} Configure the connection using Spring XML\n files. This approach only works with Service Builder modules that use\n the \\texttt{spring}\n \\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#dependency-injector}{dependency\n injection option}.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} All entities defined in a Service Builder module's\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{\\texttt{service.xml}}\nfile are bound to the same data source. Binding different entities to\ndifferent data sources requires defining the entities in separate\nService Builder modules and configuring each of the modules to use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Warning:} If your Service Builder services require nested\ntransactions, using an external data source may not be appropriate.\nTransactions between separate data sources cannot be fully nested.\nRollbacks may not propagate between services that use an external data\nsource and Liferay DXP services (or another app's services) that use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\nSince \\texttt{DataSourceProvider} is the easiest, most versatile\napproach, it's explained first.\n\n\\chapter{Connecting the Data Source Using a\nDataSourceProvider}\\label{connecting-the-data-source-using-a-datasourceprovider}\n\nConnecting to an external database by creating and registering a\n\\texttt{DataSourceProvider} as a JDK\n\\href{https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html}{\\texttt{ServiceProviderInterface}}\n(SPI) is the easiest way. This approach works regardless of whether your\nService Builder module uses the \\texttt{ds} or \\texttt{spring}\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#dependency-injector}{dependency\ninjection option} and it requires the fewest files and steps.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} All entities defined in a Service Builder module's\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{\\texttt{service.xml}}\nfile are bound to the same data source. Binding different entities to\ndifferent data sources requires defining the entities in separate\nService Builder modules and configuring each of the modules to use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Warning:} If your Service Builder services require nested\ntransactions, using an external data source may not be appropriate for\nyou. Transactions between separate data sources cannot be fully nested.\nRollbacks may not propagate between a module that uses an external data\nsource and Liferay DXP services (or another app's services) that use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\nHere are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n In your \\texttt{service.xml} file, specify the same arbitrary data\n source name for all of the entities, a unique table name for each\n entity, and a database column name for each column. Here's an example:\n\n\\begin{verbatim}\n\n\n\n\n TestDB\n \n \n \n \n \n\n\\end{verbatim}\n\n Note the example's \\texttt{\\textless{}entity\\textgreater{}} tag\n attributes:\n\n \\emph{\\texttt{data-source}}: The \\texttt{liferayDataSource} alias\n \\texttt{ext-spring.xml} specifies.\n\n \\emph{\\texttt{table}}: Your entity's database table.\n\n Also note that your entity's \\texttt{\\textless{}column\\textgreater{}}s\n must have a \\emph{\\texttt{db-name}} attribute set to the column name.\n\\item\n \\href{https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/installing-liferay/configuring-a-database.html}{Manually\n create the database} you defined in your \\texttt{service.xml}.\n\\item\n Define the data source. One way is to use\n \\href{/docs/7-2/deploy/-/knowledge_base/d/portal-properties}{portal\n properties} in a \\texttt{portal-ext.properties} file. Distinguish your\n data source from Liferay's default data source by giving it a prefix\n other than \\texttt{jdbc.default.}. This example uses prefix\n \\texttt{jdbc.ext.}.\n\n\\begin{verbatim}\njdbc.ext.driverClassName=org.mariadb.jdbc.Driver\njdbc.ext.password=userpassword\njdbc.ext.url=jdbc:mariadb://localhost/external?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false\njdbc.ext.username=yourusername\n\\end{verbatim}\n\\item\n Restart your server if you defined your data source using portal\n properties.\n\\item\n Connect your Service Builder module to the data source by implementing\n the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/jdbc/DataSourceProvider.html}{\\texttt{DataSourceProvider}}\n interface. Since the \\texttt{DataSourceProvider} must be visible to\n your \\texttt{*-service} module class loader, it's common to put the\n \\texttt{DataSourceProvider} in the \\texttt{*-service} module.\n\n This example uses\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/jdbc/DataSourceFactoryUtil.html}{\\texttt{DataSourceFactoryUtil}}\n to create a data source from\n \\href{/docs/7-2/deploy/-/knowledge_base/d/portal-properties}{portal\n properties} that have the prefix \\texttt{jdbc.ext.}.\n\n\\begin{verbatim}\npackage com.liferay.external.data.source.test.internal;\n\nimport com.liferay.portal.kernel.dao.jdbc.DataSourceFactoryUtil;\nimport com.liferay.portal.kernel.dao.jdbc.DataSourceProvider;\nimport com.liferay.portal.kernel.util.PropsUtil;\n\nimport javax.sql.DataSource;\n\npublic class DataSourceProviderImpl implements DataSourceProvider {\n\n @Override\n public DataSource getDataSource() {\n try {\n return DataSourceFactoryUtil.initDataSource(\n PropsUtil.getProperties(\"jdbc.ext.\", true));\n }\n catch (Exception e) {\n throw new RuntimeException(e);\n }\n }\n\n}\n\\end{verbatim}\n\\item\n Register the implementation as a JDK\n \\href{https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html}{\\texttt{ServiceProviderInterface}}\n (SPI) in a\n \\texttt{/META-INF/services/com.liferay.portal.kernel.dao.jdbc.DataSourceProvider}\n file in your \\texttt{*-service} module. For example, this file\n registers the \\texttt{DataSourceProvider} implementation from the\n previous step.\n\n\\begin{verbatim}\ncom.liferay.external.data.source.test.internal.DataSourceProviderImpl\n\\end{verbatim}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Run\n Service Builder}.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{Deploy}\n your \\texttt{-service} module. If your \\texttt{DataSourceProvider} is\n in a different project, deploy it too.\n\\end{enumerate}\n\nCongratulations! Your module's Service Builder services are persisting\ndata to your external data source.\n\n\\section{Related Topics}\\label{related-topics-15}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/connecting-to-data-sources-using-jndi}{Connecting\nto JNDI Data Sources}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Business\nLogic with Service Builder}\n\n\\chapter{Connecting the Data Source Using Spring\nBeans}\\label{connecting-the-data-source-using-spring-beans}\n\nSometimes you want to use a database other than Liferay DXP's. To do\nthis, its data source must be defined in \\texttt{portal-ext.properties}\nor configured as a JNDI data source on the app server. Here you'll\nconnect\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder} to a data source using Spring XML files. This approach only\nworks with Service Builder modules that use the \\texttt{spring}\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#dependency-injector}{dependency\ninjection option}. Here are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Specify your database and a data source name in your\n \\texttt{service.xml}.\n\\item\n Create the database manually.\n\\item\n Define the data source.\n\\item\n Create a Spring bean that points to the data source.\n\\item\n Run Service Builder.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} All entities defined in a Service Builder module's\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{\\texttt{service.xml}}\nfile are bound to the same data source. Binding different entities to\ndifferent data sources requires defining the entities in separate\nService Builder modules and configuring each of the modules to use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Warning:} If your Service Builder services require nested\ntransactions, using an external data source may not be appropriate for\nyou. Transactions between separate data sources cannot be fully nested.\nRollbacks may not propagate between a module that uses an external data\nsource and Liferay DXP services (or another app's services) that use a\ndifferent data source.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Connecting to an external data source using JNDI is\nbroken in Portal CE 7.2 GA1 and GA2, and in DXP 7.2 releases prior to\nFP5/SP2. See\n\\href{https://issues.liferay.com/browse/LPS-107733}{LPS-107733} for\ndetails.\n\n\\noindent\\hrulefill\n\n\\section{\\texorpdfstring{Specify Your Database and a Data Source Name in\nYour\n\\texttt{service.xml}}{Specify Your Database and a Data Source Name in Your service.xml}}\\label{specify-your-database-and-a-data-source-name-in-your-service.xml}\n\nIn your \\texttt{service.xml} file, specify the same arbitrary data\nsource name for all of the entities, a unique table name for each\nentity, and a database column name for each column. Here's an example:\n\n\\begin{verbatim}\n\n\n\n\n TestDB\n \n \n \n \n \n\n\\end{verbatim}\n\nNote the example's \\texttt{\\textless{}entity\\textgreater{}} tag\nattributes:\n\n\\emph{\\texttt{data-source}}: The \\texttt{liferayDataSource} alias\n\\texttt{ext-spring.xml} specifies.\n\n\\emph{\\texttt{table}}: Your entity's database table.\n\nAlso note that your entity's \\texttt{\\textless{}column\\textgreater{}}s\nmust have a \\emph{\\texttt{db-name}} attribute set to the column name.\n\n\\section{Create the Database\nManually}\\label{create-the-database-manually}\n\n\\href{https://learn.liferay.com/dxp/latest/en/installation-and-upgrades/installing-liferay/configuring-a-database.html}{Create\nthe database} per the database specification in your\n\\texttt{service.xml}.\n\nNext, use portal properties to set your data source.\n\n\\section{Define the Data Source}\\label{define-the-data-source}\n\nIf the application server defines the data source using JNDI, skip this\nstep. Otherwise, specify the data source in a\n\\href{/docs/7-2/deploy/-/knowledge_base/d/portal-properties}{\\texttt{portal-ext.properties}\nfile}. Distinguish it from Liferay's default data source by giving it a\nprefix other than \\texttt{jdbc.default.}. This example uses prefix\n\\texttt{jdbc.ext.}:\n\n\\begin{verbatim}\njdbc.ext.driverClassName=org.mariadb.jdbc.Driver\njdbc.ext.password=userpassword\njdbc.ext.url=jdbc:mariadb://localhost/external?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false\njdbc.ext.username=yourusername\n\\end{verbatim}\n\nRestart your server if you defined your data source using portal\nproperties.\n\n\\section{Connect Your Service Builder Module to the Data Source Via a\nSpring\nBean}\\label{connect-your-service-builder-module-to-the-data-source-via-a-spring-bean}\n\nTo do this, create a parent context extension\n(e.g.,\\texttt{ext-spring.xml}) in your \\texttt{*-service} module's\n\\texttt{src/main/resources/META-INF/spring} folder or in your\ntraditional portlet's \\texttt{WEB-INF/src/META-INF} folder. Create this\nfolder if it doesn't exist already.\n\nDefine the following elements:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n A data source factory Spring bean for the data source. It's different\n based on the type.\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\textbf{JNDI}: Specify an arbitrary property prefix and prepend the\n prefix to a JNDI name property key. Here's an example:\n \\end{itemize}\n\n\\begin{verbatim}\n\n \n \n \n jdbc/externalDataSource\n \n \n\n\\end{verbatim}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\textbf{Portal Properties}: Specify a property prefix that matches\n the prefix (e.g., \\texttt{jdbc.ext.}) you used in\n \\texttt{portal-ext.properties}.\n \\end{itemize}\n\n\\begin{verbatim}\n\n \n\n\\end{verbatim}\n\\item\n A Liferay data source bean that refers to the data source factory\n Spring bean.\n\\item\n An alias for the Liferay data source bean. Name the alias after the\n data source name you specified in the \\texttt{service.xml}.\n\n Here's an example \\texttt{ext-spring.xml} that points to a JNDI data\n source:\n\n\\begin{verbatim}\n\n\n\n\n \n \n \n \n \n jdbc/externalDataSource\n \n \n \n\n \n \n \n \n\n \n \n\n\\end{verbatim}\n\\end{enumerate}\n\nThe \\texttt{liferayDataSourceFactory} above refers to a JNDI data source\nnamed \\texttt{jdbc/externalDataSource}. If the data source is in a\n\\texttt{portal-ext.properties} file, the bean requires only a\n\\texttt{propertyPrefix} property that matches the data source property\nprefix.\n\nThe data source bean \\texttt{liferayDataSource} is overridden with one\nthat refers to the \\texttt{liferayDataSourceFactory} bean. The override\naffects this bundle (module or\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Web\nApplication Bundle}) only.\n\nThe alias \\texttt{extDataSource} refers to the\n\\texttt{liferayDataSource} data source bean.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} The \\texttt{alias} element's \\texttt{alias}\nattribute value must match the data source name specified in the\n\\texttt{service.xml}. For example, the alias attribute value above is\n\\texttt{extDataSource}.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: To use an external data source in multiple Service\nBuilder bundles, you must override the \\texttt{liferayDataSource} bean\nin each bundle.\n\n\\noindent\\hrulefill\n\n\\section{Run Service Builder}\\label{run-service-builder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Run\nService Builder} and\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{deploy}\nyour \\texttt{-service} module. Now your Service Builder services use the\ndata source. You can\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{use\nthe services in your business logic} as you always have regardless of\nthe underlying data source.\n\nCongratulations! You've connected Service Builder to your external data\nsource.\n\n\\section{Related Topics}\\label{related-topics-16}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-application-using-external-database-via-jndi}{Sample\nService Builder Application Using External Database via JNDI}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-application-using-external-database-via-jdbc}{Sample\nService Builder Application Using External Database via JDBC}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Business\nLogic with Service Builder}\n\n\\chapter{Migrating a Service Builder Module from Spring DI to OSGi\nDS}\\label{migrating-a-service-builder-module-from-spring-di-to-osgi-ds}\n\nPrior to Liferay DXP 7.2, Service Builder modules could only use Spring\nfor dependency injection (DI). Now\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\nDeclarative Services} (DS) is the default dependency injection mechanism\nfor new Service Builder modules. It's easier to learn and fosters loose\ncoupling between services. If you have an existing Service Builder\nmodule that uses Spring DI, you can modify it to use DS.\n\nHere are the conversion steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Prepare your project for DS\n\\item\n Update your Spring bean classes\n\\item\n Resolve any circular dependencies\n\\end{enumerate}\n\nNow prepare your project.\n\n\\section{Step 1: Prepare Your Project for\nDS}\\label{step-1-prepare-your-project-for-ds}\n\nPrepare your project's metadata, dependencies, and \\texttt{service.xml}\nfor DS.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Enable the DS annotation option for your inherited dependencies by\n adding this line to your \\texttt{bnd.bnd} file:\n\n\\begin{verbatim}\n-dsannotations-options: inherit\n\\end{verbatim}\n\\item\n Since DS Service Builder modules use the AOP API, add it as a compile\n dependency in \\texttt{build.gradle}:\n\n\\begin{verbatim}\ncompileOnly group: \"com.liferay:com.liferay.portal.aop.api\", version: \"1.0.0\"\n\\end{verbatim}\n\\item\n Add the \\texttt{dependency-injector=\"ds\"} attribute to your\n \\texttt{service.xml} file's\n \\texttt{\\textless{}service-builder\\textgreater{}} element:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\\end{enumerate}\n\n\\section{Step 2: Update Your Spring Bean\nClasses}\\label{step-2-update-your-spring-bean-classes}\n\nSome of your\n\\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{non-generated\nSpring bean classes} must be updated to use DS.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Add the\n \\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\n annotation to your \\texttt{*LocalServiceImpl}, \\texttt{*ServiceImpl},\n and \\texttt{*FinderImpl} classes.\n\\item\n If the class implements a \\texttt{*Finder} interface, declare the\n component as that service type. Example:\n\n\\begin{verbatim}\n@Component(service = MyFinder.class)\n\\end{verbatim}\n\\item\n If the class implements a remote or local service, declare the\n component as the \\texttt{com.liferay.portal.aop.AopService} service\n type. Example:\n\n\\begin{verbatim}\n@Component(service = AopService.class)\n\\end{verbatim}\n\\item\n If it's a remote service (i.e., \\texttt{-ServiceImpl} instead of\n \\texttt{-LocalServiceImpl}), enable JSON web services by setting these\n properties in your \\texttt{@Component} annotation:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{json.web.service.context.name}\n \\item\n \\texttt{json.web.service.context.path}\n \\end{itemize}\n\n Set them to the same values as the properties in your remote service\n interface's\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/spring/osgi/OSGiBeanProperties.html}{\\texttt{@OSGiBeanProperties}}\n annotation.\n\\item\n If it's a local service, enable\n \\href{https://docs.liferay.com/ce/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/service/PersistedModelLocalService.html}{\\texttt{PersistedModelLocalService}}\n service tracking by setting the \\texttt{@Component} property\n \\texttt{model.class.name} to the service entity's fully qualified\n class name.\n\\item\n Replace all the \\texttt{@ServiceReference} and \\texttt{@BeanReference}\n field annotations with the DS\n \\href{https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/Reference.html}{\\texttt{@Reference}}\n annotation.\n\\item\n Use the \\texttt{@Reference} field annotation to access any other\n services you need.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Run\n Service Builder} to regenerate the interfaces based on your\n implementation changes.\n\\item\n Replace the following methods:\n\n \\begin{itemize}\n \\item\n \\texttt{afterPropertiesSet()\\ \\{...\\}} →\n \\texttt{activate()\\ \\{...\\}} and annotate with\n \\href{https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/Activate.html}{\\texttt{@Activate}}.\n \\item\n \\texttt{destroy()\\ \\{...\\}} → \\texttt{deactivate()\\ \\{...\\}} and\n annotate with\n \\href{https://osgi.org/javadoc/r6/cmpn/org/osgi/service/component/annotations/Deactivate.html}{\\texttt{@Deactivate}}.\n \\end{itemize}\n\\end{enumerate}\n\nNext, you'll work out any remaining references you need.\n\n\\section{Step 3: Resolve Any Circular\nDependencies}\\label{step-3-resolve-any-circular-dependencies}\n\nCircular dependencies occur in a module if two or more of its DS\nservices refer to each another (either directly or indirectly). A direct\nreference occurs, for example, when service \\texttt{A} references\nservice \\texttt{B}, and \\texttt{B} references \\texttt{A}. Here's what\nthe service components might look like:\n\n\\texttt{AImpl.java}:\n\n\\begin{verbatim}\n@Component(service = A.class)\npublic class AImpl implements A {\n @Reference\n private B _b;\n}\n\\end{verbatim}\n\n\\texttt{BImpl.java}:\n\n\\begin{verbatim}\n@Component(service = B.class)\npublic class BImpl implements B {\n @Reference\n private A _a;\n} \n\\end{verbatim}\n\n\\texttt{AImpl} and \\texttt{BImpl} directly depend on each other. This\ncircular dependency prevents each service component from resolving. DS\nservice activation requires that all of a service's dependencies\n(references) be satisfied.\n\n\\textbf{Note:} Service resolution is independent and separate from\nmodule (OSGi bundle) resolution:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Module resolution is determined by the module's manifest.\n\\item\n Modules resolve before any of their services become active.\n\\item\n Services inside a module cannot activate if the module cannot resolve.\n\\item\n A module can resolve even if none of its services activate.\n\\end{itemize}\n\nThe example above demonstrates a very small circle, composed of only two\nclasses, but a circle can compose more classes. For example, \\texttt{A}\nreferences \\texttt{B}, \\texttt{B} references \\texttt{C}, \\texttt{C}\nreferences \\texttt{A}. Detecting and resolving such a dependency can be\ncomplicated.\n\nThere is no general, correct way to detect and resolve circular\ndependencies; cases vary. However, Liferay provides tools that\nfacilitate detecting circular dependencies and examining the DS service\ncomponents involved.\n\n\\begin{itemize}\n\\item\n \\texttt{system:check}: This\n \\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Gogo\n shell} command provides several checks, including one that detects\n inactive service components whose required references are unresolved.\n\\item\n \\texttt{scr:info\\ {[}component{]}}: Execute this\n \\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Gogo\n shell} command on an unresolved component to report its unresolved\n references.\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Service resolution in DS dependency injection (DI) is\ndifferent than in services that use Liferay's Spring DI. In the latter\ncase, all Spring beans in the same module act as a single bundle of\nservices that activate together and can bind together before activation.\nDS doesn't have this feature. With DS, each component in a module is its\nown service and must resolve on its own.\n\n\\noindent\\hrulefill\n\nCongratulations on converting your service module to use Declarative\nServices.\n\n\\section{Related Topics}\\label{related-topics-17}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{Understanding\nthe Code Service Builder Generates}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{Declarative\nServices}\n\n\\chapter{Business Logic with Service\nBuilder}\\label{business-logic-with-service-builder}\n\nOnce you've\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{defined\nyour application's entities} and\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{run\nService Builder} to generate your service and persistence layers, you\ncan begin adding business logic. Each entity generated by Service\nBuilder contains a model implementation, local service implementation,\nand optionally a remote service implementation class. Your application's\nbusiness logic can be implemented in these classes. The generated\nservice layer contains default methods that call CRUD operations from\nthe persistence layer. Once you've added your business logic, running\nService Builder again regenerates your application's interfaces and\nmakes your new logic available for invocation.\n\nThe heart of your service is its \\texttt{*LocalServiceImpl} class. This\nclass is your entity's local service extension point. Local services are\ninvoked from your application or by other applications running on the\nsame instance as your application.\n\nCreating services takes these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Deciding to Create Local and Remote Services.\n\\item\n Implementing the \\texttt{add} Method.\n\\item\n Implementing the \\texttt{update} and \\texttt{delete} Methods.\n\\item\n Implementing \\texttt{get} and \\texttt{get*Count} Methods\n\\item\n Implementing Other Business Logic\n\\item\n Integrating with Liferay's Services.\n\\end{enumerate}\n\nStart with deciding the service types you need.\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/creating-the-service-xml-file}{Defining\nyour object model} involves choosing whether to generate local and or\nremote service interfaces. Local services can only be invoked from the\nLiferay server on which they're deployed. Remote services are accessible\nto clients outside of the Liferay server. Before implementing local or\nremote services, consider the best practices described here:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n If you plan to have remote services, enable local services too.\n\\item\n Implement your business logic in \\texttt{*LocalServiceImpl}.\n\\item\n Create corresponding remote services methods in your\n \\texttt{*ServiceImpl}.\n\\item\n Use the remote service methods to call the local service, wrapping the\n calls in permission checks.\n\\item\n In your application, call only the remote services. This ensures that\n your service methods are secured and that you don't have to duplicate\n permissions code.\n\\end{enumerate}\n\nIf you are turning on local or remote services in your\n\\texttt{service.xml} file just now, make sure to\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{run\nService Builder} again to generate the service interfaces.\n\nNow you're ready to implement your business logic.\n\n\\chapter{Implementing an Add Method}\\label{implementing-an-add-method}\n\nYour \\texttt{*LocalServiceImpl} represents your service layer, where you\ncreate the business logic that operates on your application's data and\nthen calls the persistence layer to persist, retrieve, or delete your\ndata, using the object model defined in \\texttt{service.xml}.\n\nOne of the first methods you'll likely implement is one that creates\nentities. Liferay's convention is to implement this in an \\texttt{add*}\nmethod, where the part after \\texttt{add} is the entity name (or a\nshortened version of it). Here are the steps for implementing an\n\\texttt{add*} method:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Declare an \\texttt{add*} method with parameters for creating the\n entity.\n\\item\n Validate the parameters.\n\\item\n Generate a primary key.\n\\item\n Create an entity instance.\n\\item\n Populate the entity attributes.\n\\item\n Persist the entity.\n\\item\n Return the entity instance.\n\\end{enumerate}\n\nThis article refers to the Guestbook application's\n\\texttt{addGuestbookEntry} method from\n\\texttt{GuestbookEntryLocalServiceImpl}. To keep things simple, we have\nexcluded the code that integrates with Liferay services, such as assets,\nsocial bookmarks, and more.\n\nHere's the Guestbook application's \\texttt{addGuestbookEntry} method:\n\n\\begin{verbatim}\npublic GuestbookEntry addEntry(long userId, long guestbookId, String name, String email, String message,\n ServiceContext serviceContext) throws PortalException {\n\n long groupId = serviceContext.getScopeGroupId();\n\n User user = userLocalService.getUserById(userId);\n\n Date now = new Date();\n\n validate(name, email, message);\n\n long entryId = counterLocalService.increment();\n\n GuestbookEntry entry = guestbookEntryPersistence.create(entryId);\n\n entry.setUuid(serviceContext.getUuid());\n entry.setUserId(userId);\n entry.setGroupId(groupId);\n entry.setCompanyId(user.getCompanyId());\n entry.setUserName(user.getFullName());\n entry.setCreateDate(serviceContext.getCreateDate(now));\n entry.setModifiedDate(serviceContext.getModifiedDate(now));\n entry.setExpandoBridgeAttributes(serviceContext);\n entry.setGuestbookId(guestbookId);\n entry.setName(name);\n entry.setEmail(email);\n entry.setMessage(message);\n\n guestbookEntryPersistence.update(entry);\n\n // Calls to other Liferay frameworks go here\n\n return entry;\n}\n\\end{verbatim}\n\nThis method uses the parameters to create \\texttt{GuestbookEntry}. It\nvalidates the parameters, creates an entry with a generated entry ID\n(primary key), populates the entry, persists the entry, and returns it.\nYou can refer to this method as you create your own \\texttt{add*}\nmethod. Note that there's no real business logic here; it's a simple\napplication that takes data the user entered, validates it, and then\npersists it to the database.\n\n\\section{Step 1: Declare an add method with parameters for creating the\nentity}\\label{step-1-declare-an-add-method-with-parameters-for-creating-the-entity}\n\nCreate a public method for \\emph{adding} (creating) your application's\nentity. Make it a public method that returns the entity it creates.\n\n\\begin{verbatim}\npublic [ENTITY] add[ENTITY](...) {\n \n} \n\\end{verbatim}\n\nFor example, here's the \\texttt{addEntry} method signature:\n\n\\begin{verbatim}\npublic GuestbookEntry addEntry(long userId, long guestbookId, \n String name, String email, String message, \n ServiceContext serviceContext) throws PortalException {\n ...\n }\n\\end{verbatim}\n\nThis method specifies all the parameters needed to create and populate a\n\\texttt{GuestbookEntry} as you specified them in your\n\\texttt{service.xml} file. It throws a \\texttt{PortalException} in case\nthe parameters are invalid or a processing exception occurs (more on\nthis in a later step).\n\nMake sure to account for primary keys of other related entities. For\nexample, the \\texttt{addEntry} method above includes a parameter\n\\texttt{long\\ guestbookId} to associate the new \\texttt{GuestbookEntry}\nto a \\texttt{Guestbook}.\n\n\\section{Step 2: Validate the\nparameters}\\label{step-2-validate-the-parameters}\n\nValidate the parameters as needed. You might need to make sure a\nparameter is not empty or \\texttt{null}, or that a parameter value is\nwithin a valid range. Throw a\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/exception/PortalException.html}{\\texttt{PortalException}}\nor an extension of \\texttt{PortalException} for any invalid parameters.\n\nFor example, the \\texttt{addEntry} method invokes the following\n\\texttt{validate} method to check if the URL parameter is \\texttt{null}.\n\n\\begin{verbatim}\nprotected void validate(String name, String email, String entry) throws PortalException {\n\n if (Validator.isNull(name)) {\n throw new GuestbookEntryNameException();\n }\n\n if (!Validator.isEmailAddress(email)) {\n throw new GuestbookEntryEmailException();\n }\n\n if (Validator.isNull(entry)) {\n throw new GuestbookEntryMessageException();\n }\n}\n\\end{verbatim}\n\nNext, generate a primary key for the entity instance you're creating.\n\n\\section{Step 3: Generate a primary\nkey}\\label{step-3-generate-a-primary-key}\n\nEntities must each have a unique primary key. Liferay's\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/counter/kernel/service/CounterLocalService.html}{\\texttt{CounterLocalService}}\ngenerates them per entity. Every \\texttt{*BaseLocalServiceImpl} has a\n\\texttt{counterLocalService} field that references a\n\\texttt{CounterLocalService} object for the entity. Invoke the counter\nservice's \\texttt{increment} method to generate a primary key for your\nentity instance.\n\n\\begin{verbatim}\nlong id = counterLocalService.increment();\n\\end{verbatim}\n\nNow you have a unique ID for your entity instance. Always generate\nprimary keys in this way, as it ensures your code is compatible with all\nthe databases Liferay supports.\n\n\\section{Step 4: Create an entity\ninstance}\\label{step-4-create-an-entity-instance}\n\nThe \\texttt{*Peristence} instance associated with your entity has a\n\\texttt{create(long\\ id)} method that constructs an entity instance with\nthe given ID. Every \\texttt{*BaseLocalServiceImpl} has a\n\\texttt{*Persistence} field that references a \\texttt{*Persistence}\nobject for the entity. For example,\n\\texttt{GuestbookEntryLocalServiceImpl} as a child of\n\\texttt{GuestbookEntryLocalServiceBaseImpl} has a field\n\\texttt{guestbookEntryPersistence}, which is a reference to a\n\\texttt{GuestbookEntryPersistence} instance.\n\n\\begin{verbatim}\n@Reference\nprotected GuestbookEntryPersistence guestbookEntryPersistence;\n\\end{verbatim}\n\n\\texttt{GuestbookEntryLocalServiceImpl}'s \\texttt{addEntry} method\ncreates a \\texttt{GuestbookEntry} instance using this call:\n\n\\begin{verbatim}\nGuestbookEntry entry = guestbookEntryPersistence.create(entryId);\n\\end{verbatim}\n\nTo create an instance of your entity, invoke the \\texttt{create} method\non the \\texttt{*Persistence} field associated with the entity, making\nsure to pass in the entity primary key you generated in the previous\nstep.\n\n\\begin{verbatim}\n [ENTITY_NAME] entity = [ENTITY_NAME]Persistence.create(id);\n\\end{verbatim}\n\nIt's time to populate the new entity instance.\n\n\\section{Step 5: Populate the entity\nattributes}\\label{step-5-populate-the-entity-attributes}\n\nUse the \\texttt{add*} method parameter values and the entity's setter\nmethods to populate your entity's attributes. For example, here are the\n\\texttt{GuestbookEntry} attribute assignments:\n\n\\begin{verbatim}\nentry.setUuid(serviceContext.getUuid());\nentry.setUserId(userId);\nentry.setGroupId(groupId);\nentry.setCompanyId(user.getCompanyId());\nentry.setUserName(user.getFullName());\nentry.setCreateDate(serviceContext.getCreateDate(now));\nentry.setModifiedDate(serviceContext.getModifiedDate(now));\nentry.setExpandoBridgeAttributes(serviceContext);\nentry.setGuestbookId(guestbookId);\nentry.setName(name);\nentry.setEmail(email);\nentry.setMessage(message);\n\\end{verbatim}\n\nNote that the \\texttt{ServiceContext} is commonly used to carry an\nentity's UUID and the \\texttt{User} is associated to a company.\n\n\\section{Step 6: Persist the entity}\\label{step-6-persist-the-entity}\n\nIt's time to store the entity. Invoke the \\texttt{*Persistence} field's\n\\texttt{update} method, passing in the entity object. For example,\nhere's how the new \\texttt{GuestbookEntry} is persisted:\n\n\\begin{verbatim}\nguestbookEntryPersistence.update(entry);\n\\end{verbatim}\n\nYour entity is persisted for the application.\n\n\\section{Step 7: Return the entity}\\label{step-7-return-the-entity}\n\nFinally, return the entity you just created so the caller can use it.\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{Run\nService Builder} to propagate your new service method to the\n\\texttt{*LocalService} interface.\n\nYou've implemented your local service's \\texttt{add*} method to create\nand persist your application's entities.\n\n\\chapter{Implementing Update and Delete\nMethods}\\label{implementing-update-and-delete-methods}\n\nAfter you've implementing an\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method}{\\texttt{add*}\nmethod} for creating service entities, you'll want to create\n\\hyperref[implementing-an-update-method]{\\texttt{update*}} and\n\\hyperref[implementing-a-delete-method]{\\texttt{delete*}} methods for\nupdating and deleting them. The main difference between these and the\n\\texttt{add*} method is they must know which entity they're updating or\ndeleting.\n\n\\section{Implementing an Update\nMethod}\\label{implementing-an-update-method}\n\nAn \\texttt{update*} method for a local service resembles an\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method}{\\texttt{add*}\nmethod} most because it has parameters for setting entity attribute\nvalues. Create an \\texttt{update*} method this way:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Declare an \\texttt{update*} method with parameters for updating the\n entity.\n\\item\n Validate the parameters.\n\\item\n Retrieve the entity instance, if necessary.\n\\item\n Update the entity attributes.\n\\item\n Persist the updated entity.\n\\item\n Run Service Builder.\n\\end{enumerate}\n\nThe following code snippets from\n\\texttt{GuestbookEntryLocalServiceImpl}'s \\texttt{updateEntry} method\nare helpful to examine.\n\n\\begin{verbatim}\npublic GuestbookEntry updateEntry(long userId, long guestbookId, long entryId, String name, String email, String message,\n ServiceContext serviceContext) throws PortalException, SystemException {\n\n Date now = new Date();\n\n validate(name, email, message);\n\n GuestbookEntry entry = getGuestbookEntry(entryId);\n\n User user = userLocalService.getUserById(userId);\n\n entry.setUserId(userId);\n entry.setUserName(user.getFullName());\n entry.setModifiedDate(serviceContext.getModifiedDate(now));\n entry.setName(name);\n entry.setEmail(email);\n entry.setMessage(message);\n entry.setExpandoBridgeAttributes(serviceContext);\n\n guestbookEntryPersistence.update(entry);\n\n // Integrate with Liferay frameworks here.\n\n return entry;\n}\n\\end{verbatim}\n\nThis method has all the makings of a good \\texttt{update*} method:\n\n\\begin{itemize}\n\\tightlist\n\\item\n parameter for looking up the entity instance\n\\item\n parameters for updating the entity attributes\n\\item\n parameter validation\n\\item\n entity attribute updates\n\\item\n entity persistence\n\\item\n returns the entity instance\n\\end{itemize}\n\nRefer to the example method above as you follow the steps to create your\nown \\texttt{update*} method.\n\n\\section{Step 1: Declare an Update Method with Parameters for Updating\nthe\nEntity}\\label{step-1-declare-an-update-method-with-parameters-for-updating-the-entity}\n\nCreate a public method for updating your application's entity.\n\n\\begin{verbatim}\npublic [ENTITY] update[ENTITY](...)\n throws PortalException {\n \n} \n\\end{verbatim}\n\nReplace \\texttt{{[}ENTITY{]}} with your entity's name or nickname.\nCreate a parameter list that satisfies the entity attributes you're\nupdating. Include an entity instance parameter or an ID parameter for\nfetching the entity instance.\n\nFor example, the \\texttt{GuestbookEntryLocalServiceImpl}'s\n\\texttt{updateEntry} method signature has an ID parameter\n(\\texttt{entryId}) for fetching the \\texttt{GuestbookEntry} entity\ninstance. Also it has parameters \\texttt{folderId}, \\texttt{name},\n\\texttt{url}, and \\texttt{description} for updating the\n\\texttt{GuestbookEntry}'s respective attributes.\n\n\\begin{verbatim}\npublic GuestbookEntry updateEntry(long userId, long guestbookId, long entryId, String name, String email, String message,\n ServiceContext serviceContext) throws PortalException, SystemException {\n\\end{verbatim}\n\nNote, user ID, group ID, and service context parameters are useful for\nintegrating with Liferay's services. More on that later.\n\n\\section{Step 2: Validate the\nParameters}\\label{step-2-validate-the-parameters-1}\n\nSimilar to validating the\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method}{\\texttt{add*}\nmethod} parameters, validate your \\texttt{update*} parameters. Your\n\\texttt{add*} and \\texttt{update*} methods might be able to use the same\nvalidation code. Throw a\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/exception/PortalException.html}{\\texttt{PortalException}}\nor an extension of \\texttt{PortalException} for any invalid parameters.\n\n\\section{Step 3: Retrieve the Entity\nInstance}\\label{step-3-retrieve-the-entity-instance}\n\nIf you're passing in an entity instance, you can update it directly.\nOtherwise, pass in the entity ID (the primary key). The\n\\texttt{*Persistence} class Service Builder injects into\n\\texttt{*BaseLocalServiceImpl} classes has a\n\\texttt{findByPrimaryKey(long)} method that retrieves instances by ID.\nFor example, the \\texttt{GuestbookEntryLocalServiceImpl} retrieves the\n\\texttt{GuestbookEntry} with the primary key \\texttt{entryId}.\n\n\\begin{verbatim}\nGuestbookEntry entry = guestbookEntryPersistence.findByPrimaryKey(\n entryId);\n\\end{verbatim}\n\nInvoke the \\texttt{findByPrimaryKey(long\\ id)} method of your\n\\texttt{*Persistence} class to retrieve the entity instance that matches\nyour primary key parameter.\n\n\\begin{verbatim}\n [ENTITY] entity = [ENTITY]Persistence.findByPrimaryKey(id);\n\\end{verbatim}\n\nIt's time to update the entity attributes.\n\n\\section{Step 4: Update the Entity\nAttributes}\\label{step-4-update-the-entity-attributes}\n\nInvoke the entity's setter methods to replace its attribute values.\n\n\\section{Step 5: Persist and Return the Updated Entity\nInstance}\\label{step-5-persist-and-return-the-updated-entity-instance}\n\nPersist the updated entity to the database and return the instance to\nthe caller.\n\n\\begin{verbatim}\n[ENTITY]Persistence.update(entity);\n\n...\n\nreturn entity;\n\\end{verbatim}\n\n\\section{Step 6: Run Service Builder}\\label{step-6-run-service-builder}\n\nFinally, run Service Builder to propagate your new service method to the\n\\texttt{*LocalService} interface.\n\nYou've created a service method to update your entity. If you thought\nthat was easy, implementing a \\texttt{delete*} method is even easier.\n\n\\section{Implementing a Delete\nMethod}\\label{implementing-a-delete-method}\n\nThe \\texttt{remove} method of an entity's \\texttt{*Persistence} class\ndeletes an entity instance from the database. Use it in your local\nservice's \\texttt{delete*} method. Here's what a \\texttt{delete*} method\nlooks like:\n\n\\begin{verbatim}\npublic [ENTITY] delete[ENTITY](ENTITY entity) throws PortalException\n{\n [ENTITY]Persistence.remove(entity);\n\n // Clean up related to additional Liferay services goes here ... \n\n return entity;\n}\n\\end{verbatim}\n\nMake sure to replace \\texttt{{[}ENTITY{]}} with your entity's name or\nnickname.\n\nFor example, here's paraphrased code from\n\\texttt{GuestbookEntryLocalServiceImpl}'s \\texttt{deleteEntry} method:\n\n\\begin{verbatim}\npublic GuestbookEntry deleteEntry(GuestbookEntry entry)\n throws PortalException {\n\n guestbookEntryPersistence.remove(entry);\n\n // Clean up related to additional Liferay services goes here ... \n\n return entry;\n}\n\\end{verbatim}\n\nAfter implementing your \\texttt{delete*} method, run Service Builder to\npropagate your new service method to the \\texttt{*LocalService}\ninterface.\n\n\\section{Related Topics}\\label{related-topics-18}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method}{Implementing\nan add method}\n\n\\chapter{Implementing Methods to Get and Count\nEntities}\\label{implementing-methods-to-get-and-count-entities}\n\nService Builder generates \\texttt{findBy*} methods and \\texttt{countBy*}\nmethods in your\n\\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{\\texttt{*Persistence}\nclasses} based on your \\texttt{service.xml} file's\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-service-entity-finder-methods}{finders}.\nYou can leverage finder methods in your local services to get and count\nentities.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[getter-methods]{Getters}: \\texttt{get*} methods return\n entity instances matching criteria.\n\\item\n \\hyperref[counter-methods]{Counters}: \\texttt{get*Count} methods\n return the number of instances matching criteria\n\\end{itemize}\n\nStart with getting entities that match criteria.\n\n\\section{Getter Methods}\\label{getter-methods}\n\nThe \\texttt{findByPrimaryKey} methods and \\texttt{findBy*} methods\nsearch for and return entity instances based on criteria. Your local\nservice implementation must only wrap calls to the finder methods that\nget what you want.\n\nHere's how to create a method that gets an entity based on an ID\n(primary key):\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a method using this format:\n\n\\begin{verbatim}\npublic [ENTITY] get[ENTITY_NAME](long id) {\n return [ENTITY]Persistence.findByPrimaryKey(id);\n}\n\\end{verbatim}\n\\item\n Replace \\texttt{{[}ENTITY{]}} and \\texttt{{[}ENTITY\\_NAME{]}} with the\n respective entity type and entity name (or nickname).\n\\item\n Run Service Builder to propagate the method to your local service\n interface.\n\\end{enumerate}\n\nHere's how to get entities based on criteria:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Identify the criteria for finding the entity instance(s).\n\\item\n If there is no\n \\href{/docs/7-2/appdev/-/knowledge_base/a/defining-service-entity-finder-methods}{\\texttt{finder}\n element} for the criteria, create one for it and run Service Builder.\n\\item\n Determine the\n \\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{\\texttt{*Persistence}\n class} \\texttt{findBy*} method you want to call. Depending on your\n \\texttt{finder} element columns, Service Builder might overload the\n method to include these parameters:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{int\\ start} and \\texttt{int\\ end} parameters for specifying\n a range of entities.\n \\item\n \\texttt{com.liferay.portal.kernel.util.OrderByComparator\\ orderByComparator}\n parameter for arranging the matching entities.\n \\end{itemize}\n\\item\n Specify your \\texttt{get*} method signature, making sure to account\n for the \\texttt{*Persistence} class \\texttt{findBy*} method parameters\n you must satisfy. Use this method format:\n\n\\begin{verbatim}\npublic List<[ENTITY]> get[DESCRIBE_THE_ENTITIES](...) {\n\n}\n\\end{verbatim}\n\n Replace \\texttt{{[}ENTITY{]}} with the entity type. Replace\n \\texttt{{[}DESCRIBE\\_THE\\_ENTITIES{]}} with a descriptive name for the\n entities you're getting.\n\\item\n Call the \\texttt{*Persistence} class \\texttt{findBy*} method and\n return the list of matching entities.\n\\item\n Run Service Builder.\n\\end{enumerate}\n\nFor example, \\texttt{getGuestbookEntries} from\n\\texttt{GuestbookEntryLocalServiceImpl} returns a range of\n\\texttt{GuestbookEntry}s associated with a \\texttt{Group} primary key:\n\n\\begin{verbatim}\npublic List getGuestbookEntries(long groupId, long guestbookId) {\n return guestbookEntryPersistence.findByG_G(groupId, guestbookId);\n}\n\\end{verbatim}\n\nNow you know how to leverage finder methods to get entities. Methods\nthat count entities are next.\n\n\\section{Counter Methods}\\label{counter-methods}\n\nCounting entities is just as easy as getting them. Your\n\\texttt{*Persistence} class \\texttt{countBy*} methods do all the work.\nService Builder generates \\texttt{countBy*} methods based on each finder\nand its columns.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Identify the criteria for entity instances you're counting and\n determine the\n \\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{\\texttt{*Persistence}\n class} \\texttt{countBy*} method that satisfies the criteria.\n\\item\n Create a \\texttt{get*Count} method signature following this format:\n\n\\begin{verbatim}\npublic int get[DESCRIBE_THE_ENTITIES]Count(...) {\n\n}\n\\end{verbatim}\n\n Replace \\texttt{{[}DESCRIBE\\_THE\\_ENTITIES{]}} with a descriptive name\n for the entities you're counting.\n\\item\n Call the \\texttt{*Persistence} class' \\texttt{countBy} method and\n return the value. For example, the method \\texttt{getEntriesCount}\n from \\texttt{GuestbookEntryLocalServiceImpl} returns the number of\n \\texttt{GuestbookEntry}s that are associated with a group (matching\n \\texttt{groupId}) and a guestbook (matching \\texttt{guestbookId}).\n\\end{enumerate}\n\n\\begin{verbatim}\npublic int getGuestbookEntriesCount(long groupId, long guestbookId) {\n return guestbookEntryPersistence.countByG_G(groupId, guestbookId);\n}\n\\end{verbatim}\n\nNow your local service can get entities matching your criteria and\nreturn quick entity counts.\n\n\\section{Service Method Prefixes and Transactional\nAspects}\\label{service-method-prefixes-and-transactional-aspects}\n\nService Builder applies transactions to services by adding\n\\texttt{@Transactional} annotations to the \\texttt{*LocalService} and\n\\texttt{*Service} interfaces and their methods. By default, Service\nBuilder applies read-only transactions (e.g.,\n\\texttt{@Transactional\\ (readOnly\\ =\\ true\\ ...)}) to service methods\nprefixed with any of these words:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{dynamicQuery}\n\\item\n \\texttt{fetch}\n\\item\n \\texttt{get}\n\\item\n \\texttt{has}\n\\item\n \\texttt{is}\n\\item\n \\texttt{load}\n\\item\n \\texttt{reindex}\n\\item\n \\texttt{search}\n\\end{itemize}\n\nSince these methods operate in read-only transactions, Liferay DXP\noptimizes their performance. Transactional service methods that don't\nhave the read-only setting operate in regular transactions.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} A method implementation can override its interface's\n\\texttt{@Transactional} annotation attributes. For example, applying\n\\texttt{@Transactional\\ (readOnly\\ =\\ false\\ ...)} to a method\nimplementation makes it operate in a transaction that is not read only.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} In methods that operate in read-only transactions,\ninvoking a service method that persists data (adds, updates, or deletes\ndata) must be done via the service object. Using the service object\nensures that the defined transactional behavior is applied.\n\n\\begin{verbatim}\nsomeService.addSomething();\n\\end{verbatim}\n\nFor example, this \\texttt{*LocalServiceImpl}'s getter method adds\n(\\emph{persists}) a \\texttt{ClassName} object if no object with that\nvalue exists.\n\n\\begin{verbatim}\npublic ClassName getClassName(String value) {\n if (Validator.isNull(value)) {\n return _nullClassName;\n }\n\n ClassName className = _classNames.get(value);\n\n if (className == null) {\n try {\n className = classNameLocalService.addClassName(value);\n ...\n }\n ...\n }\n ...\n}\n\\end{verbatim}\n\nUsing the service object \\texttt{classNameLocalService} to invoke its\n\\texttt{addClassName} method applies the service method's transaction\n(the regular transaction specified for the method in the\n\\texttt{*Service} interface). If the \\texttt{addClassName} method was\ninvoked WITHOUT using the service object, the \\texttt{ClassName} object\nwould not persist because the method's regular transaction would not be\napplied.\n\n\\section{Related Topics}\\label{related-topics-19}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Services}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/implementing-an-add-method}{Implementing\nan Add Method}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-service-entity-finder-methods}{Defining\nService Entity Finder Methods}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/understanding-the-code-generated-by-service-builder}{Understanding\nthe Code Generated by Service Builder}\n\n\\chapter{Implementing Any Other Business\nLogic}\\label{implementing-any-other-business-logic}\n\nThis section's earlier local service articles focus on CRUD methods:\nmethods that \\textbf{c}reate (add), \\textbf{r}ead (get),\n\\textbf{u}pdate, and \\textbf{d}elete entities. But you might also need\nmethods that provide business logic.\n\nSince the Guestbook application doesn't have any business logic, the\nBookmarks application, which is extremely similar, (Bookmark Folders and\nBookmark entries instead of Guestbooks and Guestbook entries) is used\nhere to illustrate simple business logic. Bookmarks application users\n\\emph{open} bookmarks (navigate to a URLs) by clicking on them.\n\\href{https://github.com/liferay/liferay-portal/blob/7.2.x/modules/apps/bookmarks/bookmarks-service/src/main/java/com/liferay/bookmarks/service/impl/BookmarksEntryLocalServiceImpl.java}{\\texttt{BookmarksEntryLocalServiceImpl}}'s\n\\texttt{openEntry} method supports this functionality:\n\n\\begin{verbatim}\npublic BookmarksEntry openEntry(long userId, BookmarksEntry entry) {\n entry.setVisits(entry.getVisits() + 1);\n\n bookmarksEntryPersistence.update(entry);\n\n assetEntryLocalService.incrementViewCounter(\n userId, BookmarksEntry.class.getName(), entry.getEntryId(), 1);\n\n return entry;\n}\n\\end{verbatim}\n\nThe \\texttt{openEntry} method tracks and persists the number of visits\nto the \\texttt{BookmarksEntry}'s URL, increments the number of views for\nthe \\texttt{BookmarksEntry} as an asset, and returns the\n\\texttt{BookmarksEntry}. This method implements required business logic\nthat compliments the CRUD methods.\n\n\\emph{Convenience methods} might also be appropriate for your app.\nThey're easier to use because they typically have these characteristics:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Shorter parameter list\n\\item\n Intuitive name\n\\end{itemize}\n\nShort parameter lists are easier to satisfy, and methods that have\nintuitive names are easier to find in Javadoc.\n\nFor example, the Bookmarks application lets users move bookmarks to\ndifferent folders. Moving a bookmark can be done using the service's\n\\texttt{updateEntry(...)} method, but its long parameter list is\noverkill since all the operation requires is the bookmarks entry and the\nfolder where it's going. Compare the following \\texttt{update*} method\ncall to a convenience method call.\n\n\\textbf{Update method}:\n\n\\begin{verbatim}\nbookmarksEntryLocalService.updateEntry(userId, entryId, groupId, folderId, name, url, description, serviceContext);\n\\end{verbatim}\n\n\\textbf{Convenience method}:\n\n\\begin{verbatim}\nbookmarksEntryLocalService.moveEntry(entryId, folderId);\n\\end{verbatim}\n\nHere's the\n\\href{https://github.com/liferay/liferay-portal/blob/7.2.x/modules/apps/bookmarks/bookmarks-service/src/main/java/com/liferay/bookmarks/service/impl/BookmarksEntryLocalServiceImpl.java}{\\texttt{moveEntry}\nmethod}:\n\n\\begin{verbatim}\npublic BookmarksEntry moveEntry(long entryId, long parentFolderId)\n throws PortalException {\n\n BookmarksEntry entry = getBookmarksEntry(entryId);\n\n entry.setFolderId(parentFolderId);\n entry.setTreePath(entry.buildTreePath());\n\n bookmarksEntryPersistence.update(entry);\n\n return entry;\n}\n\\end{verbatim}\n\nThe \\texttt{moveEntry} method retrieves the \\texttt{BookmarksEntry}\nentity by its ID, assigns it a new parent folder, updates its tree path,\npersists all the entity's changes, and returns the entity. Convenience\nmethods like this one facilitate updating a subset of the entity's\nattributes.\n\nAfter implementing your custom business methods,\n\\href{/docs/7-2/appdev/-/knowledge_base/a/running-service-builder}{run\nService Builder} to propagate them to the interface.\n\nIn your local services, you can implement business logic methods that\nsuit your application.\n\n\\textbf{Related Topics}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Services}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{Invoking\nLocal Services}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-services-from-spring-service-builder-code}{Invoking\nServices from Spring Service Builder Code}\n\n\\chapter{Integrating with Liferay's\nFrameworks}\\label{integrating-with-liferays-frameworks}\n\nNew car buyers expect certain standard features: power windows, cruise\ncontrol, floor mats (at least the cheap ones), and so on. Similarly,\nusers expect applications to have certain features, and those features\nshould behave consistently across applications.\n\nFor example, a user might expect the app's content can be shared on\nsocial networks, tagged and rated, and discussed in comments. Liferay's\nframeworks implement these features users expect to see. Integrating\nwith the frameworks is easy, and the frameworks provide intuitive,\nconsistent user experiences.\n\nHere are some of Liferay's most popular frameworks:\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/defining-application-permissions}{Permissions}:\nDefines resources and permissions for entities and actions that can be\nperformed on them.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/configurable-applications}{Configurable\nApplications}: Provide configuration screens in the Control Panel.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/the-workflow-framework}{Workflow}:\nEquips entities for reviewing in workflows before publishing.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/item-selector}{Item\nSelector}: Provides a consistent experience for browsing and selecting\nentities.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/asset-framework}{Asset\nFramework}: Provides a way to make entity data generic, so common tasks\ncan be performed on them. This enables users to tag, categorize, rate,\nprioritize, and comment on anything that has been asset-enabled. Users\ncan relate entities to each other as assets, and entities can be\npublished in the Asset Publisher.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/implementing-asset-categorization-and-tagging}{Tags\n and Categories}: Enables users to tag entities and categorize them\n into logical hierarchies.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/implementing-asset-priority}{Priority}:\n Users can ascribe numerical priorities to entities.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/relating-assets}{Related\n Assets}: Users can associate one entity with another as an asset.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/asset-framework}{Asset\n Renderer}: Enables entities appearing in Asset Publisher queries.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/adding-comments-to-your-app}{Comments}:\n Lets users comment on entities.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/rating-assets}{Ratings}:\n Enables rating systems, such as five stars or thumbs up/down, on\n entities.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/flagging-inappropriate-asset-content}{Flags}:\n Users can flag entity content as inappropriate.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/applying-social-bookmarks}{Social\n Bookmarks}: Users can share entity content on Twitter, Facebook, and\n more.\n\\end{itemize}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/export-import}{Export/Import}:\nExport entity data to and import entity data from files (\\texttt{.lpkg}\nfiles). Exported data can be imported to another portal instance or\nsaved for later use.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/staging}{Staging}: Modify\ncontent behind the scenes without affecting the live site, and then\npublish to the live site when the content is ready.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/search}{Search}: Index\nentities for searching.\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/moving-entities-to-the-recycle-bin}{Recycle\nBin}: Instead of deleting entities, put them into the Recycle Bin.\nEntities can be restored from the Recycle Bin or deleted permanently\n(manually or per a schedule).\n\n\\section{Related Topics}\\label{related-topics-20}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-language-keys}{Internationalization}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/javascript-module-loaders}{JavaScript\nModule Loaders}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/front-end-taglibs}{Java\nTaglibs}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/upgrade-processes}{Upgrade\nProcesses}\n\n\\chapter{Invoking Local Services}\\label{invoking-local-services}\n\nOnce you deploy your services module, those services are available in\nthe container. Service Builder generates local and remote service\nclasses as OSGi Declarative Services (DS) components. These components\nare accessible to other DS components, so you can invoke them from other\ncomponents, such as your web application. Here's how:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Add a reference to the local service component.\n\\item\n Call the component's methods.\n\\end{enumerate}\n\nThere's a Blade sample called\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-samples}{Basic\nService Builder}. Its \\texttt{basic-web} module has a \\texttt{Portlet}\nservice component that demonstrates referencing a local service\ncomponent. This module also has JSPs that invoke the component's\nmethods. Your first step is to add a reference to the local service\ncomponent object.\n\n\\section{Step 1: Reference the Local Service\nComponent}\\label{step-1-reference-the-local-service-component}\n\nYour application's Service Builder-generated local services are DS\ncomponents that you can inject into your application's other DS\ncomponents (classes annotated with \\texttt{@Component})\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{using\nthe \\texttt{@Reference} annotation}. The \\texttt{basic-web} module's\n\\texttt{JSPPortlet} class is a \\texttt{Portlet} service component that\nreferences the \\texttt{FooLocalService} local service as a DS component.\n\n\\begin{verbatim}\n@Reference\nprivate volatile FooLocalService _fooLocalService;\n\\end{verbatim}\n\nThe OSGi service registry wires the service implementation object to\nyour class that references it. The \\texttt{JSPPortlet} sample class\ndeclares the \\texttt{\\_fooLocalService} field to be volatile, but making\na field volatile is completely optional.\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: If you chose Spring as the dependency injector, Service\nBuilder generates \\texttt{*LocalServiceImpl}, \\texttt{*ServiceImpl},\n\\texttt{*PersistenceImpl}, and \\texttt{{[}ENTITY\\_NAME{]}Impl} classes\nfor your entities as Service Builder Spring Beans---not OSGi Declarative\nServices.\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-services-from-spring-service-builder-code}{Service\nBuilder Spring Beans must use means other than the \\texttt{@Reference}\nannotation to reference Liferay services and OSGi services}.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} You should never invoke \\texttt{*LocalServiceImpl}\nobjects directly. You should only invoke them indirectly through their\n\\texttt{*LocalService} service interface. The OSGi service registry\nwires the service implementation object to your class.\n\nYou can make a service object available to JSPs by associating it with a\n\\texttt{RenderRequest} attribute. For example, the \\texttt{JSPPortlet}'s\n\\texttt{render} method associates the \\texttt{FooLocalService} object\nwith an attribute called \\texttt{fooLocalService}.\n\n\\begin{verbatim}\n@Override\npublic void render(RenderRequest request, RenderResponse response)\n throws IOException, PortletException {\n\n //set service bean\n request.setAttribute(\"fooLocalService\", getFooLocalService());\n\n super.render(request, response);\n}\n\npublic FooLocalService getFooLocalService() {\n return _fooLocalService;\n}\n\\end{verbatim}\n\nIf your JSP declares the\n\\texttt{\\textless{}portlet:defineObjects\\ /\\textgreater{}} tag, it can\nretrieve the service object from the \\texttt{RenderRequest} attribute.\nFor example, the \\texttt{JSPPortlet}'s \\texttt{init.jsp} file retrieves\nthe \\texttt{FooLocalService} object from the \\texttt{\"fooLocalService\"}\nattribute.\n\n\\begin{verbatim}\n...\n<%@\npage import=\"com.liferay.blade.samples.servicebuilder.service.FooLocalService\" %>\n...\n\n\n\n\n\n<%\n...\n\n//get service bean\nFooLocalService fooLocalService = (FooLocalService)request.getAttribute(\"fooLocalService\");\n%>\n\\end{verbatim}\n\nAll JSPs that include the above \\texttt{init.jsp} can use the\n\\texttt{fooLocalService} variable to invoke the local service\ncomponent's methods.\n\n\\section{Step 2: Call the Component's\nMethods}\\label{step-2-call-the-components-methods}\n\nNow that you have the service component object, you can invoke its\nmethods as you would any Java object's methods.\n\nThe \\texttt{basic-web} sample module's \\texttt{view.jsp} and\n\\texttt{edit\\_foo.jsp} files include the \\texttt{init.jsp} shown in the\nprevious section. Therefore, they can access the\n\\texttt{fooLocalService} variable which references the service component\nobject. The \\texttt{view.jsp} file uses the component's\n\\texttt{getFoosCount} method and \\texttt{getFoos} method in a Liferay\nSearch Container that lists \\texttt{Foo} instances.\n\n\\begin{verbatim}\n\"\n>\n \"\n />\n ...\n\n\\end{verbatim}\n\nThe \\texttt{edit\\_foo.jsp} file calls \\texttt{getFoo(long\\ id)} to\nretrieve a \\texttt{Foo} entity based on the entity instance's ID.\n\n\\begin{verbatim}\nlong fooId = ParamUtil.getLong(request, \"fooId\");\nFoo foo = null;\nif (fooId > 0) {\n foo = fooLocalService.getFoo(fooId);\n}\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} When invoking service entity updates (e.g.,\n\\texttt{fooService.update(object)}) for services that have MVCC enabled,\nmake sure to do so in transactions. Propagate rejected transactions to\nthe UI for the user to handle. For details, see\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#multiversion-concurrency-control-mvcc}{Multiversion\nconcurrency control (MVCC)}.\n\n\\noindent\\hrulefill\n\nUsing the \\texttt{@Reference} annotation, you can inject your\napplication's OSGi DS components (such as a portlet DS component) with\ninstances of your application's Service Builder-generated local service\ncomponents. Also you can provide your JSPs access to the component\ninstances via \\texttt{RenderRequest} attributes.\n\n\\section{Related Topics}\\label{related-topics-21}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Services}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{Invoking\nLocal Services}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-services-from-spring-service-builder-code}{Invoking\nLocal Services from Spring Service Builder Code}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\nServices and Dependency Injection with Declarative Services}\n\n\\chapter{Invoking Services from Spring Service Builder\nCode}\\label{invoking-services-from-spring-service-builder-code}\n\nWhen using Spring as the dependency injector, all the services created\nwithin a Service Builder application are wired using an internal Spring\nApplication Context. This uses AOP proxies to adapt the services for\ntransactions, indexing, and security. In a module's\n\\texttt{module-spring.xml} Spring Application Context file, Service\nBuilder defines each entity's \\texttt{*LocalServiceImpl},\n\\texttt{*ServiceImpl}, and \\texttt{*PersistenceImpl} classes as Spring\nBeans. For example, Service Builder defines Spring Beans for the\n\\texttt{Foo} entity in the\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-samples}{Liferay\nBlade Service Builder \\texttt{basic-service} sample module's}\n\\texttt{src/main/resources/META-INF/spring/module-spring.xml} file:\n\n\\begin{verbatim}\n\n\n\n \n \n \n\n\\end{verbatim}\n\nHere's a summary of the beans the example context defines:\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.4118}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.5882}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Interface ID}\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Implementation Class}\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\texttt{com.liferay.blade.samples.servicebuilder.service.FooLocalService}\n&\n\\texttt{com.liferay.blade.samples.servicebuilder.service.impl.FooLocalServiceImpl} \\\\\n\\texttt{com.liferay.blade.samples.servicebuilder.service.FooService} &\n\\texttt{com.liferay.blade.samples.servicebuilder.service.impl.FooServiceImpl} \\\\\n\\texttt{com.liferay.blade.samples.servicebuilder.service.persistence.FooPersistence}\n&\n\\texttt{com.liferay.blade.samples.servicebuilder.service.persistence.impl.FooPersistenceImpl} \\\\\n\\end{longtable}\n\nSince these classes are Spring Beans and NOT OSGi Declarative Services\ncomponents, they don't use the \\texttt{@Reference} Declarative Services\nannotation to inject themselves. Here are the recommended Liferay\nannotations a Service Builder Spring Bean can use.\n\n\\begin{itemize}\n\\tightlist\n\\item\n Use \\texttt{@BeanReference} to reference a Spring Bean that is in the\n Application Context.\n\\item\n Use \\texttt{@ServiceReference} to reference an OSGi service.\n\\end{itemize}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} When invoking service entity updates (e.g.,\n\\texttt{fooService.update(object)}) for services that have MVCC enabled,\nmake sure to do so in transactions. Propagate rejected transactions to\nthe UI for the user to handle. For details, see\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-global-service-information\\#multiversion-concurrency-control-mvcc}{Multiversion\nconcurrency control (MVCC)}.\n\n\\noindent\\hrulefill\n\nThe \\texttt{@BeanReference} annotation is explained first.\n\n\\section{Referencing a Spring Bean that is in the Application\nContext}\\label{referencing-a-spring-bean-that-is-in-the-application-context}\n\nA Service Builder Spring Bean class, such as a\n\\texttt{*LocalServiceImpl} class, should use Liferay's\n\\texttt{@BeanReference} annotation to access other Spring Beans the\nmodule's Spring Application Context defines.\n\nFor example, if your service module's \\texttt{service.xml} file defines\nlocal services for entities named \\texttt{Foo} and \\texttt{Bar}, Service\nBuilder generates a \\texttt{module-spring.xml} file that defines local\nservice Spring Beans for both entities. To inject the\n\\texttt{BarLocalService} Spring Bean into the\n\\texttt{FooLocalServiceImpl} class, for example, the\n\\texttt{FooLocalServiceImpl} class must declare a\n\\texttt{BarLocalService} field and apply an \\texttt{@BeanReference}\nannotation to it.\n\n\\begin{verbatim}\n@BeanReference\nprivate BarLocalService _barLocalService;\n\\end{verbatim}\n\nThe \\texttt{@BeanReference} tells Liferay's AOP to treat the bean\nreference for use in transactions, search indexing, or security, if\nneeded. The referencing class can invoke the Spring Bean class's\nmethods.\n\nBesides the services Service Builder makes available for your\napplication, Service Builder Spring Bean classes can also access any\nservice published in the OSGi Registry. This means the following\nservices are available:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Beans defined in Liferay's core\n\\item\n Beans created in other module app contexts\n\\item\n Services declared using OSGi Declarative Services\n\\item\n Services registered using the OSGi low level API\n\\end{itemize}\n\nThese are all OSGi services. The next section demonstrates a Service\nBuilder Spring Bean referencing OSGi services.\n\n\\section{Referencing OSGi Services}\\label{referencing-osgi-services}\n\nIn many cases, your Service Builder code (Spring Beans) must use\nexternal services. Liferay's \\texttt{@ServiceReference} annotation lets\nLiferay Spring Beans reference OSGi services.\n\nSuppose you're building an application with a simple entity your service\nmodule defines in its \\texttt{service.xml} file. The application must\nsend an SMS every time a new entity is created, and the\n\\texttt{SMSService} is provided by a module installed in the system.\n\nYour \\texttt{*LocalServiceImpl} (Spring Bean) could use an\n\\texttt{@ServiceReference} annotation to reference the \\emph{external}\nservice.\n\n\\begin{verbatim}\n@ServiceReference\nprivate SMSService _smsService;\n\\end{verbatim}\n\nThis annotation retrieves a reference to the OSGi service and provides\nsome nice benefits. None of the Spring context is created until the\n\\texttt{SMSService} service is available. Likewise, if the\n\\texttt{SMSService} suddenly disappears, the whole Spring Application\nContext is destroyed. This makes Liferay Spring apps robust and\nversatile.\n\nFortunately, Service Builder generates this kind of code for every\nentity your \\texttt{service.xml} file references. For example, the\n\\href{/docs/7-2/reference/-/knowledge_base/r/service-builder-samples}{Liferay\nBlade Service Builder sample project} \\texttt{basic-service} module's\n\\texttt{service.xml} file defines a \\texttt{Foo} entity that references\nan \\texttt{AssetEntry} entity:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\nService Builder generated the \\texttt{FooLocalServiceBaseImpl} class\n(the base class is part of the \\texttt{FooLocalServiceImpl} class's\nhierarchy), which references the \\texttt{AssetEntry} entity's local\nservice \\texttt{AssetEntryLocalService} using a field annotated with\n\\texttt{@ServiceReference}:\n\n\\begin{verbatim}\n@ServiceReference(type = com.liferay.asset.kernel.service.AssetEntryLocalService.class)\nprotected com.liferay.asset.kernel.service.AssetEntryLocalService assetEntryLocalService;\n\\end{verbatim}\n\nGreat! You now know how to add a reference to any OSGi service to a\nService Builder Spring Bean. You also know how to add a reference to any\nother Spring Bean in the Application Context of your Service Builder\nSpring Bean.\n\n\\section{Related Topics}\\label{related-topics-22}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{Invoking\nLocal Services}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/using-a-service-tracker}{Service\nTrackers}\n\n\\chapter{Advanced Queries}\\label{advanced-queries}\n\nService Builder doesn't limit you to what you can cook up with\n\\texttt{\\textless{}finder\\ /\\textgreater{}} elements in\n\\texttt{service.xml}. If simple finders aren't sufficient for getting\ndata out of your application, you can use Liferay's Dynamic Query API,\nwhich wraps Hibernate's Criteria API, or your own SQL to make exactly\nthe queries you need.\n\nThough you can use custom SQL queries with Service Builder to retrieve\ndata from the database, sometimes it's more convenient to build queries\ndynamically at runtime. You can do this with Liferay's Dynamic Query\nAPI, which wraps Hibernate's Criteria API. The Dynamic Query API lets\nyou build queries without writing any SQL. It helps you think in terms\nof objects and member variables instead of tables and columns. Complex\nqueries can be significantly easier to understand and maintain than the\nequivalent custom SQL (or HQL) queries. While you technically don't need\nto know SQL to construct Dynamic Queries, you still must take care to\nconstruct efficient queries. For information on Hibernate's Criteria\nAPI, please see\n\\href{http://docs.jboss.org/hibernate/orm/5.0/userguide/html_single/chapters/query/criteria/Criteria.html}{Hibernate's\nmanual}.\n\nWhichever way you decide to implement your custom queries, this guide\nshows you how. Here are the steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n If using SQL,\n \\href{/docs/7-2/appdev/-/knowledge_base/a/custom-sql}{create your SQL\n query}.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/defining-a-custom-finder-method}{Define\n a custom finder method}.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/dynamic-query}{Implement\n your finder using Dynamic Query API or SQL}.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/accessing-your-custom-finder-method-from-the-service-layer}{Add\n a method to your \\texttt{*LocalServiceImpl} class that invokes your\n finder}.\n\\end{enumerate}\n\nOnce you've taken these steps, you can access your custom finder as a\nservice method. Note: You can create multiple or overloaded\n\\texttt{findBy*} finder methods in your \\texttt{*FinderImpl} class.\nNext, you'll examine these steps in more detail.\n\n\\chapter{Custom SQL}\\label{custom-sql}\n\nService Builder creates finder methods that retrieve entities by their\nattributes: their column values. When you add a column as a parameter\nfor the finder in your \\texttt{service.xml} file and run Service\nBuilder, it generates the finder method in your persistence layer and\nadds methods to your service layer that invoke the finder. If your\nqueries are simple enough, consider using\n\\href{/docs/7-2/appdev/-/knowledge_base/a/dynamic-query}{Dynamic Query}\nto access Liferay's database. If you want to do something more\ncomplicated like JOINs, you can write your own custom SQL queries. Here,\nyou'll learn how.\n\nThe Guestbook application has two tables, one for guestbooks and one for\nguestbook entries. The entry entity's foreign key to its guestbook is\nthe guestbook's ID. That is, the entry entity table,\n\\texttt{GB\\_GuestbookEntry}, tracks an entry's guestbook by its long\ninteger ID in the table's \\texttt{guestbookId} column. If you want to\nfind a guestbook entry based on its name, message, and guestbook name,\nyou must access the \\emph{name} of the entry's guestbook. Of course,\nwith SQL you can join the entry and guestbook tables to include the\nguestbook name. Service Builder lets you do this by specifying the SQL\nas \\emph{Liferay custom SQL} and invoking it in your service via a\n\\emph{custom finder method}.\n\nUsing Custom SQL in Service Builder is the same as using dynamic\nqueries; it just takes an additional first step to place the SQL you\nwant to run in an XML file. If you plan to use dynamic queries instead,\nskip the rest of this tutorial and move on to the next one.\n\n\\section{Specify Your Custom SQL}\\label{specify-your-custom-sql}\n\nAfter you've tested your SQL, you must specify it in a particular file\nfor Liferay to access it. \\texttt{CustomSQL} class (from module\n\\href{https://repository.liferay.com/nexus/content/repositories/liferay-public-releases/com/liferay/com.liferay.portal.dao.orm.custom.sql.api/}{\\texttt{com.liferay.portal.dao.orm.custom.sql.api}})\nretrieves SQL from a file called \\texttt{default.xml} in your service\nmodule's \\texttt{src/main/resources/META-INF/custom-sql/} folder. You\nmust create the \\texttt{custom-sql} folder and create the\n\\texttt{default.xml} file in that \\texttt{custom-sql} folder. The\n\\texttt{default.xml} file must adhere to the following format:\n\n\\begin{verbatim}\n\n \n SQL query wrapped in \n No terminating semi-colon\n \n\n\\end{verbatim}\n\nCreate a \\texttt{custom-sql} element for every SQL query you want in\nyour application, and give each query a unique ID. The recommended\nconvention to use for the ID value is the fully-qualified class name of\nthe finder followed by a dot (\\texttt{.}) character and the name of the\nfinder method. More detail on the finder class and finder methods is\nprovided in the next step.\n\nFor example, in the Guestbook application, you could use the following\nID value to specify a query:\n\n\\begin{verbatim}\ncom.liferay.docs.guestbook.service.persistence.EntryFinder.findByEntryNameEntryMessageGuestbookName\n\\end{verbatim}\n\nCustom SQL must be wrapped in character data (\\texttt{CDATA}) for the\n\\texttt{sql} element. Importantly, do not terminate the SQL with a\nsemi-colon. Following these rules, the \\texttt{default.xml} file of the\nGuestbook application specifies an SQL query that joins the\n\\texttt{GB\\_GuestbookEntry} and \\texttt{GB\\_Guestbook} tables:\n\n\\begin{verbatim}\n\n\n \n \n \n\n\\end{verbatim}\n\nNow that you've specified some custom SQL, the next step is to implement\na finder method to invoke it. The method name for the finder should\nmatch the ID you just specified for the \\texttt{sql} element.\n\nCongratulations on developing a custom SQL query and custom finder for\nyour application!\n\n\\section{Related Topics}\\label{related-topics-23}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{Customizing\nLiferay Services}\n\n\\chapter{Defining a Custom Finder\nMethod}\\label{defining-a-custom-finder-method}\n\nDynamic queries and custom SQL belong in finder methods. You implement\nthem and then make them available through an interface. This article\ndemonstrates defining the finder method in an implementation class,\ngenerating its interface and tying the implementation to the interface.\n\nAn example of this is a Guestbook application with two entities:\nguestbook and entry. Each entry belongs to a guestbook so the entry\nentity has a \\texttt{guestbookId} field as a foreign key. If you need a\nfinder to search for guestbook entries by entry name and guestbook name,\nyou'd add a finder method to \\texttt{GuestbookFinderImpl} and name it\n\\texttt{findByEntryNameGuestbookName}. The full method signature would\nbe\n\\texttt{findByEntryNameGuestbookName(String\\ entryName,\\ String\\ guestbookName)}.\nThe steps are below.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a \\texttt{{[}Entity{]}FinderImpl} class in the\n \\texttt{{[}package\\ \\ \\ \\ \\ \\ path{]}.service.persistence.impl}\n package of your service module's \\texttt{src/main/java} folder. Recall\n that you specify the \\texttt{{[}package\\ path{]}} in your\n \\texttt{service.xml} file. Here's an example:\n\n\\begin{verbatim}\n\n ...\n\n\\end{verbatim}\n\\item\n Define a \\texttt{findBy*} finder method in the class you created. Make\n sure to add any required arguments to your finder method signature.\n\\item\n Run Service Builder to generate the appropriate interface in the\n \\texttt{{[}package\\ \\ \\ \\ \\ \\ path{]}.service.persistence} package in\n the \\texttt{service} folder of your API and service modules.\n\n For example, after adding\n \\texttt{findByEntryNameGuestbookName(String\\ entryName,\\ String\\ guestbookName)}\n to \\texttt{GuestbookFinderImpl} and running Service Builder, the\n interface\n \\texttt{com.liferay.docs.guestbook.service.persistence.GuestbookFinder}\n is generated.\n\\item\n Make the finder class a component (annotated with\n \\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}})\n that implements the \\texttt{GuestbookFinder} interface. For example,\n the class declaration should look like this:\n\n\\begin{verbatim}\n@Component(service = GuestbookFinder.class)\npublic class GuestbookFinderImpl extends BasePersistenceImpl implements GuestbookFinder\n\\end{verbatim}\n\\end{enumerate}\n\nYour next step is to implement the query in your finder. You can do this\nvia the Dynamic Query API or Custom SQL. The next tutorial covers\nDynamic Query. To simply call custom SQL you have written, create a\nfinder method to run your SQL:\n\n\\begin{verbatim}\npublic List findByEntryNameEntryMessageGuestbookName(\n String entryName, String entryMessage, String guestbookName,\n int begin, int end) {\n\n Session session = null;\n try {\n session = openSession();\n\n String sql = _customSQL.get(\n getClass(),\n FIND_BY_ENTRYNAME_ENTRYMESSAGE_GUESTBOOKNAME);\n\n SQLQuery q = session.createSQLQuery(sql);\n q.setCacheable(false);\n q.addEntity(\"GB_Entry\", EntryImpl.class);\n\n QueryPos qPos = QueryPos.getInstance(q);\n qPos.add(entryName);\n qPos.add(entryMessage);\n qPos.add(guestbookName);\n\n return (List) QueryUtil.list(q, getDialect(), begin, end);\n }\n catch (Exception e) {\n try {\n throw new SystemException(e);\n }\n catch (SystemException se) {\n se.printStackTrace();\n }\n }\n finally {\n closeSession(session);\n }\n\n return null;\n}\n\npublic static final String FIND_BY_ENTRYNAME_ENTRYMESSAGE_GUESTBOOKNAME =\n EntryFinder.class.getName() +\n \".findByEntryNameEntryMessageGuestbookName\";\n\n@Reference\nprivate CustomSQL _customSQL;\n\\end{verbatim}\n\nThe custom finder method opens a new Hibernate session and uses\nLiferay's\n\\texttt{CustomSQL.get(Class\\textless{}?\\textgreater{}\\ clazz,\\ String\\ id)}\nmethod to get the custom SQL to use for the database query. The\n\\texttt{FIND\\_BY\\_ENTRYNAME\\_ENTRYMESSAGE\\_GUESTBOOKNAME} static field\ncontains the custom SQL query's ID. The\n\\texttt{FIND\\_BY\\_EVENTNAME\\_EVENTDESCRIPTON\\_LOCATIONNAME} string is\nbased on the fully-qualified class name of the \\texttt{*Finder}\ninterface (\\texttt{EventFinder}) and the name of the finder method\n(\\texttt{findByEntryNameEntryMessageGuestbookName}).\n\nAwesome! You've implemented your finder class, and if you're using\ncustom SQL, you've even implemented a method to call your finder. If\nyou're using Dynamic Query, the next tutorial shows you how to implement\na dynamic query finder method.\n\n\\chapter{Dynamic Query}\\label{dynamic-query}\n\nOnce you've\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-a-custom-finder-method}{defined\nyour custom finder method}, you can use the Dynamic Query API to\nimplement your query in it. Here's what you must do in your finder\nmethod:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\hyperref[using-a-hibernate-session]{Open a Hibernate Session}\n\\item\n \\hyperref[creating-dynamic-queries]{Create a dynamic query using these\n Hibernate features}:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\emph{Restrictions}: Similar to \\texttt{where} clauses of an SQL\n query, restrictions limit results based on criteria.\n \\item\n \\emph{Projections}: Modify the kind of results the query returns.\n \\item\n \\emph{Orders}: Organize results.\n \\end{itemize}\n\\item\n \\hyperref[executing-the-dynamic-query]{Execute the Dynamic Query and\n return the results}\n\\end{enumerate}\n\nBefore implementing a dynamic query in your own finder method, it can be\nhelpful to examine an example. The following example method uses\nmultiple dynamic queries and all the Hibernate features. Instructions\nfor implementing your own finder method follow the example.\n\n\\section{Example Finder Method:\nfindByGuestbookNameEntryName}\\label{example-finder-method-findbyguestbooknameentryname}\n\nThis finder method for the Guestbook application retrieves a list of\nGuestbook entries that have a specific name and that also belong to a\nGuestbook of a specific name:\n\n\\begin{verbatim}\npublic List findByEntryNameGuestbookName(String entryName, String guestbookName) {\n\n Session session = null;\n try {\n session = openSession();\n\n ClassLoader classLoader = getClass().getClassLoader();\n\n DynamicQuery guestbookQuery = DynamicQueryFactoryUtil.forClass(Guestbook.class, classLoader)\n .add(RestrictionsFactoryUtil.eq(\"name\", guestbookName))\n .setProjection(ProjectionFactoryUtil.property(\"guestbookId\"));\n\n Order order = OrderFactoryUtil.desc(\"modifiedDate\");\n\n DynamicQuery entryQuery = DynamicQueryFactoryUtil.forClass(Entry.class, classLoader))\n .add(RestrictionsFactoryUtil.eq(\"name\", entryName))\n .add(PropertyFactoryUtil.forName(\"guestbookId\").in(guestbookQuery))\n .addOrder(order);\n\n List entries = _entryLocalService.dynamicQuery(entryQuery);\n\n return entries;\n }\n catch (Exception e) {\n try {\n throw new SystemException(e);\n }\n catch (SystemException se) {\n se.printStackTrace();\n }\n }\n finally {\n closeSession(session);\n }\n}\n\\end{verbatim}\n\nThe method first opens a Hibernate session. While the session is open in\nthe \\texttt{try} block, it creates and executes a dynamic query, which\nreturns results (a list of guestbook \\texttt{Entry} objects) if all goes\nwell.\n\nThe finder method has two distinct dynamic queries.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n The first query retrieves a list of guestbook IDs corresponding to\n guestbook names that match the \\texttt{guestbookName} parameter of the\n finder method.\n\\item\n The second query retrieves a list of guestbook entries with entry\n names that match the \\texttt{entryName} parameter and have\n \\texttt{guestbookId} foreign keys belonging to the list returned by\n the first query.\n\\end{enumerate}\n\nHere's the first query:\n\n\\begin{verbatim}\nDynamicQuery guestbookQuery = DynamicQueryFactoryUtil.forClass(Guestbook.class, classLoader))\n .add(RestrictionsFactoryUtil.eq(\"name\", guestbookName))\n .setProjection(ProjectionFactoryUtil.property(\"guestbookId\"));\n\\end{verbatim}\n\nBy default,\n\\texttt{DynamicQueryFactoryUtil.forClass(Guestbook.class,\\ classLoader))}\nreturns a query that retrieves a list of all guestbook entities. Adding\nthe \\texttt{.add(RestrictionsFactoryUtil.eq(\"name\",\\ guestbookName))}\nrestriction limits the results to only those guestbooks whose guestbook\nnames match the \\texttt{guestbookName} parameter. The\n\\texttt{.setProjection(ProjectionFactoryUtil.property(\"guestbookId\"))}\nprojection changes the result set from a list of guestbook entries to a\nlist of guestbook IDs. This is useful since guestbook IDs are much less\nexpensive to retrieve than full guestbook entities, and the entry query\nonly needs the guestbook IDs.\n\nNext appears an order:\n\n\\begin{verbatim}\nOrder order = OrderFactoryUtil.desc(\"modifiedDate\");\n\\end{verbatim}\n\nThis arranges the results list in descending order of the query entity's\n\\texttt{modifiedDate} attribute. Thus the most recently modified\nentities (guestbook entries, in our example) appear first and the least\nrecently modified entities appear last.\n\nHere's the second query:\n\n\\begin{verbatim}\nDynamicQuery entryQuery = DynamicQueryFactoryUtil.forClass(Entry.class, classLoader))\n .add(RestrictionsFactoryUtil.eq(\"name\", entryName))\n .add(PropertyFactoryUtil.forName(\"guestbookId\").in(guestbookQuery))\n .addOrder(order);\n\\end{verbatim}\n\nBy default,\n\\texttt{DynamicQueryFactoryUtil.forClass(Entry.class,\\ classLoader))}\nreturns a list of all guestbook entry entities. The\n\\texttt{.add(RestrictionsFactoryUtil.eq(\"name\",\\ entryName))}\nrestriction limits the results to only those guestbook entries whose\nnames match the finder method's \\texttt{entryName} parameter.\n\\href{https://docs.liferay.com/dxp/portal/7.0-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/PropertyFactoryUtil.html}{\\texttt{PropertyFactoryUtil}}\nis a Liferay utility class whose method\n\\texttt{forName(String\\ propertyName)} returns the specified property.\nThis property can be passed to another Liferay dynamic query. This is\nexactly what happens in the following line of our example:\n\n\\begin{verbatim}\n.add(PropertyFactoryUtil.forName(\"guestbookId\").in(guestbookQuery))\n\\end{verbatim}\n\nHere, the code makes sure that the guestbook IDs (foreign keys) of the\nentry entities in the \\texttt{entityQuery} belong to the list of\nguestbook IDs returned by the \\texttt{guestbookQuery}. Declaring that an\nentity property in one query must belong to the result list of another\nquery is a way to use the dynamic query API to create complex queries,\nsimilar to SQL joins.\n\nLastly, the order defined earlier is applied to the entries returned by\nthe \\texttt{findByEntryNameGuestbookName} finder method:\n\n\\begin{verbatim}\n.addOrder(order);\n\\end{verbatim}\n\nThis orders the list of guestbook entities by the \\texttt{modifiedDate}\nattribute, from most recent to least recent.\n\nLastly, the dynamic query is invoked on the \\texttt{EntryLocalService}\ninstance. It returns a list of \\texttt{Entry} objects which are then\nreturned by the finder method.\n\n\\begin{verbatim}\nList entries = _entryLocalService.dynamicQuery(entryQuery);\n\nreturn entries;\n\\end{verbatim}\n\nIt's time to implement your finder method to use Dynamic Query. Start\nwith opening and managing a Hibernate session.\n\n\\section{Using a Hibernate Session}\\label{using-a-hibernate-session}\n\nYour first step in implementing your custom finder method in your\n\\texttt{*FinderImpl} class is to open a new Hibernate session. Since\nyour \\texttt{*FinderImpl} class extends\n\\texttt{BasePersistenceImpl\\textless{}Entity\\textgreater{}}, and\n\\texttt{BasePersistenceImpl\\textless{}Entity\\textgreater{}} contains a\nsession factory object and an\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/service/persistence/impl/BasePersistenceImpl.html\\#openSession--}{\\texttt{openSession}}\nmethod, you can invoke the \\texttt{openSession} method of your\n\\texttt{*FinderImpl}'s parent class to open a new Hibernate session. The\nstructure of your finder method should look like this:\n\n\\begin{verbatim}\npublic List findBy-(...) {\n\n Session session = null;\n try {\n session = openSession();\n \n /*\n create a dynamic\n query to retrieve and return the desired list of entity\n objects\n */\n }\n catch (Exception e) {\n // Exception handling\n }\n finally {\n closeSession(session);\n }\n\n return null;\n /*\n Return null only if there was an error returning the\n desired list of entity objects in the try block\n */\n\n}\n\\end{verbatim}\n\nNext, in the try block, create your dynamic query objects.\n\n\\section{Creating Dynamic Queries}\\label{creating-dynamic-queries}\n\nIn Liferay, you don't create criteria objects directly from the\nHibernate session. Instead, you create dynamic query objects using\nLiferay's\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/DynamicQueryFactoryUtil.html}{\\texttt{DynamicQueryFactoryUtil}}\nservice. Thus, instead of\n\n\\begin{verbatim}\nCriteria entryCriteria = session.createCriteria(Entry.class);\n\\end{verbatim}\n\nyou use\n\n\\begin{verbatim}\nDynamicQuery entryQuery = DynamicQueryFactoryUtil.forClass(Entry.class, classLoader));\n\\end{verbatim}\n\nIn your finder method, initialize your dynamic query for your entity\nclass.\n\nMost features of Hibernate's Criteria API, including restrictions,\nprojections, and orders, can be used on Liferay dynamic query objects.\nEach criteria can be applied to your query. The restriction criteria\ntype is described first.\n\n\\section{Restriction Criteria}\\label{restriction-criteria}\n\nRestrictions in Hibernate's Criteria API roughly correspond to the\n\\texttt{where} clause of an SQL query: they offer a variety of ways to\nlimit the results returned by the query. You can use restrictions, for\nexample, to cause a query to return only results where a certain field\nhas a particular value, or a value in a certain range, or a non-null\nvalue, etc.\n\nWhen you need to add restrictions to a dynamic query, don't call\nHibernate's \\texttt{Restrictions} class directly. Instead, use the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/RestrictionsFactoryUtil.html}{\\texttt{RestrictionsFactoryUtil}}\nservice. \\texttt{RestrictionsFactoryUtil} has the same methods that\nyou're used to from Hibernate's \\texttt{Restrictions} class:\n\\texttt{in}, \\texttt{between}, \\texttt{like}, \\texttt{eq}, \\texttt{ne},\n\\texttt{gt}, \\texttt{ge}, \\texttt{lt}, \\texttt{le}, etc.\n\nThus, instead of using this call to specify that a guestbook must have a\ncertain name,\n\n\\begin{verbatim}\nentryCriteria.add(Restrictions.eq(\"name\", guestbookName));\n\\end{verbatim}\n\nyou use\n\n\\begin{verbatim}\nentryQuery.add(RestrictionsFactoryUtil.eq(\"name\", guestbookName));\n\\end{verbatim}\n\nThe restriction above limits the results to guestbook entries whose\n\\texttt{name} attribute matches the value of the variable\n\\texttt{guestbookName}. Add the restrictions you need to get the results\nyou want.\n\nProjections are the next criteria type. They let you transform the query\nresults to return the field type you desire.\n\n\\section{Projection Criteria}\\label{projection-criteria}\n\nProjections in Hibernate's Criteria API let you modify the kind of\nresults returned by a query. For example, if you don't want your query\nto return a list of entity objects (the default), you can set a\nprojection on a query to return only a list of the values of a certain\nentity field, or fields. You can also use projections on a query to\nreturn the maximum or minimum value of an entity field, or the sum of\nall the values of a field, or the average, etc. For more information on\nrestrictions and projections, please refer to Hibernate's\n\\href{http://docs.jboss.org/hibernate/orm/3.6/reference/en-US/html/querycriteria.html}{documentation}.\n\nSimilarly, to set projections, create properties via Liferay's\n\\href{https://docs.liferay.com/dxp/portal/7.0-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/PropertyFactoryUtil.html}{PropertyFactoryUtil}\nservice instead of through Hibernate's \\texttt{Property} class. Thus,\ninstead of\n\n\\begin{verbatim}\nentryCriteria.setProjection(Property.forName(\"guestbookId\"));\n\\end{verbatim}\n\nyou use\n\n\\begin{verbatim}\nentryQuery.setProjection(PropertyFactoryUtil.forName(\"guestbookId\"));\n\\end{verbatim}\n\nThe projection above specifies the \\texttt{guestbookId} entity field to\nchanges the result set to a list of those field values. If you want to\nreturn a specific field type from your entities, add a projection for\nit.\n\nThe last criteria type lets you organize results your way.\n\n\\section{Order Criteria}\\label{order-criteria}\n\nOrders in Hibernate's Criteria API let you control the order of the\nelements in the list a query returns. You can choose the property or\nproperties to which an order applies as well as whether they're in\nascending or descending order.\n\nThis code creates an order by the entity's \\texttt{modifiedDate}\nattribute:\n\n\\begin{verbatim}\nOrder order = OrderFactoryUtil.desc(\"modifiedDate\");\n\\end{verbatim}\n\nWhen you apply this order, the results are arranged in descending order\nof the query entity's \\texttt{modifiedDate} attribute. Thus the most\nrecently modified entities (guestbook entries, in our example) appear\nfirst and the least recently modified entities appear last.\n\nLike Hibernate criteria, Liferay's dynamic queries are\n\\emph{chain-able}: you can add criteria to, set projections on, and add\norders to Liferay's dynamic query objects just by appending the\nappropriate method calls to the query object. For example, the following\nsnippet demonstrates chaining a restriction criterion and a projection\nto a dynamic query object declaration:\n\n\\begin{verbatim}\nDynamicQuery guestbookQuery = DynamicQueryFactoryUtil.forClass(Guestbook.class)\n .add(RestrictionsFactoryUtil.eq(\"name\", guestbookName))\n .setProjection(ProjectionFactoryUtil.property(\"guestbookId\"));\n\\end{verbatim}\n\nIt's time to execute your dynamic query.\n\n\\section{Executing the Dynamic Query}\\label{executing-the-dynamic-query}\n\nIn the previous article, you ran Service Builder after\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-a-custom-finder-method}{defining\nyour custom finder}. Service Builder generated a\n\\texttt{dynamicQuery(DynamicQuery\\ dynamicQuery)} method in your\n\\texttt{*LocalServiceBaseImpl} class. Using a \\texttt{*LocalService}\ninstance, invoke \\texttt{dynamicQuery} method, passing it your dynamic\nquery. Here's an example dynamic query execution.\n\n\\begin{verbatim}\nList entities = _someLocalService.dynamicQuery(entityQuery);\n\nreturn entities;\n\\end{verbatim}\n\nThe dynamic query execution returns a list of entities and the finder\nmethod returns that list.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Service Builder not only generates a\n\\texttt{public\\ List\\ \\ dynamicQuery(DynamicQuery\\ dynamicQuery)} method\nin \\texttt{*LocalServiceBaseImpl} but it also generates\n\\texttt{public\\ List\\ dynamicQuery(DynamicQuery\\ dynamicQuery,\\ int\\ \\ start,\\ int\\ end)}\nand\n\\texttt{public\\ List\\ dynamicQuery(DynamicQuery\\ dynamicQuery,\\ int\\ \\ start,\\ int\\ end,\\ OrderByComparator\\ orderByComparator)}\nmethods. You can go back to\n\\href{/docs/7-2/appdev/-/knowledge_base/a/defining-a-custom-finder-method}{defining\ncustom finder methods} and either modify your finder method or create\noverloaded versions of it to take advantage of these extra methods and\ntheir parameters. The \\texttt{int\\ start} and \\texttt{int\\ \\ end}\nparameters are useful when paginating a result list. \\texttt{start} is\nthe lower bound of the range of model entity instances and \\texttt{end}\nis the upper bound. The \\texttt{OrderByComparator\\ orderByComparator} is\nthe comparator by which to order the results.\n\n\\noindent\\hrulefill\n\nTo use the overloaded \\texttt{dynamicQuery} methods of your\n\\texttt{*LocalServiceBaseImpl} class in the (optionally overloaded)\ncustom finders of your \\texttt{*FinderImpl} class, just choose the\nappropriate methods for running the dynamic queries:\n\\texttt{dynamicQuery(entryQuery)}, or\n\\texttt{dynamicQuery(entryQuery,\\ start,\\ end)} or\n\\texttt{dynamicQuery(entryQuery,\\ start,\\ end,\\ orderByComparator)}.\n\nGreat! You've now created a finder method using Liferay's Dynamic Query\nAPI. Your last step is to add a service method that calls your finder.\n\n\\chapter{Accessing Your Custom Finder Method from the Service\nLayer}\\label{accessing-your-custom-finder-method-from-the-service-layer}\n\nSo far, you've created a \\texttt{*FinderImpl} class, defined a\n\\texttt{findBy*} finder method in that class, and implemented the finder\nmethod using Dynamic Query or custom SQL. Now how do you call your\nfinder method from the service layer?\n\nWhen you ran Service Builder (if you haven't run it yet; run it now),\nthe \\texttt{*Finder} interface was generated (e.g.,\n\\texttt{GuestbookFinder}). For proper separation of concerns, only a\nlocal or remote service implementation (i.e., \\texttt{*LocalServiceImpl}\nor \\texttt{*ServiceImpl}) in your service module should invoke the\n\\texttt{*Finder} class. The portlet classes in your application's web\nmodule invoke the business logic of the services published from your\napplication's service module. The services, in turn, access the data\nmodel using the persistence layer's finder classes.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} In previous versions of Liferay DXP, your finder methods\nwere accessible via \\texttt{*FinderUtil} utility classes. Finder methods\nare now injected into your app's local services, removing the need to\ncall finder utilities.\n\n\\noindent\\hrulefill\n\nYou'll add a method in the \\texttt{*LocalServiceImpl} class that invokes\nthe finder method implementation via the \\texttt{*Finder} class. Then\nyou'll rebuild your application's service layer so that the portlet\nclasses and JSPs in your web module can access the services.\n\nFor example, for the Guestbook application, you'd add the following\nmethod to the \\texttt{GuestbookEntryLocalServiceImpl} class:\n\n\\begin{verbatim}\npublic List findByEntryNameGuestbookName(String entryName,\n String guestbookName) throws SystemException {\n\n return entryFinder.findByEntryNameGuestbookName(String entryName,\n String guestbookName);\n}\n\\end{verbatim}\n\nAfter you've added your \\texttt{findBy*} method to your\n\\texttt{*LocalServiceImpl} class, run Service Builder to generate the\ninterface and make the finder method available in the\n\\texttt{EntryLocalService} class.\n\nNow you can indirectly call the finder method from your portlet class or\nfrom a JSP by calling\n\\texttt{\\_entryLocalService.findByEntryNameGuestbookName(...)}!\n\nCongratulations on following the process of developing custom queries in\na custom finder and exposing it as a service for your portlet!\n\n\\section{Related Topics}\\label{related-topics-24}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Service}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{Invoking\nLocal Services}\n\n\\chapter{Actionable Dynamic Queries}\\label{actionable-dynamic-queries}\n\nSuppose you have over a million users, and you want to perform some kind\nof mass update to some of them. One approach might be to use a dynamic\nquery to retrieve the list of users in question. Once loaded into\nmemory, you could loop through the list and update each user. However,\nwith over a million users, the memory cost of such an operation would be\ntoo great. In general, retrieving large numbers of Service Builder\nentities using dynamic queries requires too much memory and time.\n\nLiferay actionable dynamic queries solve this problem. Actionable\ndynamic queries use a pagination strategy to load only small numbers of\nentities into memory at a time and perform processing (i.e., perform an\n\\emph{action}) on each entity. So instead of trying to use a dynamic\nquery to load a million users into memory and then perform some\nprocessing on each of them, a much better strategy is to use an\nactionable dynamic query. This way, you can still process your million\nusers, but only small numbers are loaded into memory at a time.\n\nHere's how to use actionable dynamic query:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Get an\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/ActionableDynamicQuery.html}{\\texttt{ActionableDynamicQuery}}\n from your \\texttt{*LocalService} by invoking its\n \\texttt{getActionableDynamicQuery} method.\n\\item\n Add query criteria and constraints, using the query's\n \\texttt{setAddCriteriaMethod} and \\texttt{setAddOrderCriteriaMethod}\n methods.\n\\item\n Set an action to perform on the matching entities, using\n \\texttt{setPerformActionMethod}.\n\\item\n Execute the action on each matching entity, by invoking the query's\n \\texttt{performActions} method.\n\\end{enumerate}\n\nThis method from a sample portlet creates an actionable dynamic query,\nadds a query restriction and an action, and executes the query:\n\n\\begin{verbatim}\nprotected void massUpdate() {\n ActionableDynamicQuery adq = _barLocalService.getActionableDynamicQuery();\n \n adq.setAddCriteriaMethod(new ActionableDynamicQuery.AddCriteriaMethod() {\n \n @Override\n public void addCriteria(DynamicQuery dynamicQuery) {\n dynamicQuery.add(RestrictionsFactoryUtil.lt(\"field3\", 100));\n }\n \n });\n \n adq.setPerformActionMethod(new ActionableDynamicQuery.PerformActionMethod() {\n \n @Override\n public void performAction(Bar bar) {\n int field3 = bar.getField3();\n field3++;\n bar.setField3(field3);\n _barLocalService.updateBar(bar);\n }\n \n });\n \n try {\n adq.performActions();\n }\n catch (Exception e) {\n e.printStackTrace();\n }\n}\n\\end{verbatim}\n\nThe example method demonstrates executing an actionable dynamic query on\n\\texttt{Bar} entities that match certain criteria.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Retrieve an\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/dao/orm/ActionableDynamicQuery.html}{\\texttt{ActionableDynamicQuery}}\n from local service \\texttt{BarLocalService}.\n\n\\begin{verbatim}\nActionableDynamicQuery adq = _barLocalService.getActionableDynamicQuery();\n\\end{verbatim}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Service Builder generates method `getActionableDynamicQuery()` in\n each entity's `*LocalService` interface and implements it in each entity's\n `*BaseLocalServiceImpl` class.\n \n @Transactional(propagation = Propagation.SUPPORTS, readOnly = true)\n public ActionableDynamicQuery getActionableDynamicQuery();\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{1}\n\\item\n Set query criteria to match \\texttt{field3} values less than\n \\texttt{100}.\n\n\\begin{verbatim}\nadq.setAddCriteriaMethod(new ActionableDynamicQuery.AddCriteriaMethod() {\n\n @Override\n public void addCriteria(DynamicQuery dynamicQuery) {\n dynamicQuery.add(RestrictionsFactoryUtil.lt(\"field3\", 100));\n }\n\n });\n\\end{verbatim}\n\\item\n Set an action to perform. The action increments the matching entity's\n \\texttt{field3} value.\n\n\\begin{verbatim}\nadq.setPerformActionMethod(new ActionableDynamicQuery.PerformActionMethod() {\n\n @Override\n public void performAction(Bar bar) {\n int field3 = bar.getField3();\n field3++;\n bar.setField3(field3);\n _barLocalService.updateBar(bar);\n }\n\n });\n\\end{verbatim}\n\\item\n Execute the action on each matching entity.\n\n\\begin{verbatim}\ntry {\n adq.performActions();\n}\ncatch (Exception e) {\n e.printStackTrace();\n}\n\\end{verbatim}\n\\end{enumerate}\n\nActionable dynamic queries let you act on large numbers of entities in\nsmaller groups. It's an efficient and high performing way to update\nentities.\n\n\\section{Related Topics}\\label{related-topics-25}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/business-logic-with-service-builder}{Creating\nLocal Service}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/invoking-local-services}{Invoking\nLocal Services}\n\n\\chapter{REST Builder}\\label{rest-builder}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} This documentation is in beta. Stay tuned for more to\ncome!\n\n\\noindent\\hrulefill\n\nLiferay DXP's headless REST APIs follow the\n\\href{https://swagger.io/docs/specification/about/}{OpenAPI}\nspecification and let your apps consume RESTful web services. These APIs\nare developed using a mixture of the Contract First and Contract Last\ndevelopment approaches. This presents a best-of-both-worlds approach to\nAPI development. For more detailed information, see\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/headless-rest-apis}{Headless\nREST APIs}.\n\nHere, you'll learn how to use Liferay's\n\\href{https://github.com/liferay/liferay-portal/tree/master/modules/util/portal-tools-rest-builder}{REST\nBuilder tool} to create headless REST APIs for your own apps. REST\nBuilder is an API generator that consumes OpenAPI profiles and generates\nthe API scaffolding: JAX-RS endpoints, parsing, XML generation, and\nadvanced features like filtering or multipart (binary file) support. The\ndeveloper only has to fill in the resource implementations, calling\nLiferay DXP's remote services.\n\nRead on to learn how to generate REST services with REST Builder!\n\n\\chapter{Generating APIs with REST\nBuilder}\\label{generating-apis-with-rest-builder}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} This documentation is in beta. Stay tuned for more to\ncome!\n\n\\noindent\\hrulefill\n\nFollow these steps to use REST Builder to create a headless REST API for\nyour app:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a\n \\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{project}.\n\\item\n Install REST Builder. For instructions on this, see\n \\href{/docs/7-2/reference/-/knowledge_base/r/rest-builder-gradle-plugin}{REST\n Builder Gradle Plugin}.\n\\item\n Run \\texttt{gradlew\\ clean\\ deploy}. Note that your Gradle wrapper may\n not be in your app's project directory, so you may need to use\n \\texttt{..} to locate it (e.g.,\n \\texttt{../../../gradlew\\ clean\\ deploy}).\n\\item\n Create the \\texttt{*-api} and \\texttt{*-impl} projects with the usual\n files (\\texttt{build.gradle}, \\texttt{bnd.bnd}). Also create a\n \\texttt{rest-config.yaml} with the author, paths, and packages. For\n example, here's the \\texttt{rest-config.yaml} for Liferay's\n \\texttt{headless-delivery} API:\n\n\\begin{verbatim}\napiDir: \"../headless-delivery-api/src/main/java\"\napiPackagePath: \"com.liferay.headless.delivery\"\napplication:\n baseURI: \"/headless-delivery\"\n className: \"HeadlessDeliveryApplication\"\n name: \"Liferay.Headless.Delivery\"\nauthor: \"Javier Gamarra\"\nclientDir: \"../headless-delivery-client/src/main/java\"\ntestDir: \"../headless-delivery-test/src/testIntegration/java\"\n\\end{verbatim}\n\\item\n In your \\texttt{*-impl} module's root folder, write your OpenAPI\n profile in YAML. You can use the\n \\href{https://editor.swagger.io/}{Swagger Editor} to validate syntax\n and ensure compliance with the OpenAPI specification.\n\\item\n In your \\texttt{*-impl} module folder, run \\texttt{gradlew\\ buildREST}\n (make sure you locate your Gradle wrapper as instructed in step two\n above).\n\\item\n REST Builder generates the interfaces with the JAX-RS endpoints. It\n also generates a \\texttt{*ResourceImpl} class where you must implement\n the business logic for each service.\n\\item\n After implementing the business logic for each service, deploy your\n modules. Your APIs are then available at this URL:\n\n\\begin{verbatim}\nhttp://[host]:[port]/o/[APPLICATION_CLASSNAME]/[OPEN_API_VERSION]/\n\\end{verbatim}\n\n You can also execute \\texttt{jaxrs:check} in the OSGi console to see\n all the JAX-RS endpoints.\n\\end{enumerate}\n\n\\section{Related Topics}\\label{related-topics-26}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/rest-builder}{REST Builder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/headless-rest-apis}{Headless\nREST APIs}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/rest-builder-gradle-plugin}{REST\nBuilder Gradle Plugin}\n\n\\chapter{Troubleshooting Application Development\nIssues}\\label{troubleshooting-application-development-issues}\n\nWhen coding on any platform, you can sometimes run into issues that have\nno clear resolution. This can be particularly frustrating. If you have\nissues building, deploying, or running apps and modules, you want to\nresolve them fast. These frequently asked questions and answers help you\ntroubleshoot and correct problems.\n\nHere are the troubleshooting sections:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[modules]{Modules}\n\\item\n \\hyperref[services-and-components]{Services and Components}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/troubleshooting-front-end-development-issues}{Front-end}\n\\end{itemize}\n\nClick a question to view the answer.\n\n\\section{Modules}\\label{modules}\n\n{How can I configure dependencies on Liferay artifacts?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n{What are optional package imports and how can I specify them?~{}}\n\n\\begin{verbatim}\n
When developing modules, you can declare optional package imports. An optional package import is one your module can use if it's available, but can still function without it. Specifying optional package imports is straightforward.
\n\\end{verbatim}\n\n{How can I connect to a JNDI data source from my module?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n{An IllegalContextNameException reports that my bundle's context name\ndoes not follow Bundle-SymbolicName syntax. How can I fix the context\nname?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n{After creating a relational mapping between Service Builder entities,\nmy portlet is using too much memory. What can I do?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n\\section{Services and Components}\\label{services-and-components}\n\n{How can I see what's happening in the OSGi container?~{}}\n\n\\begin{verbatim}\n
A known bug with Angular causes absolute URLs for CSS files not to be recognized.
\n
Due to the nature of portals, a relative URL is not an option either because the app can be placed on any page.
\n
To fix this, you can either provide the CSS with a theme or themelet, or you can specify the path to the CSS file with the com.liferay.portlet.header-portlet-css property in the portlet containing your Angular code.
\n\\end{verbatim}\n\n\\phantomsection\\label{portal-css-broken-ie}\n{Why is Liferay Portal's CSS broken in Internet Explorer?~{}}\n\n\\begin{verbatim}\n
By default CSS files are minified in the browser. This can cause issues in Internet Explorer. You can disable this behavior by including theme.css.fast.load=false and minifier.enabled=false in your portal-ext.properties file.
\n\\end{verbatim}\n\n\\section{Modules}\\label{modules-1}\n\n\\phantomsection\\label{jquery-anonymous-module-error}\n{Why does my JQuery module throw an anonymous module error when I try to\nload it?~{}}\n\n\\begin{verbatim}\n
If you're using an external library that you host, you must disable the Expose Global option as described in the Using External JavaScript Libraries tutorial.
\n\\end{verbatim}\n\n\\phantomsection\\label{source-maps-not-showing}\n{Why are my source maps not showing for my Angular or Typescript\nmodule?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n\\phantomsection\\label{disable-bundler-analytics}\n{I'm using the liferay-npm-bundler for multiple projects. How can I\ndisable analytics tracking for the liferay-npm-bundler in my\nprojects?~{}}\n\n\\begin{verbatim}\n
There are a couple options you can use to disable reporting:
\n
\n
Use the --no-tracking flag in your package.json's build script to disable reporting:
\n
liferay-npm-bundler --no-tracking
\n \n
\n
Create a .liferay-npm-bundler-no-tracking file in your project's root folder, or any of its ancestors, to disable reporting.
\n
This equates to answering No to the May liferay-npm-bundler anonymously report usage statistics to improve the tool over time? question.
\n
\n\n\\end{verbatim}\n\n\\section{Portlets}\\label{portlets}\n\n\\phantomsection\\label{angular-react-vue-portlet-disable-spa}\n{I want to use a custom router in my Angular/React/Vue portlet. How can\nI disable the default Senna JS SPA engine in my portlet?~{}}\n\n\\begin{verbatim}\n
By default, the Senna JS SPA engine is enabled in your portlets and sites. This disables full page reloads during portlet navigation.
\n\\end{verbatim}\n"
},
{
"path": "book/developer/customization.aux",
"content": "\\relax \n\\providecommand{\\transparent@use}[1]{}\n\\providecommand\\hyper@newdestlabel[2]{}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {150}Liferay Customization}{399}{chapter.150}\\protected@file@percent }\n\\newlabel{liferay-customization}{{150}{399}{Liferay Customization}{chapter.150}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {151}Fundamentals}{401}{chapter.151}\\protected@file@percent }\n\\newlabel{fundamentals}{{151}{401}{Fundamentals}{chapter.151}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {152}Configuring Dependencies}{403}{chapter.152}\\protected@file@percent }\n\\newlabel{configuring-dependencies}{{152}{403}{Configuring Dependencies}{chapter.152}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {153}Finding Artifacts}{405}{chapter.153}\\protected@file@percent }\n\\newlabel{finding-artifacts}{{153}{405}{Finding Artifacts}{chapter.153}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.1}Finding Core Artifact Attributes}{405}{section.153.1}\\protected@file@percent }\n\\newlabel{finding-core-artifact-attributes}{{153.1}{405}{Finding Core Artifact Attributes}{section.153.1}{}}\n\\gdef \\LT@ii {\\LT@entry \n {1}{105.70474pt}\\LT@entry \n {1}{134.6858pt}\\LT@entry \n {1}{81.00111pt}\\LT@entry \n {1}{88.6722pt}\\LT@entry \n {1}{59.69113pt}}\n\\gdef \\LT@iii {\\LT@entry \n {1}{177.65813pt}\\LT@entry \n {1}{292.09688pt}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.2}Finding Liferay App and Independent Artifacts}{407}{section.153.2}\\protected@file@percent }\n\\newlabel{finding-liferay-app-and-independent-artifacts}{{153.2}{407}{Finding Liferay App and Independent Artifacts}{section.153.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.3}App Manager}{407}{section.153.3}\\protected@file@percent }\n\\newlabel{app-manager}{{153.3}{407}{App Manager}{section.153.3}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {153.1}{\\ignorespaces You can inspect deployed module artifact IDs and version numbers.}}{408}{figure.153.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {153.2}{\\ignorespaces The App Manager aggregates Liferay and independent modules.}}{408}{figure.153.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.4}Reference Docs}{408}{section.153.4}\\protected@file@percent }\n\\newlabel{reference-docs}{{153.4}{408}{Reference Docs}{section.153.4}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {153.3}{\\ignorespaces Results from this Gogo command show that the module's number is \\texttt {1173}.}}{409}{figure.153.3}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {153.4}{\\ignorespaces Results from running the \\texttt {headers} command show the module's bundle vendor and bundle version.}}{409}{figure.153.4}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {153.5}{\\ignorespaces Liferay DXP app Javadoc overviews list each app module's display name, followed by its group ID, artifact ID, and version number in a colon-separated string. It's a Gradle artifact syntax.}}{410}{figure.153.5}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.5}Maven Central}{410}{section.153.5}\\protected@file@percent }\n\\newlabel{maven-central}{{153.5}{410}{Maven Central}{section.153.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {153.6}Related Topics}{411}{section.153.6}\\protected@file@percent }\n\\newlabel{related-topics}{{153.6}{411}{Related Topics}{section.153.6}{}}\n\\gdef \\LT@iv {\\LT@entry \n {1}{62.14067pt}\\LT@entry \n {1}{56.93881pt}\\LT@entry \n {1}{63.67303pt}\\LT@entry \n {1}{43.04385pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {154}Specifying Dependencies}{413}{chapter.154}\\protected@file@percent }\n\\newlabel{specifying-dependencies}{{154}{413}{Specifying Dependencies}{chapter.154}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {154.1}Related Topics}{414}{section.154.1}\\protected@file@percent }\n\\newlabel{related-topics-1}{{154.1}{414}{Related Topics}{section.154.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {155}Resolving Third Party Library Package Dependencies}{415}{chapter.155}\\protected@file@percent }\n\\newlabel{resolving-third-party-library-package-dependencies}{{155}{415}{Resolving Third Party Library Package Dependencies}{chapter.155}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {155.1}Library Package Resolution Workflow}{416}{section.155.1}\\protected@file@percent }\n\\newlabel{library-package-resolution-workflow}{{155.1}{416}{Library Package Resolution Workflow}{section.155.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {155.2}Embedding Libraries in a Project}{417}{section.155.2}\\protected@file@percent }\n\\newlabel{embedding-libraries-in-a-project}{{155.2}{417}{Embedding Libraries in a Project}{section.155.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {155.3}Embedding Libraries Using Gradle}{417}{section.155.3}\\protected@file@percent }\n\\newlabel{embedding-libraries-using-gradle}{{155.3}{417}{Embedding Libraries Using Gradle}{section.155.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {155.4}Embedding a Library Using Maven}{417}{section.155.4}\\protected@file@percent }\n\\newlabel{embedding-a-library-using-maven}{{155.4}{417}{Embedding a Library Using Maven}{section.155.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {155.5}Related Topics}{418}{section.155.5}\\protected@file@percent }\n\\newlabel{related-topics-2}{{155.5}{418}{Related Topics}{section.155.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {156}Understanding Excluded JARs}{419}{chapter.156}\\protected@file@percent }\n\\newlabel{understanding-excluded-jars}{{156}{419}{Understanding Excluded JARs}{chapter.156}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {156.1}Related Topics}{420}{section.156.1}\\protected@file@percent }\n\\newlabel{related-topics-3}{{156.1}{420}{Related Topics}{section.156.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {157}Using the Felix Gogo Shell}{421}{chapter.157}\\protected@file@percent }\n\\newlabel{using-the-felix-gogo-shell}{{157}{421}{Using the Felix Gogo Shell}{chapter.157}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {158}Importing Packages}{423}{chapter.158}\\protected@file@percent }\n\\newlabel{importing-packages}{{158}{423}{Importing Packages}{chapter.158}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {158.1}Automatic Package Import Generation}{423}{section.158.1}\\protected@file@percent }\n\\newlabel{automatic-package-import-generation}{{158.1}{423}{Automatic Package Import Generation}{section.158.1}{}}\n\\gdef \\LT@v {\\LT@entry \n {1}{130.8321pt}\\LT@entry \n {1}{338.9229pt}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {158.2}Manually Adding Package Imports}{425}{section.158.2}\\protected@file@percent }\n\\newlabel{manually-adding-package-imports}{{158.2}{425}{Manually Adding Package Imports}{section.158.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {158.3}Related Topics}{426}{section.158.3}\\protected@file@percent }\n\\newlabel{related-topics-4}{{158.3}{426}{Related Topics}{section.158.3}{}}\n\\gdef \\LT@vi {\\LT@entry \n {3}{149.19315pt}\\LT@entry \n {3}{211.04694pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {159}Exporting Packages}{427}{chapter.159}\\protected@file@percent }\n\\newlabel{exporting-packages}{{159}{427}{Exporting Packages}{chapter.159}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {159.1}Related Topics}{428}{section.159.1}\\protected@file@percent }\n\\newlabel{related-topics-5}{{159.1}{428}{Related Topics}{section.159.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {160}Semantic Versioning}{429}{chapter.160}\\protected@file@percent }\n\\newlabel{semantic-versioning}{{160}{429}{Semantic Versioning}{chapter.160}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {160.1}Baselining Your Project}{429}{section.160.1}\\protected@file@percent }\n\\newlabel{baselining-your-project}{{160.1}{429}{Baselining Your Project}{section.160.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {160.2}Managing Artifact and Dependency Versions}{430}{section.160.2}\\protected@file@percent }\n\\newlabel{managing-artifact-and-dependency-versions}{{160.2}{430}{Managing Artifact and Dependency Versions}{section.160.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {160.3}Related Topics}{431}{section.160.3}\\protected@file@percent }\n\\newlabel{related-topics-6}{{160.3}{431}{Related Topics}{section.160.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {161}Deploying WARs (WAB Generator)}{433}{chapter.161}\\protected@file@percent }\n\\newlabel{deploying-wars-wab-generator}{{161}{433}{Deploying WARs (WAB Generator)}{chapter.161}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {161.1}WAR versus WAB Structure}{434}{section.161.1}\\protected@file@percent }\n\\newlabel{war-versus-wab-structure}{{161.1}{434}{WAR versus WAB Structure}{section.161.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {161.2}Deploying a WAR}{435}{section.161.2}\\protected@file@percent }\n\\newlabel{deploying-a-war}{{161.2}{435}{Deploying a WAR}{section.161.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {161.3}Saving a Copy of the WAB}{435}{section.161.3}\\protected@file@percent }\n\\newlabel{saving-a-copy-of-the-wab}{{161.3}{435}{Saving a Copy of the WAB}{section.161.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {161.4}Related Topics}{435}{section.161.4}\\protected@file@percent }\n\\newlabel{related-topics-7}{{161.4}{435}{Related Topics}{section.161.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {162}Architecture}{437}{chapter.162}\\protected@file@percent }\n\\newlabel{architecture}{{162}{437}{Architecture}{chapter.162}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {162.1}Core}{437}{section.162.1}\\protected@file@percent }\n\\newlabel{core}{{162.1}{437}{Core}{section.162.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {162.1}{\\ignorespaces Liferay DXP portals and Sites contain content and widgets. Liferay DXP can also be used ``headless''---without the UI.}}{438}{figure.162.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {162.2}{\\ignorespaces The Core provides a runtime environment for components, such as the ones here. New component implementations can extend or replace existing implementations dynamically.}}{439}{figure.162.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {162.2}Services}{439}{section.162.2}\\protected@file@percent }\n\\newlabel{services}{{162.2}{439}{Services}{section.162.2}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {162.3}{\\ignorespaces Remote and Liferay DXP applications can invoke services via REST web APIs. Liferay DXP Java-based portlets can also invoke services via Java APIs.}}{440}{figure.162.3}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {162.3}UI}{440}{section.162.3}\\protected@file@percent }\n\\newlabel{ui}{{162.3}{440}{UI}{section.162.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {163}Liferay Portal Classloader Hierarchy}{443}{chapter.163}\\protected@file@percent }\n\\newlabel{liferay-portal-classloader-hierarchy}{{163}{443}{Liferay Portal Classloader Hierarchy}{chapter.163}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {163.1}{\\ignorespaces 0: Here is Liferay's classloader hierarchy.}}{444}{figure.163.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {163.1}Web Application Classloading Perspective}{445}{section.163.1}\\protected@file@percent }\n\\newlabel{web-application-classloading-perspective}{{163.1}{445}{Web Application Classloading Perspective}{section.163.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {163.2}Other Classloading Perspectives}{445}{section.163.2}\\protected@file@percent }\n\\newlabel{other-classloading-perspectives}{{163.2}{445}{Other Classloading Perspectives}{section.163.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {163.3}Related Topics}{445}{section.163.3}\\protected@file@percent }\n\\newlabel{related-topics-8}{{163.3}{445}{Related Topics}{section.163.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {164}Liferay DXP Startup Phases}{447}{chapter.164}\\protected@file@percent }\n\\newlabel{liferay-dxp-startup-phases}{{164}{447}{Liferay DXP Startup Phases}{chapter.164}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.1}Portal Context Initialization Phase}{447}{section.164.1}\\protected@file@percent }\n\\newlabel{portal-context-initialization-phase}{{164.1}{447}{Portal Context Initialization Phase}{section.164.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.2}Main Servlet Initialization Phase}{448}{section.164.2}\\protected@file@percent }\n\\newlabel{main-servlet-initialization-phase}{{164.2}{448}{Main Servlet Initialization Phase}{section.164.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.3}Acting on Events}{448}{section.164.3}\\protected@file@percent }\n\\newlabel{acting-on-events}{{164.3}{448}{Acting on Events}{section.164.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.4}ModuleServiceLifecycle Events}{448}{section.164.4}\\protected@file@percent }\n\\newlabel{moduleservicelifecycle-events}{{164.4}{448}{ModuleServiceLifecycle Events}{section.164.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.5}Portal Startup Events}{448}{section.164.5}\\protected@file@percent }\n\\newlabel{portal-startup-events}{{164.5}{448}{Portal Startup Events}{section.164.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {164.6}Related Topics}{449}{section.164.6}\\protected@file@percent }\n\\newlabel{related-topics-9}{{164.6}{449}{Related Topics}{section.164.6}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {165}The Benefits of Modularity}{451}{chapter.165}\\protected@file@percent }\n\\newlabel{the-benefits-of-modularity}{{165}{451}{The Benefits of Modularity}{chapter.165}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {165.1}{\\ignorespaces The Apollo spacecraft's modules collectively took astronauts to the moon's surface and back to Earth.}}{451}{figure.165.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.1}Modularity Benefits for Software}{452}{section.165.1}\\protected@file@percent }\n\\newlabel{modularity-benefits-for-software}{{165.1}{452}{Modularity Benefits for Software}{section.165.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.2}Distinct Functionality}{452}{section.165.2}\\protected@file@percent }\n\\newlabel{distinct-functionality}{{165.2}{452}{Distinct Functionality}{section.165.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.3}Encapsulation}{452}{section.165.3}\\protected@file@percent }\n\\newlabel{encapsulation}{{165.3}{452}{Encapsulation}{section.165.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.4}Dependencies}{453}{section.165.4}\\protected@file@percent }\n\\newlabel{dependencies}{{165.4}{453}{Dependencies}{section.165.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.5}Reusability}{453}{section.165.5}\\protected@file@percent }\n\\newlabel{reusability}{{165.5}{453}{Reusability}{section.165.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {165.6}Example: Designing a Modular Application}{453}{section.165.6}\\protected@file@percent }\n\\newlabel{example-designing-a-modular-application}{{165.6}{453}{Example: Designing a Modular Application}{section.165.6}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {165.2}{\\ignorespaces The speech recognition application can be implemented in a single monolithic code base or in modules, each focused on a particular function.}}{454}{figure.165.2}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {165.3}{\\ignorespaces The \\emph {Instruction manager} and \\emph {Computer voice} modules designed for the speech recognition app can be used (or \\emph {reused}) by a navigation app.}}{454}{figure.165.3}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {166}OSGi and Modularity}{455}{chapter.166}\\protected@file@percent }\n\\newlabel{osgi-and-modularity}{{166}{455}{OSGi and Modularity}{chapter.166}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.1}Modules}{455}{section.166.1}\\protected@file@percent }\n\\newlabel{modules}{{166.1}{455}{Modules}{section.166.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.2}API}{456}{section.166.2}\\protected@file@percent }\n\\newlabel{api}{{166.2}{456}{API}{section.166.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.3}Provider}{457}{section.166.3}\\protected@file@percent }\n\\newlabel{provider}{{166.3}{457}{Provider}{section.166.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.4}Consumer}{458}{section.166.4}\\protected@file@percent }\n\\newlabel{consumer}{{166.4}{458}{Consumer}{section.166.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.5}A Typical Liferay Application}{460}{section.166.5}\\protected@file@percent }\n\\newlabel{a-typical-liferay-application}{{166.5}{460}{A Typical Liferay Application}{section.166.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {166.6}Related Topics}{460}{section.166.6}\\protected@file@percent }\n\\newlabel{related-topics-10}{{166.6}{460}{Related Topics}{section.166.6}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {167}Module Lifecycle}{461}{chapter.167}\\protected@file@percent }\n\\newlabel{module-lifecycle}{{167}{461}{Module Lifecycle}{chapter.167}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {167.1}{\\ignorespaces This state diagram illustrates the module lifecycle.}}{462}{figure.167.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {167.1}Related Topics}{463}{section.167.1}\\protected@file@percent }\n\\newlabel{related-topics-11}{{167.1}{463}{Related Topics}{section.167.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {168}UI Architecture}{465}{chapter.168}\\protected@file@percent }\n\\newlabel{ui-architecture}{{168}{465}{UI Architecture}{chapter.168}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {168.1}Content}{465}{section.168.1}\\protected@file@percent }\n\\newlabel{content}{{168.1}{465}{Content}{section.168.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {168.2}Applications}{465}{section.168.2}\\protected@file@percent }\n\\newlabel{applications}{{168.2}{465}{Applications}{section.168.2}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {168.1}{\\ignorespaces Widget pages offer users functionality. Widgets are organized into a page template's rows and columns. This template has two columns: a smaller left column and larger right column. On this page, users select tags in the Tag Cloud widget and the matching tagged images show the Asset Publisher widget.}}{466}{figure.168.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {168.3}Themes}{466}{section.168.3}\\protected@file@percent }\n\\newlabel{themes}{{168.3}{466}{Themes}{section.168.3}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {168.2}{\\ignorespaces You can select an attractive theme and apply it to your site.}}{467}{figure.168.2}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {168.3}{\\ignorespaces You can provide custom styling using the theme's \\texttt {\\_custom.sccs} file.}}{468}{figure.168.3}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {168.4}Product Navigation Sidebars and Panels}{469}{section.168.4}\\protected@file@percent }\n\\newlabel{product-navigation\\noindent -and-panels}{{168.4}{469}{Product Navigation Sidebars and Panels}{section.168.4}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {168.4}{\\ignorespaces Liferay facilitates integrating custom administrative functionality through navigation menus and administrative applications.}}{469}{figure.168.4}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {169}Theme Components}{471}{chapter.169}\\protected@file@percent }\n\\newlabel{theme-components}{{169}{471}{Theme Components}{chapter.169}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {169.1}Theme Templates and Utilities}{471}{section.169.1}\\protected@file@percent }\n\\newlabel{theme-templates-and-utilities}{{169.1}{471}{Theme Templates and Utilities}{section.169.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {169.1}{\\ignorespaces The collapsed navbar provides simplified user-friendly navigation for mobile devices.}}{472}{figure.169.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {169.2}{\\ignorespaces Each theme template provides a portion of the page's markup and functionality.}}{472}{figure.169.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {169.2}CSS Frameworks and Extensions}{473}{section.169.2}\\protected@file@percent }\n\\newlabel{css-frameworks-and-extensions}{{169.2}{473}{CSS Frameworks and Extensions}{section.169.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {169.3}Theme Customizations and Extensions}{473}{section.169.3}\\protected@file@percent }\n\\newlabel{theme-customizations-and-extensions}{{169.3}{473}{Theme Customizations and Extensions}{section.169.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {169.4}Portlet Customizations and Extensions}{473}{section.169.4}\\protected@file@percent }\n\\newlabel{portlet-customizations-and-extensions}{{169.4}{473}{Portlet Customizations and Extensions}{section.169.4}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {169.3}{\\ignorespaces There are several extension points for customizing portlets}}{474}{figure.169.3}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {169.5}Related Topics}{474}{section.169.5}\\protected@file@percent }\n\\newlabel{related-topics-12}{{169.5}{474}{Related Topics}{section.169.5}{}}\n\\gdef \\LT@vii {\\LT@entry \n {1}{154.56912pt}\\LT@entry \n {1}{160.56912pt}\\LT@entry \n {1}{154.56912pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {170}Understanding the Page Structure}{475}{chapter.170}\\protected@file@percent }\n\\newlabel{understanding-the-page-structure}{{170}{475}{Understanding the Page Structure}{chapter.170}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {170.1}Portlets or Fragments}{475}{section.170.1}\\protected@file@percent }\n\\newlabel{portlets-or-fragments}{{170.1}{475}{Portlets or Fragments}{section.170.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.1}{\\ignorespaces The page layout is broken into three key sections.}}{476}{figure.170.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {170.2}Layout Templates, Page Templates, and Site Templates}{476}{section.170.2}\\protected@file@percent }\n\\newlabel{layout-templates-page-templates-and-site-templates}{{170.2}{476}{Layout Templates, Page Templates, and Site Templates}{section.170.2}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.2}{\\ignorespaces Each section of the page has elements and IDs that you can target for styling.}}{477}{figure.170.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {170.3}Product Navigation Sidebars and Panels}{478}{section.170.3}\\protected@file@percent }\n\\newlabel{product-navigation-sidebars-and-panels-1}{{170.3}{478}{Product Navigation Sidebars and Panels}{section.170.3}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.3}{\\ignorespaces Remember to account for the product navigation sidebars and panels when styling your site.}}{478}{figure.170.3}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.4}{\\ignorespaces The Add Menu pushes the main contents to the left.}}{479}{figure.170.4}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.5}{\\ignorespaces The Product Menu pushes the main contents to the right.}}{479}{figure.170.5}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {170.6}{\\ignorespaces The Simulation Panel pushes the main contents to the left.}}{480}{figure.170.6}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {170.4}Related Topics}{480}{section.170.4}\\protected@file@percent }\n\\newlabel{related-topics-13}{{170.4}{480}{Related Topics}{section.170.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {171}Bundle Classloading Flow}{481}{chapter.171}\\protected@file@percent }\n\\newlabel{bundle-classloading-flow}{{171}{481}{Bundle Classloading Flow}{chapter.171}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {171.1}{\\ignorespaces This flow chart illustrates classloading in a bundle.}}{482}{figure.171.1}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {172}Finding Extension Points}{483}{chapter.172}\\protected@file@percent }\n\\newlabel{finding-extension-points}{{172}{483}{Finding Extension Points}{chapter.172}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {172.1}Locate the Related Module and Component}{483}{section.172.1}\\protected@file@percent }\n\\newlabel{locate-the-related-module-and-component}{{172.1}{483}{Locate the Related Module and Component}{section.172.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {172.1}{\\ignorespaces The module name can be found using the App Manager.}}{484}{figure.172.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {172.2}Finding Extension Points in a Component}{484}{section.172.2}\\protected@file@percent }\n\\newlabel{finding-extension-points-in-a-component}{{172.2}{484}{Finding Extension Points in a Component}{section.172.2}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {172.2}{\\ignorespaces The component name can be found using the App Manager.}}{485}{figure.172.2}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {173}Troubleshooting Customizations}{487}{chapter.173}\\protected@file@percent }\n\\newlabel{troubleshooting-customizations}{{173}{487}{Troubleshooting Customizations}{chapter.173}{}}\n\\newlabel{cacheable-web-content-taglibs}{{173}{487}{Troubleshooting Customizations}{section*.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {174}Why doesn't the package I use from the fragment host resolve?}{489}{chapter.174}\\protected@file@percent }\n\\newlabel{why-doesnt-the-package-i-use-from-the-fragment-host-resolve}{{174}{489}{Why doesn't the package I use from the fragment host resolve?}{chapter.174}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {175}Why Aren't JSP overrides I Made Using Fragments Showing?}{491}{chapter.175}\\protected@file@percent }\n\\newlabel{why-arent-jsp-overrides-i-made-using-fragments-showing}{{175}{491}{Why Aren't JSP overrides I Made Using Fragments Showing?}{chapter.175}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {175.1}Related Topics}{491}{section.175.1}\\protected@file@percent }\n\\newlabel{related-topics-14}{{175.1}{491}{Related Topics}{section.175.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {176}Using OSGi Services from EXT Plugins}{493}{chapter.176}\\protected@file@percent }\n\\newlabel{using-osgi-services-from-ext-plugins}{{176}{493}{Using OSGi Services from EXT Plugins}{chapter.176}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {176.1}Related Topics}{493}{section.176.1}\\protected@file@percent }\n\\newlabel{related-topics-15}{{176.1}{493}{Related Topics}{section.176.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {177}Contributing to Liferay Portal}{495}{chapter.177}\\protected@file@percent }\n\\newlabel{contributing-to-liferay-portal}{{177}{495}{Contributing to Liferay Portal}{chapter.177}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {177.1}Building Liferay Portal from source}{495}{section.177.1}\\protected@file@percent }\n\\newlabel{building-liferay-portal-from-source}{{177.1}{495}{Building Liferay Portal from source}{section.177.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {177.2}Tooling}{495}{section.177.2}\\protected@file@percent }\n\\newlabel{tooling}{{177.2}{495}{Tooling}{section.177.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {177.3}Additional Resources}{496}{section.177.3}\\protected@file@percent }\n\\newlabel{additional-resources}{{177.3}{496}{Additional Resources}{section.177.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {178}Model Listeners}{497}{chapter.178}\\protected@file@percent }\n\\newlabel{model-listeners}{{178}{497}{Model Listeners}{chapter.178}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {178.1}Creating a Model Listener Class}{498}{section.178.1}\\protected@file@percent }\n\\newlabel{creating-a-model-listener-class}{{178.1}{498}{Creating a Model Listener Class}{section.178.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {178.2}Register the Model Listener Service}{498}{section.178.2}\\protected@file@percent }\n\\newlabel{register-the-model-listener-service}{{178.2}{498}{Register the Model Listener Service}{section.178.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {178.3}Listening For Persistence Events}{498}{section.178.3}\\protected@file@percent }\n\\newlabel{listening-for-persistence-events}{{178.3}{498}{Listening For Persistence Events}{section.178.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {178.4}Related Topics}{499}{section.178.4}\\protected@file@percent }\n\\newlabel{related-topics-16}{{178.4}{499}{Related Topics}{section.178.4}{}}\n\\gdef \\LT@viii {\\LT@entry \n {1}{133.35468pt}\\LT@entry \n {1}{171.17975pt}\\LT@entry \n {1}{165.17975pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {179}Customizing JSPs}{501}{chapter.179}\\protected@file@percent }\n\\newlabel{customizing-jsps}{{179}{501}{Customizing JSPs}{chapter.179}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {179.1}Using Liferay DXP's API to Override a JSP}{501}{section.179.1}\\protected@file@percent }\n\\newlabel{using-liferay-dxps-api-to-override-a-jsp}{{179.1}{501}{Using Liferay DXP's API to Override a JSP}{section.179.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {179.2}Overriding a JSP Without Using Liferay DXP's API}{501}{section.179.2}\\protected@file@percent }\n\\newlabel{overriding-a-jsp-without-using-liferay-dxps-api}{{179.2}{501}{Overriding a JSP Without Using Liferay DXP's API}{section.179.2}{}}\n\\gdef \\LT@ix {\\LT@entry \n {1}{133.35468pt}\\LT@entry \n {1}{171.17975pt}\\LT@entry \n {1}{165.17975pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {180}Customizing JSPs with Dynamic Includes}{503}{chapter.180}\\protected@file@percent }\n\\newlabel{customizing-jsps-with-dynamic-includes}{{180}{503}{Customizing JSPs with Dynamic Includes}{chapter.180}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {181}JSP Overrides Using Portlet Filters}{507}{chapter.181}\\protected@file@percent }\n\\newlabel{jsp-overrides-using-portlet-filters}{{181}{507}{JSP Overrides Using Portlet Filters}{chapter.181}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {182}JSP Overrides Using OSGi Fragments}{511}{chapter.182}\\protected@file@percent }\n\\newlabel{jsp-overrides-using-osgi-fragments}{{182}{511}{JSP Overrides Using OSGi Fragments}{chapter.182}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {182.1}Declaring a Fragment Host}{511}{section.182.1}\\protected@file@percent }\n\\newlabel{declaring-a-fragment-host}{{182.1}{511}{Declaring a Fragment Host}{section.182.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {182.2}Provide the Overridden JSP}{512}{section.182.2}\\protected@file@percent }\n\\newlabel{provide-the-overridden-jsp}{{182.2}{512}{Provide the Overridden JSP}{section.182.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {182.3}Using Fragment Host Internal Packages}{513}{section.182.3}\\protected@file@percent }\n\\newlabel{using-fragment-host-internal-packages}{{182.3}{513}{Using Fragment Host Internal Packages}{section.182.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {182.4}Related Topics}{514}{section.182.4}\\protected@file@percent }\n\\newlabel{related-topics-17}{{182.4}{514}{Related Topics}{section.182.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {183}JSP Overrides Using Custom JSP Bag}{515}{chapter.183}\\protected@file@percent }\n\\newlabel{jsp-overrides-using-custom-jsp-bag}{{183}{515}{JSP Overrides Using Custom JSP Bag}{chapter.183}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {183.1}Providing a Custom JSP}{515}{section.183.1}\\protected@file@percent }\n\\newlabel{providing-a-custom-jsp}{{183.1}{515}{Providing a Custom JSP}{section.183.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {183.2}Implement a Custom JSP Bag}{516}{section.183.2}\\protected@file@percent }\n\\newlabel{implement-a-custom-jsp-bag}{{183.2}{516}{Implement a Custom JSP Bag}{section.183.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {183.3}Extend a JSP}{518}{section.183.3}\\protected@file@percent }\n\\newlabel{extend-a-jsp}{{183.3}{518}{Extend a JSP}{section.183.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {183.4}Site Scoped JSP Customization}{518}{section.183.4}\\protected@file@percent }\n\\newlabel{site-scoped-jsp-customization}{{183.4}{518}{Site Scoped JSP Customization}{section.183.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {183.5}Related Topics}{518}{section.183.5}\\protected@file@percent }\n\\newlabel{related-topics-18}{{183.5}{518}{Related Topics}{section.183.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {184}Overriding Inline Content Using JSPs}{519}{chapter.184}\\protected@file@percent }\n\\newlabel{overriding-inline-content-using-jsps}{{184}{519}{Overriding Inline Content Using JSPs}{chapter.184}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {184.1}Example: Overriding the fieldset Taglib Tag}{520}{section.184.1}\\protected@file@percent }\n\\newlabel{example-overriding-the-fieldset-taglib-tag}{{184.1}{520}{Example: Overriding the fieldset Taglib Tag}{section.184.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {184.1}{\\ignorespaces Liferay DXP's home page's search and sign in components are in a \\texttt {fieldset}.}}{522}{figure.184.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {184.2}{\\ignorespaces Before the \\texttt {fieldset}'s nested fields, it prints \\emph {test} surrounded by asterisks.}}{523}{figure.184.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {184.2}Related Topics}{523}{section.184.2}\\protected@file@percent }\n\\newlabel{related-topics-19}{{184.2}{523}{Related Topics}{section.184.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {185}Customizing Widgets}{525}{chapter.185}\\protected@file@percent }\n\\newlabel{customizing-widgets}{{185}{525}{Customizing Widgets}{chapter.185}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {185.1}Implementing the TemplateHandler Interface}{526}{section.185.1}\\protected@file@percent }\n\\newlabel{implementing-the-templatehandler-interface}{{185.1}{526}{Implementing the TemplateHandler Interface}{section.185.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {185.2}Defining Display Template Definitions}{526}{section.185.2}\\protected@file@percent }\n\\newlabel{defining-display-template-definitions}{{185.2}{526}{Defining Display Template Definitions}{section.185.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {185.3}Defining Permissions}{526}{section.185.3}\\protected@file@percent }\n\\newlabel{defining-permissions}{{185.3}{526}{Defining Permissions}{section.185.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {185.4}Exposing the Widget Template Selection}{526}{section.185.4}\\protected@file@percent }\n\\newlabel{exposing-the-widget-template-selection}{{185.4}{526}{Exposing the Widget Template Selection}{section.185.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {185.5}Recommendations for Using Widget Templates}{527}{section.185.5}\\protected@file@percent }\n\\newlabel{recommendations-for-using-widget-templates}{{185.5}{527}{Recommendations for Using Widget Templates}{section.185.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {186}Implementing Widget Templates}{529}{chapter.186}\\protected@file@percent }\n\\newlabel{implementing-widget-templates}{{186}{529}{Implementing Widget Templates}{chapter.186}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {186.1}{\\ignorespaces By using a custom display template, your portlet's display can be customized.}}{529}{figure.186.1}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {186.2}{\\ignorespaces You can click a variable to add it to the template editor.}}{531}{figure.186.2}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {186.3}{\\ignorespaces You can choose the Widget Template you want to apply from the widget's Configuration menu.}}{532}{figure.186.3}\\protected@file@percent }\n\\gdef \\LT@x {\\LT@entry \n {1}{192.48683pt}\\LT@entry \n {1}{277.26817pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {187}Dynamic Includes}{537}{chapter.187}\\protected@file@percent }\n\\newlabel{dynamic-includes}{{187}{537}{Dynamic Includes}{chapter.187}{}}\n\\gdef \\LT@xi {\\LT@entry \n {1}{59.00896pt}\\LT@entry \n {3}{83.90862pt}\\LT@entry \n {3}{99.2502pt}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {188}WYSIWYG Editor Dynamic Includes}{539}{chapter.188}\\protected@file@percent }\n\\newlabel{wysiwyg-editor-dynamic-includes}{{188}{539}{WYSIWYG Editor Dynamic Includes}{chapter.188}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {188.1}Related Topics}{540}{section.188.1}\\protected@file@percent }\n\\newlabel{related-topics-20}{{188.1}{540}{Related Topics}{section.188.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {189}Top Head JSP Dynamic Includes}{541}{chapter.189}\\protected@file@percent }\n\\newlabel{top-head-jsp-dynamic-includes}{{189}{541}{Top Head JSP Dynamic Includes}{chapter.189}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {189.1}Related Topics}{542}{section.189.1}\\protected@file@percent }\n\\newlabel{related-topics-21}{{189.1}{542}{Related Topics}{section.189.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {190}Top JS Dynamic Include}{543}{chapter.190}\\protected@file@percent }\n\\newlabel{top-js-dynamic-include}{{190}{543}{Top JS Dynamic Include}{chapter.190}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {190.1}Related Topics}{544}{section.190.1}\\protected@file@percent }\n\\newlabel{related-topics-22}{{190.1}{544}{Related Topics}{section.190.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {191}Bottom JSP Dynamic Includes}{545}{chapter.191}\\protected@file@percent }\n\\newlabel{bottom-jsp-dynamic-includes}{{191}{545}{Bottom JSP Dynamic Includes}{chapter.191}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {191.1}Related Topics}{546}{section.191.1}\\protected@file@percent }\n\\newlabel{related-topics-23}{{191.1}{546}{Related Topics}{section.191.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {192}Waiting on Lifecycle Events}{547}{chapter.192}\\protected@file@percent }\n\\newlabel{waiting-on-lifecycle-events}{{192}{547}{Waiting on Lifecycle Events}{chapter.192}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {192.1}Taking action from a component}{547}{section.192.1}\\protected@file@percent }\n\\newlabel{taking-action-from-a-component}{{192.1}{547}{Taking action from a component}{section.192.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {192.2}Taking action from a non-component class}{548}{section.192.2}\\protected@file@percent }\n\\newlabel{taking-action-from-a-non-component-class}{{192.2}{548}{Taking action from a non-component class}{section.192.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {192.3}Related Topics}{549}{section.192.3}\\protected@file@percent }\n\\newlabel{related-topics-24}{{192.3}{549}{Related Topics}{section.192.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {193}Liferay Forms}{551}{chapter.193}\\protected@file@percent }\n\\newlabel{liferay-forms}{{193}{551}{Liferay Forms}{chapter.193}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {193.1}Liferay Forms Extension Points}{551}{section.193.1}\\protected@file@percent }\n\\newlabel{liferay-forms-extension-points}{{193.1}{551}{Liferay Forms Extension Points}{section.193.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {194}Form Storage Adapters}{553}{chapter.194}\\protected@file@percent }\n\\newlabel{form-storage-adapters}{{194}{553}{Form Storage Adapters}{chapter.194}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {194.1}Storage Adapter Methods}{553}{section.194.1}\\protected@file@percent }\n\\newlabel{storage-adapter-methods}{{194.1}{553}{Storage Adapter Methods}{section.194.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {194.1}{\\ignorespaces Choose a Storage Type for your form records.}}{554}{figure.194.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {194.2}The CRUD Methods}{554}{section.194.2}\\protected@file@percent }\n\\newlabel{the-crud-methods}{{194.2}{554}{The CRUD Methods}{section.194.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {194.3}Validating Form Entries}{555}{section.194.3}\\protected@file@percent }\n\\newlabel{validating-form-entries}{{194.3}{555}{Validating Form Entries}{section.194.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {194.4}Enabling the Storage Adapter}{556}{section.194.4}\\protected@file@percent }\n\\newlabel{enabling-the-storage-adapter}{{194.4}{556}{Enabling the Storage Adapter}{section.194.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {195}Creating a Form Storage Adapter}{557}{chapter.195}\\protected@file@percent }\n\\newlabel{creating-a-form-storage-adapter}{{195}{557}{Creating a Form Storage Adapter}{chapter.195}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.1}Storage Adapter CRUD Operations}{557}{section.195.1}\\protected@file@percent }\n\\newlabel{storage-adapter-crud-operations}{{195.1}{557}{Storage Adapter CRUD Operations}{section.195.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.2}Create}{557}{section.195.2}\\protected@file@percent }\n\\newlabel{create}{{195.2}{557}{Create}{section.195.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.3}Read}{558}{section.195.3}\\protected@file@percent }\n\\newlabel{read}{{195.3}{558}{Read}{section.195.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.4}Update}{559}{section.195.4}\\protected@file@percent }\n\\newlabel{update}{{195.4}{559}{Update}{section.195.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.5}Delete}{559}{section.195.5}\\protected@file@percent }\n\\newlabel{delete}{{195.5}{559}{Delete}{section.195.5}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {195.6}Beyond CRUD: Validation}{560}{section.195.6}\\protected@file@percent }\n\\newlabel{beyond-crud-validation}{{195.6}{560}{Beyond CRUD: Validation}{section.195.6}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {196}Overriding Language Keys}{561}{chapter.196}\\protected@file@percent }\n\\newlabel{overriding-language-keys}{{196}{561}{Overriding Language Keys}{chapter.196}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {197}Overriding Global Language Keys}{563}{chapter.197}\\protected@file@percent }\n\\newlabel{overriding-global-language-keys}{{197}{563}{Overriding Global Language Keys}{chapter.197}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {197.1}Determine the language keys to override}{563}{section.197.1}\\protected@file@percent }\n\\newlabel{determine-the-language-keys-to-override}{{197.1}{563}{Determine the language keys to override}{section.197.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {197.1}{\\ignorespaces Messages displayed in Liferay's user interface can be customized.}}{564}{figure.197.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {197.2}Override the keys in a new language properties file}{564}{section.197.2}\\protected@file@percent }\n\\newlabel{override-the-keys-in-a-new-language-properties-file}{{197.2}{564}{Override the keys in a new language properties file}{section.197.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {197.3}Create a Resource Bundle service component}{564}{section.197.3}\\protected@file@percent }\n\\newlabel{create-a-resource-bundle-service-component}{{197.3}{564}{Create a Resource Bundle service component}{section.197.3}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {197.2}{\\ignorespaces This button uses the overridden \\texttt {publish} key.}}{566}{figure.197.2}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {197.4}Related Topics}{566}{section.197.4}\\protected@file@percent }\n\\newlabel{related-topics-25}{{197.4}{566}{Related Topics}{section.197.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {198}Overriding a Module's Language Keys}{567}{chapter.198}\\protected@file@percent }\n\\newlabel{overriding-a-modules-language-keys}{{198}{567}{Overriding a Module's Language Keys}{chapter.198}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {198.1}Find the module and its metadata and language keys}{567}{section.198.1}\\protected@file@percent }\n\\newlabel{find-the-module-and-its-metadata-and-language-keys}{{198.1}{567}{Find the module and its metadata and language keys}{section.198.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {198.2}Write custom language key values}{568}{section.198.2}\\protected@file@percent }\n\\newlabel{write-custom-language-key-values}{{198.2}{568}{Write custom language key values}{section.198.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {198.3}Prioritize Your Module's Resource Bundle}{569}{section.198.3}\\protected@file@percent }\n\\newlabel{prioritize-your-modules-resource-bundle}{{198.3}{569}{Prioritize Your Module's Resource Bundle}{section.198.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {198.4}Related Topics}{570}{section.198.4}\\protected@file@percent }\n\\newlabel{related-topics-26}{{198.4}{570}{Related Topics}{section.198.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {199}Overriding Liferay Services (Service Wrappers)}{571}{chapter.199}\\protected@file@percent }\n\\newlabel{overriding-liferay-services-service-wrappers}{{199}{571}{Overriding Liferay Services (Service Wrappers)}{chapter.199}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {199.1}Related Topics}{572}{section.199.1}\\protected@file@percent }\n\\newlabel{related-topics-27}{{199.1}{572}{Related Topics}{section.199.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {200}Overriding lpkg Files}{573}{chapter.200}\\protected@file@percent }\n\\newlabel{overriding-lpkg-files}{{200}{573}{Overriding lpkg Files}{chapter.200}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {201}Overriding Liferay MVC Commands}{575}{chapter.201}\\protected@file@percent }\n\\newlabel{overriding-liferay-mvc-commands}{{201}{575}{Overriding Liferay MVC Commands}{chapter.201}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {202}Adding Logic to MVC Commands}{577}{chapter.202}\\protected@file@percent }\n\\newlabel{adding-logic-to-mvc-commands}{{202}{577}{Adding Logic to MVC Commands}{chapter.202}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {202.1}Step 1: Implement the interface}{577}{section.202.1}\\protected@file@percent }\n\\newlabel{step-1-implement-the-interface}{{202.1}{577}{Step 1: Implement the interface}{section.202.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {202.2}Step 2: Publish as a component}{578}{section.202.2}\\protected@file@percent }\n\\newlabel{step-2-publish-as-a-component}{{202.2}{578}{Step 2: Publish as a component}{section.202.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {202.3}Step 3: Refer to the original implementation}{578}{section.202.3}\\protected@file@percent }\n\\newlabel{step-3-refer-to-the-original-implementation}{{202.3}{578}{Step 3: Refer to the original implementation}{section.202.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {202.4}Step 4: Add the logic}{579}{section.202.4}\\protected@file@percent }\n\\newlabel{step-4-add-the-logic}{{202.4}{579}{Step 4: Add the logic}{section.202.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {203}Overriding MVCRenderCommands}{581}{chapter.203}\\protected@file@percent }\n\\newlabel{overriding-mvcrendercommands}{{203}{581}{Overriding MVCRenderCommands}{chapter.203}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {203.1}Adding Logic to an Existing MVC Render Command}{582}{section.203.1}\\protected@file@percent }\n\\newlabel{adding-logic-to-an-existing-mvc-render-command}{{203.1}{582}{Adding Logic to an Existing MVC Render Command}{section.203.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {203.2}Redirecting to a New JSP}{582}{section.203.2}\\protected@file@percent }\n\\newlabel{redirecting-to-a-new-jsp}{{203.2}{582}{Redirecting to a New JSP}{section.203.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {203.3}Related Topics}{584}{section.203.3}\\protected@file@percent }\n\\newlabel{related-topics-28}{{203.3}{584}{Related Topics}{section.203.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {204}Overriding MVCActionCommands}{585}{chapter.204}\\protected@file@percent }\n\\newlabel{overriding-mvcactioncommands}{{204}{585}{Overriding MVCActionCommands}{chapter.204}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {204.1}Related Topics}{586}{section.204.1}\\protected@file@percent }\n\\newlabel{related-topics-29}{{204.1}{586}{Related Topics}{section.204.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {205}Overriding MVCResourceCommands}{587}{chapter.205}\\protected@file@percent }\n\\newlabel{overriding-mvcresourcecommands}{{205}{587}{Overriding MVCResourceCommands}{chapter.205}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {205.1}Related Topics}{588}{section.205.1}\\protected@file@percent }\n\\newlabel{related-topics-30}{{205.1}{588}{Related Topics}{section.205.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {206}Overriding OSGi Services}{589}{chapter.206}\\protected@file@percent }\n\\newlabel{overriding-osgi-services}{{206}{589}{Overriding OSGi Services}{chapter.206}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {207}Examining an OSGi Service to Override}{591}{chapter.207}\\protected@file@percent }\n\\newlabel{examining-an-osgi-service-to-override}{{207}{591}{Examining an OSGi Service to Override}{chapter.207}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {207.1}Gathering Information on a Service}{591}{section.207.1}\\protected@file@percent }\n\\newlabel{gathering-information-on-a-service}{{207.1}{591}{Gathering Information on a Service}{section.207.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {207.2}Step 1: Copy the Service Interface Name}{592}{section.207.2}\\protected@file@percent }\n\\newlabel{step-1-copy-the-service-interface-name}{{207.2}{592}{Step 1: Copy the Service Interface Name}{section.207.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {207.3}Step 2: Copy the Existing Service Name}{592}{section.207.3}\\protected@file@percent }\n\\newlabel{step-2-copy-the-existing-service-name}{{207.3}{592}{Step 2: Copy the Existing Service Name}{section.207.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {207.4}Step 3: Gather Reference Configuration Details (if reconfiguration is needed)}{593}{section.207.4}\\protected@file@percent }\n\\newlabel{step-3-gather-reference-configuration-details-if-reconfiguration-is-needed}{{207.4}{593}{Step 3: Gather Reference Configuration Details (if reconfiguration is needed)}{section.207.4}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {207.5}Related Topics}{594}{section.207.5}\\protected@file@percent }\n\\newlabel{related-topics-31}{{207.5}{594}{Related Topics}{section.207.5}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {208}Creating a Custom OSGi Service}{595}{chapter.208}\\protected@file@percent }\n\\newlabel{creating-a-custom-osgi-service}{{208}{595}{Creating a Custom OSGi Service}{chapter.208}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {208.1}Related Topics}{596}{section.208.1}\\protected@file@percent }\n\\newlabel{related-topics-32}{{208.1}{596}{Related Topics}{section.208.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {209}Reconfiguring Components to Use Your OSGi Service}{597}{chapter.209}\\protected@file@percent }\n\\newlabel{reconfiguring-components-to-use-your-osgi-service}{{209}{597}{Reconfiguring Components to Use Your OSGi Service}{chapter.209}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {209.1}Reconfiguring the Service Reference}{598}{section.209.1}\\protected@file@percent }\n\\newlabel{reconfiguring-the-service-reference}{{209.1}{598}{Reconfiguring the Service Reference}{section.209.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {209.1}{\\ignorespaces Because the example component's service reference is overridden by the configuration file deployment, the portlet indicates it's calling the custom service.}}{599}{figure.209.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {209.2}Related Topics}{599}{section.209.2}\\protected@file@percent }\n\\newlabel{related-topics-33}{{209.2}{599}{Related Topics}{section.209.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {210}Portlet Filters}{601}{chapter.210}\\protected@file@percent }\n\\newlabel{portlet-filters}{{210}{601}{Portlet Filters}{chapter.210}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {210.1}Sample Portlet}{602}{section.210.1}\\protected@file@percent }\n\\newlabel{sample-portlet}{{210.1}{602}{Sample Portlet}{section.210.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {210.2}Render filter 1 hides parts of user email addresses}{602}{section.210.2}\\protected@file@percent }\n\\newlabel{render-filter-1-hides-parts-of-user-email-addresses}{{210.2}{602}{Render filter 1 hides parts of user email addresses}{section.210.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {210.3}RenderFilter 2 Logs Statistics}{604}{section.210.3}\\protected@file@percent }\n\\newlabel{renderfilter-2-logs-statistics}{{210.3}{604}{RenderFilter 2 Logs Statistics}{section.210.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {210.4}Related Topics}{605}{section.210.4}\\protected@file@percent }\n\\newlabel{related-topics-34}{{210.4}{605}{Related Topics}{section.210.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {211}Product Navigation}{607}{chapter.211}\\protected@file@percent }\n\\newlabel{product-navigation}{{211}{607}{Product Navigation}{chapter.211}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {211.1}{\\ignorespaces The main product navigation menus include the Product Menu, Control Menu, Simulation Menu and User Personal Menu.}}{607}{figure.211.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {211.1}Product Menu}{608}{section.211.1}\\protected@file@percent }\n\\newlabel{product-menu}{{211.1}{608}{Product Menu}{section.211.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {211.2}Control Menu}{608}{section.211.2}\\protected@file@percent }\n\\newlabel{control-menu}{{211.2}{608}{Control Menu}{section.211.2}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {211.2}{\\ignorespaces The Control Menu has three configurable areas: left, right, and middle. It also displays the title and type of page that you are currently viewing.}}{608}{figure.211.2}\\protected@file@percent }\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {211.3}{\\ignorespaces When switching your context to web content, the Control Menu adapts to provide helpful options for that area.}}{608}{figure.211.3}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {211.3}Simulation Menu}{609}{section.211.3}\\protected@file@percent }\n\\newlabel{simulation-menu}{{211.3}{609}{Simulation Menu}{section.211.3}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {211.4}{\\ignorespaces The Simulation Menu offers a device preview application.}}{609}{figure.211.4}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {211.4}User Personal Menu}{610}{section.211.4}\\protected@file@percent }\n\\newlabel{user-personal-menu}{{211.4}{610}{User Personal Menu}{section.211.4}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {211.5}{\\ignorespaces By default, the User Personal Menu contains the signed-in user's avatar, which opens the user's settings when selected.}}{610}{figure.211.5}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {212}Customizing the Product Menu}{613}{chapter.212}\\protected@file@percent }\n\\newlabel{customizing-the-product-menu}{{212}{613}{Customizing the Product Menu}{chapter.212}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {212.1}PanelCategory Interface}{613}{section.212.1}\\protected@file@percent }\n\\newlabel{panelcategory-interface}{{212.1}{613}{PanelCategory Interface}{section.212.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {212.2}BasePanelCategory}{614}{section.212.2}\\protected@file@percent }\n\\newlabel{basepanelcategory}{{212.2}{614}{BasePanelCategory}{section.212.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {212.3}BaseJSPPanelCategory}{614}{section.212.3}\\protected@file@percent }\n\\newlabel{basejsppanelcategory}{{212.3}{614}{BaseJSPPanelCategory}{section.212.3}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {212.4}PanelApp Interface}{614}{section.212.4}\\protected@file@percent }\n\\newlabel{panelapp-interface}{{212.4}{614}{PanelApp Interface}{section.212.4}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {213}Adding Custom Panel Categories}{617}{chapter.213}\\protected@file@percent }\n\\newlabel{adding-custom-panel-categories}{{213}{617}{Adding Custom Panel Categories}{chapter.213}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {213.1}Creating the OSGi Module}{617}{section.213.1}\\protected@file@percent }\n\\newlabel{creating-the-osgi-module}{{213.1}{617}{Creating the OSGi Module}{section.213.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {213.2}Implementing Liferay's Frameworks}{617}{section.213.2}\\protected@file@percent }\n\\newlabel{implementing-liferays-frameworks}{{213.2}{617}{Implementing Liferay's Frameworks}{section.213.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {214}Adding Custom Panel Apps}{621}{chapter.214}\\protected@file@percent }\n\\newlabel{adding-custom-panel-apps}{{214}{621}{Adding Custom Panel Apps}{chapter.214}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {215}Customizing the Control Menu}{623}{chapter.215}\\protected@file@percent }\n\\newlabel{customizing-the-control-menu}{{215}{623}{Customizing the Control Menu}{chapter.215}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {215.1}{\\ignorespaces This image shows where your entry will reside depending on the category you select.}}{623}{figure.215.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {215.1}ProductNavigationControlMenuEntry Interface}{623}{section.215.1}\\protected@file@percent }\n\\newlabel{productnavigationcontrolmenuentry-interface}{{215.1}{623}{ProductNavigationControlMenuEntry Interface}{section.215.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {215.2}BaseProductNavigationControlMenuEntry}{624}{section.215.2}\\protected@file@percent }\n\\newlabel{baseproductnavigationcontrolmenuentry}{{215.2}{624}{BaseProductNavigationControlMenuEntry}{section.215.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {215.3}BaseJSPProductNavigationControlMenuEntry}{624}{section.215.3}\\protected@file@percent }\n\\newlabel{basejspproductnavigationcontrolmenuentry}{{215.3}{624}{BaseJSPProductNavigationControlMenuEntry}{section.215.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {216}Creating Control Menu Entries}{625}{chapter.216}\\protected@file@percent }\n\\newlabel{creating-control-menu-entries}{{216}{625}{Creating Control Menu Entries}{chapter.216}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {216.1}Creating the OSGi Module}{625}{section.216.1}\\protected@file@percent }\n\\newlabel{creating-the-osgi-module-1}{{216.1}{625}{Creating the OSGi Module}{section.216.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {216.2}Implementing Liferay's Frameworks}{625}{section.216.2}\\protected@file@percent }\n\\newlabel{implementing-liferays-frameworks-1}{{216.2}{625}{Implementing Liferay's Frameworks}{section.216.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {217}Defining Icons and Tooltips}{629}{chapter.217}\\protected@file@percent }\n\\newlabel{defining-icons-and-tooltips}{{217}{629}{Defining Icons and Tooltips}{chapter.217}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {217.1}Control Menu Entry Icons}{629}{section.217.1}\\protected@file@percent }\n\\newlabel{control-menu-entry-icons}{{217.1}{629}{Control Menu Entry Icons}{section.217.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {217.2}Control Menu Entry Tooltips}{630}{section.217.2}\\protected@file@percent }\n\\newlabel{control-menu-entry-tooltips}{{217.2}{630}{Control Menu Entry Tooltips}{section.217.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {218}Extending the Simulation Menu}{631}{chapter.218}\\protected@file@percent }\n\\newlabel{extending-the-simulation-menu}{{218}{631}{Extending the Simulation Menu}{chapter.218}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {218.1}{\\ignorespaces The Simulation Menu also displays Segments to help simulate different user experiences.}}{632}{figure.218.1}\\protected@file@percent }\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {219}Customizing the User Personal Bar and Menu}{635}{chapter.219}\\protected@file@percent }\n\\newlabel{customizing-the-user-personal-bar-and-menu}{{219}{635}{Customizing the User Personal Bar and Menu}{chapter.219}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {219.1}{\\ignorespaces By default, the User Personal Bar contains the signed-in user's avatar, which opens the Personal Menu when selected.}}{635}{figure.219.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {219.1}Displaying the Personal Menu}{636}{section.219.1}\\protected@file@percent }\n\\newlabel{displaying-the-personal-menu}{{219.1}{636}{Displaying the Personal Menu}{section.219.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {220}Using a Custom Portlet in Place of the User Personal Bar}{637}{chapter.220}\\protected@file@percent }\n\\newlabel{using-a-custom-portlet-in-place-of-the-user-personal-bar}{{220}{637}{Using a Custom Portlet in Place of the User Personal Bar}{chapter.220}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {220.1}Related Topics}{638}{section.220.1}\\protected@file@percent }\n\\newlabel{related-topics-35}{{220.1}{638}{Related Topics}{section.220.1}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {221}Customizing the Personal Menu}{639}{chapter.221}\\protected@file@percent }\n\\newlabel{customizing-the-personal-menu}{{221}{639}{Customizing the Personal Menu}{chapter.221}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {221.1}Adding an Entry to the Personal Menu}{639}{section.221.1}\\protected@file@percent }\n\\newlabel{adding-an-entry-to-the-personal-menu}{{221.1}{639}{Adding an Entry to the Personal Menu}{section.221.1}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {221.1}{\\ignorespaces The Personal Menu is organized into four sections.}}{640}{figure.221.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {221.2}Adding a Portlet Entry to the Personal Menu}{641}{section.221.2}\\protected@file@percent }\n\\newlabel{adding-a-portlet-entry-to-the-personal-menu}{{221.2}{641}{Adding a Portlet Entry to the Personal Menu}{section.221.2}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {221.3}Related Topics}{642}{section.221.3}\\protected@file@percent }\n\\newlabel{related-topics-36}{{221.3}{642}{Related Topics}{section.221.3}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {222}Customizing Workflow}{643}{chapter.222}\\protected@file@percent }\n\\newlabel{customizing-workflow}{{222}{643}{Customizing Workflow}{chapter.222}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {223}Creating SLA Calendars}{645}{chapter.223}\\protected@file@percent }\n\\newlabel{creating-sla-calendars}{{223}{645}{Creating SLA Calendars}{chapter.223}{}}\n\\@writefile{lof}{\\contentsline {figure}{\\numberline {223.1}{\\ignorespaces Write a Custom SLA Calendar if the default, 24/7 calendar isn't sufficient.}}{645}{figure.223.1}\\protected@file@percent }\n\\@writefile{toc}{\\contentsline {section}{\\numberline {223.1}Dependencies}{646}{section.223.1}\\protected@file@percent }\n\\newlabel{dependencies-1}{{223.1}{646}{Dependencies}{section.223.1}{}}\n\\@writefile{toc}{\\contentsline {section}{\\numberline {223.2}Implementation Steps}{646}{section.223.2}\\protected@file@percent }\n\\newlabel{implementation-steps}{{223.2}{646}{Implementation Steps}{section.223.2}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {224}Customizing Core Functionality with Ext}{649}{chapter.224}\\protected@file@percent }\n\\newlabel{customizing-core-functionality-with-ext}{{224}{649}{Customizing Core Functionality with Ext}{chapter.224}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {225}Extending Core Classes Using Spring with Ext Plugins}{651}{chapter.225}\\protected@file@percent }\n\\newlabel{extending-core-classes-using-spring-with-ext-plugins}{{225}{651}{Extending Core Classes Using Spring with Ext Plugins}{chapter.225}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {226}Overriding Core Classes with Ext Plugins}{653}{chapter.226}\\protected@file@percent }\n\\newlabel{overriding-core-classes-with-ext-plugins}{{226}{653}{Overriding Core Classes with Ext Plugins}{chapter.226}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {227}Adding to the web.xml with Ext Plugins}{655}{chapter.227}\\protected@file@percent }\n\\newlabel{adding-to-the-web.xml-with-ext-plugins}{{227}{655}{Adding to the web.xml with Ext Plugins}{chapter.227}{}}\n\\@writefile{lof}{\\addvspace {10pt}}\n\\@writefile{lot}{\\addvspace {10pt}}\n\\@writefile{toc}{\\contentsline {chapter}{\\chapternumberline {228}Modifying the web.xml with Ext Plugins}{657}{chapter.228}\\protected@file@percent }\n\\newlabel{modifying-the-web.xml-with-ext-plugins}{{228}{657}{Modifying the web.xml with Ext Plugins}{chapter.228}{}}\n\\@setckpt{developer/customization}{\n\\setcounter{page}{659}\n\\setcounter{equation}{0}\n\\setcounter{enumi}{3}\n\\setcounter{enumii}{2}\n\\setcounter{enumiii}{3}\n\\setcounter{enumiv}{0}\n\\setcounter{footnote}{0}\n\\setcounter{mpfootnote}{0}\n\\setcounter{@memmarkcntra}{-1}\n\\setcounter{storedpagenumber}{1}\n\\setcounter{book}{0}\n\\setcounter{part}{2}\n\\setcounter{chapter}{228}\n\\setcounter{section}{0}\n\\setcounter{subsection}{0}\n\\setcounter{subsubsection}{0}\n\\setcounter{paragraph}{0}\n\\setcounter{subparagraph}{0}\n\\setcounter{@ppsavesec}{0}\n\\setcounter{@ppsaveapp}{0}\n\\setcounter{vslineno}{0}\n\\setcounter{poemline}{0}\n\\setcounter{modulo@vs}{0}\n\\setcounter{memfvsline}{0}\n\\setcounter{verse}{0}\n\\setcounter{chrsinstr}{0}\n\\setcounter{poem}{0}\n\\setcounter{newflo@tctr}{4}\n\\setcounter{@contsubnum}{0}\n\\setcounter{section@level}{0}\n\\setcounter{maxsecnumdepth}{1}\n\\setcounter{sidefootnote}{0}\n\\setcounter{pagenote}{0}\n\\setcounter{pagenoteshadow}{0}\n\\setcounter{memfbvline}{0}\n\\setcounter{bvlinectr}{0}\n\\setcounter{cp@cntr}{0}\n\\setcounter{ism@mctr}{0}\n\\setcounter{xsm@mctr}{0}\n\\setcounter{csm@mctr}{0}\n\\setcounter{ksm@mctr}{0}\n\\setcounter{xksm@mctr}{0}\n\\setcounter{cksm@mctr}{0}\n\\setcounter{msm@mctr}{0}\n\\setcounter{xmsm@mctr}{0}\n\\setcounter{cmsm@mctr}{0}\n\\setcounter{bsm@mctr}{0}\n\\setcounter{workm@mctr}{0}\n\\setcounter{sheetsequence}{731}\n\\setcounter{lastsheet}{2851}\n\\setcounter{lastpage}{2779}\n\\setcounter{figure}{0}\n\\setcounter{lofdepth}{1}\n\\setcounter{table}{0}\n\\setcounter{lotdepth}{1}\n\\setcounter{Item}{837}\n\\setcounter{Hfootnote}{5}\n\\setcounter{bookmark@seq@number}{0}\n\\setcounter{memhycontfloat}{0}\n\\setcounter{Hpagenote}{0}\n\\setcounter{r@tfl@t}{0}\n\\setcounter{float@type}{4}\n\\setcounter{LT@tables}{11}\n\\setcounter{LT@chunks}{3}\n\\setcounter{parentequation}{0}\n\\setcounter{FancyVerbLine}{0}\n}\n"
},
{
"path": "book/developer/customization.tex",
"content": "\\chapter{Liferay Customization}\\label{liferay-customization}\n\nLiferay DXP is highly customizable. Its modular architecture contains\ncomponents you can extend and override dynamically. This section\nexplains Liferay DXP's architecture and customization fundamentals and\ndemonstrates overriding and extending Liferay DXP components and\napplications using APIs.\n\n\\begin{itemize}\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/fundamentals}{Fundamentals}\n include understanding and configuring dependencies, packaging, and\n deployment. Here you'll work with module JARs, plugin WARs,\n components, and Java packages in Liferay DXP.\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/architecture}{Architecture}\n dives deep into how Liferay DXP uses modularity and OSGi to provide\n the core, application modules, component services, and extension\n points. Learning the architecture helps you develop better\n customizations fast, and it empowers you to build extension points\n into your own applications.\n\\item\n Built-in customization features, including\n \\href{/docs/7-2/user/-/knowledge_base/u/styling-widgets-with-widget-templates}{Widget\n Templates} and\n \\href{/docs/7-2/user/-/knowledge_base/u/web-experience-management}{Web\n Experience Management} help you customize content and pages faster.\n All this is done from within the Liferay DXP UI.\n\\item\n Application customization articles (listed after the Architecture\n articles) demonstrate modifying Liferay applications via their APIs\n and extension points.\n\\end{itemize}\n\nStart with\n\\href{/docs/7-2/customization/-/knowledge_base/c/fundamentals}{Fundamentals}.\n\n\\chapter{Fundamentals}\\label{fundamentals}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nThe fundamentals of developing on Liferay DXP and customizing it are\nperhaps best learned in the context of projects. It's in projects that\nyou configure access to Liferay DXP's API, extend and override Liferay\nDXP features, and package your software for deployment. Projects are\ndeveloped as WARs or OSGi JARs, but are all installed to Liferay's OSGi\nframework as OSGi bundles. These bundles can depend on external Java\npackages, share Java packages, and be manipulated at run time via Apache\nGogo Shell. The fundamentals are explained in the context of projects so\nthat you understand them in a practical sense and can apply them right\naway. Here are the fundamental topics:\n\n\\begin{itemize}\n\\item\n \\textbf{WARs Versus OSGi JAR} explains fundamental differences between\n the WAR and OSGi JAR structures and how they're deployed in Liferay\n DXP.\n\\item\n \\textbf{Configuring Dependencies} demonstrates how to identify and\n configure Liferay artifacts and third-party artifacts to use their\n Java packages in your projects.\n\\item\n \\textbf{Importing and Exporting Packages} shows how to import the\n packages your projects need and export packages your projects provide.\n Liferay's tooling detects package use and specifies package imports\n automatically.\n\\item\n \\textbf{Semantic Versioning} shows how Liferay DXP uses a standard for\n ascribing meaning to major, minor, and micro versions of modules and\n Java packages.\n\\item\n \\textbf{Deploying WARs (WAB Generator)} explains how Liferay's WAB\n Generator deploys WAR applications as OSGi Web Application Bundles\n (WABs).\n\\item\n \\textbf{Gogo Shell} enables you to examine components, debug issues,\n and manage deployments.\n\\end{itemize}\n\nStart with understanding how WAR and OSGi JAR project structures are\nused in development.\n\n\\chapter{Configuring Dependencies}\\label{configuring-dependencies}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nLiferay DXP's modular environment lets modules provide and consume\ncapabilities via Java packages. To leverage packages from other modules\nor traditional libraries in your project, you must configure them as\ndependencies. Here you'll learn how to find artifacts (modules or\nlibraries) and configure dependencies on them.\n\n\\begin{itemize}\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/finding-artifacts}{Finding\n Artifacts} explains how to use the Application Manager, Gogo Shell,\n and Liferay DXP reference documentation to find artifacts deployed on\n Liferay DXP and available in repositories.\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/specifying-dependencies}{Specifying\n Dependencies} demonstrates specifying artifacts to Maven and Gradle\n build frameworks. It shows you how to determine whether Liferay DXP\n already exports packages from an artifact and how to configure such\n artifacts as compile-time dependencies.\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{Resolving\n Third-Party Library Package Dependencies} provides a workflow for\n using packages that are only available in traditional library JARs\n (JARs that aren't OSGi modules). It involves minimizing transitive\n dependencies so you can resolve dependencies quicker and prevent\n bloating your project with unnecessary JARs.\n\\end{itemize}\n\nYour first step is to find the artifacts you need.\n\n\\chapter{Finding Artifacts}\\label{finding-artifacts}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nUsing external artifacts in your project requires configuring their\ndependencies. To do this, look up the artifact's attributes and plug\nthem into dependency entries for your build system (either\n\\href{https://gradle.org/}{Gradle} or\n\\href{https://maven.apache.org/}{Maven}). Your build system downloads\nthe dependency artifacts your project needs to compile successfully.\n\nBefore specifying an artifact as a dependency, you must first find its\nattributes. Artifacts have these attributes:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\emph{Group ID}: Authoring organization\n\\item\n \\emph{Artifact ID}: Name/identifier\n\\item\n \\emph{Version}: Release number\n\\end{itemize}\n\nHere you'll learn how to find artifact attributes to specify artifact\ndependencies.\n\n\\section{Finding Core Artifact\nAttributes}\\label{finding-core-artifact-attributes}\n\nEach Liferay artifact is a JAR file whose \\texttt{META-INF/MANIFEST.MF}\nfile specifies OSGi bundle metadata the artifact's attributes. For\nexample, these two OSGi headers specify the artifact ID and version:\n\n\\begin{verbatim}\nBundle-SymbolicName: [artifact ID]\nBundle-Version: [version]\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Artifacts in Liferay DXP fix packs override Liferay\nDXP installation artifacts. Subfolders of a fix pack ZIP file's\n\\texttt{binaries} folder hold the artifacts. If an installed fix pack\nprovides an artifact you depend \\textbar{} on, specify the version of\nthat fix pack artifact in your dependency.\n\n\\noindent\\hrulefill\n\nThis table lists each core Liferay DXP artifact's group ID and artifact\nID and where to find the artifact's manifest, which lists the artifact\nversion:\n\n\\emph{Core Liferay DXP Artifacts}:\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 8\\tabcolsep) * \\real{0.2364}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 8\\tabcolsep) * \\real{0.2909}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 8\\tabcolsep) * \\real{0.1636}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 8\\tabcolsep) * \\real{0.1818}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 8\\tabcolsep) * \\real{0.1273}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nFile\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nGroup ID\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nArtifact ID\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nVersion\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nOrigin\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\texttt{portal-kernel.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nportal.kernel} & (see JAR's \\texttt{MANIFEST.MF}) &\nfix pack ZIP, Liferay DXP installation, or Liferay DXP dependencies\nZIP \\\\\n\\texttt{portal-impl.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nportal.impl} & (see JAR's \\texttt{MANIFEST.MF}) &\nfix pack ZIP or Liferay DXP \\texttt{.war} \\\\\n\\texttt{util-bridges.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nutil.bridges} & (see JAR's \\texttt{MANIFEST.MF}) &\nfix pack ZIP or Liferay DXP \\texttt{.war} \\\\\n\\texttt{util-java.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nutil.java} & (see JAR's \\texttt{MANIFEST.MF}) & fix\npack ZIP or Liferay DXP \\texttt{.war} \\\\\n\\texttt{util-slf4j.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nutil.slf4j} & (see JAR's \\texttt{MANIFEST.MF}) & fix\npack ZIP or Liferay DXP \\texttt{.war} \\\\\n\\texttt{util-taglibs.jar} & \\texttt{com.liferay.portal} &\n\\texttt{com.liferay.\\ \nutil.taglib} & (see JAR's \\texttt{MANIFEST.MF}) &\nfix pack ZIP or Liferay DXP \\texttt{.war} \\\\\n\\texttt{com.liferay.*} JAR files & \\texttt{com.liferay} & (see JAR's\n\\texttt{MANIFEST.MF}) & (see JAR's \\texttt{MANIFEST.MF}) & fix pack ZIP,\nLiferay DXP installation, Liferay DXP dependencies ZIP, or the OSGi\nZIP \\\\\n\\end{longtable}\n\nNext, you'll learn how to find Liferay DXP app and independent module\nartifact attributes.\n\n\\section{Finding Liferay App and Independent\nArtifacts}\\label{finding-liferay-app-and-independent-artifacts}\n\nIndependent modules and Liferay DXP app modules aren't part of the\nLiferay DXP core. You must still, however, find their artifact\nattributes if you depend on them. The resources below provide the\nartifact details for Liferay DXP's apps and independent modules:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.3750}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.6250}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nResource\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nArtifact Type\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\hyperref[app-manager]{App Manager} & Deployed modules \\\\\n\\hyperref[reference-docs]{Reference Docs} & Liferay DXP modules (per\nrelease) \\\\\n\\hyperref[maven-central]{Maven Central} & All artifact types: Liferay\nDXP and third party, module and non-module \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Important}: \\texttt{com.liferay} is the group ID for all of\nLiferay's apps and independent modules.\n\n\\noindent\\hrulefill\n\nThe App Manager is the best source for information on deployed modules.\nYou'll learn about it next.\n\n\\section{App Manager}\\label{app-manager}\n\n\\href{/docs/7-2/user/-/knowledge_base/u/managing-and-configuring-apps\\#using-the-app-manager}{The\nApp Manager} knows what's deployed on your Liferay instance. Use it to\nfind deployed module attributes.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n In Liferay DXP, navigate to \\emph{Control Panel} → \\emph{Apps} →\n \\emph{App Manager}.\n\\item\n Search for the module by its display name, symbolic name, or related\n keywords. You can also browse for the module in its app. Whether\n browsing or searching, the App Manager shows the module's artifact ID\n and version number.\n\\end{enumerate}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/configuring-dependencies-search-app-manager-for-module.png}\n\\caption{You can inspect deployed module artifact IDs and version\nnumbers.}\n\\end{figure}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/configuring-dependencies-indep-modules-in-app-manager.png}\n\\caption{The App Manager aggregates Liferay and independent modules.}\n\\end{figure}\n\nIf you don't know a deployed module's group ID, use the\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Felix\nGogo Shell} to find it:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Navigate to the Gogo Shell portlet in the Control Panel →\n \\emph{Configuration} → \\emph{Gogo Shell}. Enter commands in the Felix\n Gogo Shell command prompt.\n\\item\n Search for the module by its display name (e.g.,\n \\texttt{Liferay\\ Blogs\\ API}) or a keyword. In the results, note the\n module's number. You can use it in the next step. For example, Gogo\n command results in the figure below show the Liferay Blogs API module\n number.\n\n \\begin{figure}\n \\centering\n \\includegraphics{./images/configuring-deps-gogo-grep-for-module.png}\n \\caption{Results from this Gogo command show that the module's number\n is \\texttt{1173}.}\n \\end{figure}\n\\item\n List the module's manifest headers by passing the module number to the\n \\texttt{headers} command. In the results, note the\n \\texttt{Bundle-Vendor} value: you'll match it with an artifact group\n in a later step:\n\n \\begin{figure}\n \\centering\n \\includegraphics{./images/configuring-deps-gogo-module-info.png}\n \\caption{Results from running the \\texttt{headers} command show the\n module's bundle vendor and bundle version.}\n \\end{figure}\n\\item\n On \\href{https://search.maven.org/}{Maven Central} or\n \\href{https://mvnrepository.com}{MVNRepository}, search for the module\n by its artifact ID.\n\\item\n Determine the group ID by matching the \\texttt{Bundle-Vendor} value\n from step 3 with a group listed that provides the artifact.\n\\end{enumerate}\n\nNext, Liferay DXP's reference documentation provides Liferay DXP app\nartifact attributes.\n\n\\section{Reference Docs}\\label{reference-docs}\n\nLiferay DXP's app Javadoc lists each app module's artifact ID, version\nnumber, and display name. This is the best place to look up Liferay DXP\napp modules that aren't yet deployed to your Liferay DXP instance.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} To find artifact information on a Core Liferay DXP\nartifact, refer to the previous section \\emph{Finding Core Liferay DXP\nArtifact Attributes}.\n\n\\noindent\\hrulefill\n\nFollow these steps to find a Liferay DXP app module's attributes in the\nJavadoc:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Navigate to Javadoc for an app module class. If you don't have a link\n to the class's Javadoc, find it by browsing\n {[}https://docs.liferay.com/dxp/apps{]}(\n\\item\n Copy the class's package name.\n\\item\n Navigate to the \\emph{Overview} page.\n\\item\n On the \\emph{Overview} page, search for the package name you copied in\n step 2.\n\\end{enumerate}\n\nThe heading above the package name shows the module's artifact ID,\nversion number, and display name. Remember, the group ID for all app\nmodules is \\texttt{com.liferay}.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/intro-configuring-dependencies-module-info-in-javadoc-overview.png}\n\\caption{Liferay DXP app Javadoc overviews list each app module's\ndisplay name, followed by its group ID, artifact ID, and version number\nin a colon-separated string. It's a Gradle artifact syntax.}\n\\end{figure}\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: Module version numbers aren't currently included in any\ntag library reference docs.\n\n\\noindent\\hrulefill\n\nNext, you'll learn how to look up artifacts on MVNRepository and Maven\nCentral.\n\n\\section{Maven Central}\\label{maven-central}\n\nMost artifacts, regardless of type or origin, are on\n\\href{https://mvnrepository.com/}{MVNRepository} and\n\\href{https://search.maven.org/}{Maven Central}. These sites can help\nyou find artifacts based on class packages. It's common to include an\nartifact's ID in the start of an artifact's package names. For example,\nif you depend on the class\n\\texttt{org.osgi.service.component.annotations.Component}, search for\nthe package name \\texttt{org.osgi.service.component.annotations} on one\nof the Maven sites.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Make sure to follow the instructions listed earlier to\ndetermine the version of Liferay artifacts you need.\n\n\\noindent\\hrulefill\n\nNow that you know the artifact's attributes, you can configure a\ndependency on it.\n\n\\section{Related Topics}\\label{related-topics}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/specifying-dependencies}{Specifying\nDependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{Importing\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/exporting-packages}{Exporting\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{Resolving\nThird Party Library Package Dependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Deploying\nWARs (WAB Generator)}\n\n\\chapter{Specifying Dependencies}\\label{specifying-dependencies}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nCompiling your project and deploying it to Liferay DXP requires\nsatisfying its dependencies on external artifacts. After\n\\href{/docs/7-2/customization/-/knowledge_base/c/finding-artifacts}{finding\nthe attributes of an artifact}, set a dependency for it in your build\nfile. Here's how:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Determine whether Liferay DXP provides the Java packages you use from\n the artifact. These files list the packages Liferay DXP exports:\n\n \\begin{itemize}\n \\item\n \\texttt{modules/core/portal-bootstrap/system.packages.extra.bnd}\n file in the\n \\href{https://github.com/liferay/liferay-portal/blob/7.2.x/modules/core/portal-bootstrap/system.packages.extra.bnd}{GitHub\n repository}. It lists exported packages on separate lines, making\n them easy to read.\n \\item\n \\texttt{META-INF/system.packages.extra.mf} file in\n \\texttt{{[}LIFERAY\\_HOME{]}/osgi/core/com.liferay.portal.bootstrap.jar}.\n The file is available in Liferay DXP bundles. It lists exported\n packages in a paragraph wrapped at 70 columns--they're harder to\n read here than in the \\texttt{system.packages.extra.bnd} file.\n \\end{itemize}\n\\item\n If Liferay DXP exports all the packages you use from the artifact,\n specify the artifact as a compile-only dependency. This prevents your\n build framework from bundling the artifact with your project. Here's\n how to make the dependency compile-only:\n\n \\textbf{Gradle:} Add the \\texttt{compileOnly} directive to the\n dependency\n\n \\textbf{Maven:} Add the\n \\texttt{\\textless{}scope\\textgreater{}provided\\textless{}/scope\\textgreater{}}\n element to the dependency.\n\\item\n Add a dependency entry for the artifact. Here's the artifact\n terminology for the Gradle and Maven build frameworks:\n\\end{enumerate}\n\n\\emph{Artifact Terminology}\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}llll@{}}\n\\toprule\\noalign{}\nFramework & Group ID & Artifact ID & Version \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\nGradle & \\texttt{group} & \\texttt{name} & \\texttt{version} \\\\\nMaven & \\texttt{groupId} & \\texttt{artifactId} & \\texttt{version} \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\nHere is an example dependency on Liferay's Journal API module for\nGradle, and Maven:\n\n\\emph{Gradle (\\texttt{build.gradle} entry):}\n\n\\begin{verbatim}\ndependencies {\n compileOnly group: \"com.liferay\", name: \"com.liferay.journal.api\", version: \"1.0.1\"\n ...\n}\n\\end{verbatim}\n\n\\emph{Maven (\\texttt{pom.xml} entry):}\n\n\\begin{verbatim}\n\n com.liferay\n com.liferay.journal.api\n 1.0.1\n provided\n\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:}\n\\href{/docs/7-2/reference/-/knowledge_base/r/third-party-packages-portal-exports}{Liferay\nDXP exports many third-party packages}. Deploy your module to check if\nLiferay DXP or another module in your Liferay instance's OSGi runtime\nframework provides the package you need. If it's provided already,\nspecify the corresponding dependency as being ``provided''. Here's how\nto specify a provided dependency:\n\nMaven:\n\\texttt{\\textless{}scope\\textgreater{}provided\\textless{}/scope\\textgreater{}}\n\nGradle: \\texttt{providedCompile}\n\nDon't deploy a provided package's JAR again or embed the JAR in your\nproject. Exporting the same package from different JARs leads to ``split\npackage'' issues, whose side affects differ from case to case. If the\npackage is in a third-party library (not an OSGi module), refer to\n{[}Resolving Third\n\n\\noindent\\hrulefill Party Library\nDependencies{]}(/docs/7-2/customization/-/knowledge\\_base/c/adding-third-party-libraries-to-a-module).\n\n\\noindent\\hrulefill\n\nIf you're developing a WAR that requires a different version of a\nthird-party package that\n\\href{/docs/7-2/reference/-/knowledge_base/r/third-party-packages-portal-exports}{Liferay\nDXP or another module exports}, specify that package in your\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{\\texttt{Import-Package:}\nlist}. If the package provider is an OSGi module, publish its exported\npackages by deploying that module. Otherwise, follow the instructions\nfor\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{adding\na third-party library (not an OSGi module)}.\n\n\\noindent\\hrulefill\n\nNice! You know how to specify artifact dependencies. Now that's a skill\nyou can depend on!\n\n\\section{Related Topics}\\label{related-topics-1}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/finding-artifacts}{Finding\nArtifacts}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{Importing\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/exporting-packages}{Exporting\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{Resolving\nThird Party Library Package Dependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Deploying\nWARs (WAB Generator)}\n\n\\chapter{Resolving Third Party Library Package\nDependencies}\\label{resolving-third-party-library-package-dependencies}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nLiferay's OSGi framework lets you build applications composed of\nmultiple OSGi bundles (modules). For the framework to assemble the\nmodules into a working system, the modules must resolve their Java\npackage dependencies. In a perfect world, every Java library would be an\nOSGi module, but many libraries aren't. So how do you resolve the\npackages your project needs from non-OSGi third party libraries?\n\nHere is the main workflow for resolving third party Java library\npackages:\n\n\\textbf{Option 1 - Find an OSGi module of the library}: Projects, such\nas \\href{https://www.eclipse.org/orbit/}{Eclipse Orbit} and\n\\href{https://servicemix.apache.org/developers/source/bundles-source.html}{ServiceMix\nBundles}, convert hundreds of traditional Java libraries to OSGi\nmodules. Their artifacts are available at these locations:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{https://download.eclipse.org/tools/orbit/downloads/}{Eclipse\n Orbit downloads (select a build)}\n\\item\n \\href{https://mvnrepository.com/artifact/org.apache.servicemix.bundles}{ServiceMix\n Bundles}\n\\end{itemize}\n\nDeploying the module to Liferay's OSGi framework lets you share it on\nthe system. If you find a module for the library you need,\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{deploy}\nit. Then\n\\href{/docs/7-2/customization/-/knowledge_base/c/specifying-dependencies}{add\na compile-only dependency} for it in your project. When you deploy your\nproject, the OSGi framework wires the dependency module to your\nproject's module or web application bundle (WAB). If you don't find an\nOSGi module based on the Java library, follow Option 2.\n\n\\noindent\\hrulefill\n\n\\textbf{Tip:} Refrain from embedding library JARs that provide the same\n\\href{/docs/7-2/reference/-/knowledge_base/r/third-party-packages-portal-exports}{packages\nthat Liferay DXP or existing modules provide already}.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} If you're developing a WAR that requires a different\nversion of a third-party package that\n\\href{/docs/7-2/reference/-/knowledge_base/r/third-party-packages-portal-exports}{Liferay\nDXP or another module exports}, specify that package in your\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{\\texttt{Import-Package:}\nlist}. If the package provider is an OSGi module, publish its exported\npackages by deploying that module. Otherwise, rename the third-party\nlibrary (not an OSGi module) differently from the\n\\href{/docs/7-2/customization/-/knowledge_base/c/understanding-excluded-jars}{JAR\nthat the WAB generator excludes} and embed the JAR in your project.\n\n\\noindent\\hrulefill\n\n\\textbf{Option 2 - Resolve the Java packages privately in your project}:\nCopy \\emph{required packages} only from libraries into your project, if\nyou can or embed \\emph{libraries} wholesale, if you must. The rest of\nthis article shows you how to do these things.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Features for manipulating library packages are only\navailable to module projects that use bnd and the\n\\texttt{com.liferay.plugin} plugin, such as\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace} modules. WAR projects must embed libraries wholesale into\ntheir classpath.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: Liferay's Gradle plugin \\texttt{com.liferay.plugin}\nautomates several third party library configuration steps. The plugin is\nautomatically applied to\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace} Gradle module projects created using\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP} or\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Liferay Blade\nCLI}.\n\nTo leverage the \\texttt{com.liferay.plugin} plugin outside of Liferay\nWorkspace, add code like the listing below to your Gradle project and\nupdate the version of the \\texttt{com.liferay.gradle.plugins} artifact\nto the latest version found in the repository:\n\n\\begin{verbatim}\n buildscript {\n dependencies {\n classpath group: \"com.liferay\", name: \"com.liferay.gradle.plugins\", version: \"4.0.4\"\n }\n\n repositories {\n maven {\n url \"https://repository.liferay.com/nexus/content/repositories/liferay-public-releases/\"\n }\n }\n }\n\n apply plugin: \"com.liferay.plugin\"\n\\end{verbatim}\n\nIf you use Gradle without the \\texttt{com.liferay.plugin} plugin, you\nmust \\hyperref[embedding-libraries-using-gradle]{embed the third party\nlibraries wholesale}.\n\n\\noindent\\hrulefill\n\nThe recommended package resolution workflow is next.\n\n\\section{Library Package Resolution\nWorkflow}\\label{library-package-resolution-workflow}\n\nWhen you depend on a library JAR, much of the time you only need parts\nof it. Explicitly specifying only the Java packages you need makes your\nmodule more modular. This also keeps other modules that depend on your\nmodule from incorporating unneeded packages.\n\nHere's a configuration workflow for module projects that minimizes\ndependencies and Java package imports:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Add the library as a compile-only dependency (e.g.,\n \\texttt{compileOnly} in Gradle,\n \\texttt{\\textless{}scope\\textgreater{}provided\\textless{}/scope\\textgreater{}}\n in Maven).\n\\item\n Copy only the library packages you need by specifying them in a\n conditional package instruction (\\texttt{Conditional-Package}) in your\n \\texttt{bnd.bnd} file. Here are some examples:\n\n \\texttt{Conditional-Package:\\ foo.common*} adds packages your module\n uses such as \\texttt{foo.common}, \\texttt{foo.common-messages},\n \\texttt{foo.common-web} to your module's class path.\n\n \\texttt{Conditional-Package:\\ foo.bar.*} adds packages your module\n uses such as \\texttt{foo.bar} and all its sub-packages (e.g.,\n \\texttt{foo.bar.baz}, \\texttt{foo.bar.biz}, etc.) to your module's\n class path.\n\n \\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{Deploy\n your project}. If a class your module needs or class its dependencies\n need isn't found, go back to main workflow \\textbf{Step 1 - Find an\n OSGi module version of the library} to resolve it.\n\n \\textbf{Important}: Resolving packages by using compile-only\n dependencies and conditional package instructions assures you use only\n the packages you need and avoids unnecessary transitive dependencies.\n It's recommended to use the steps up to this point, as much as\n possible, to resolve required packages.\n\\item\n If a library package you depend on requires non-class files (e.g.,\n DLLs, descriptors) from the library, then you might need to\n \\hyperref[embedding-libraries-in-a-project]{embed the library\n wholesale in your module}. This adds the entire library to your\n module's classpath.\n\\end{enumerate}\n\nNext you'll learn how to embed libraries in your module project.\n\n\\section{Embedding Libraries in a\nProject}\\label{embedding-libraries-in-a-project}\n\nYou can use Gradle or Maven to embed libraries in your project. Below\nare examples for adding \\href{https://shiro.apache.org}{Apache Shiro}\nusing both build utilities.\n\n\\section{Embedding Libraries Using\nGradle}\\label{embedding-libraries-using-gradle}\n\nOpen your module's \\texttt{build.gradle} file and add the library as a\ndependency in the \\texttt{compileInclude} configuration:\n\n\\begin{verbatim}\ndependencies {\n compileInclude group: 'org.apache.shiro', name: 'shiro-core', version: '1.1.0'\n}\n\\end{verbatim}\n\nThe \\texttt{com.liferay.plugin} plugin's \\texttt{compileInclude}\nconfiguration is transitive. The \\texttt{compileInclude} configuration\nembeds the artifact and all its dependencies in a \\texttt{lib} folder in\nthe module's JAR. Also, it adds the artifact JARs to the module's\n\\texttt{Bundle-ClassPath} manifest header.\n\n\\textbf{Note}: The \\texttt{compileInclude} configuration does not\ndownload transitive\n\\href{https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html}{optional\ndependencies}. If your module requires such artifacts, add them as you\nwould another third party library.\n\n\\textbf{Note:} If the library you've added as a dependency in your\n\\texttt{build.gradle} file has transitive dependencies, you can\nreference them by name in an \\texttt{-includeresource:} instruction\nwithout having to add them explicitly to the dependency list. See how\nit's used in the Maven section next.\n\n\\section{Embedding a Library Using\nMaven}\\label{embedding-a-library-using-maven}\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Open your project's \\texttt{pom.xml} file and add the library as a\n dependency in the \\texttt{provided} scope:\n\n\\begin{verbatim}\n\n org.apache.shiro\n shiro-core\n 1.1.0\n provided\n\n\\end{verbatim}\n\\item\n Open your module's \\texttt{bnd.bnd} file and add the library to an\n \\texttt{-includeresource} instruction:\n\n\\begin{verbatim}\n-includeresource: META-INF/lib/shiro-core.jar=shiro-core-[0-9]*.jar;lib:=true\n\\end{verbatim}\n\n This instruction adds the \\texttt{shiro-core-{[}version{]}.jar} file\n as an included resource in the module's \\texttt{META-INF/lib} folder.\n The \\texttt{META-INF/lib/shiro-core.jar} is your module's embedded\n library. The expression \\texttt{{[}0-9{]}*} helps the build tool match\n the library version to make available on the module's class path. The\n \\texttt{lib:=true} directive adds the embedded JAR to the module's\n class path via the \\texttt{Bundle-Classpath} manifest header.\n\\end{enumerate}\n\nLastly, if after embedding a library you get unresolved imports when\ntrying to deploy to Liferay, you might need to blacklist some imports:\n\n\\begin{verbatim}\nImport-Package:\\\n !foo.bar.baz,\\\n *\n\\end{verbatim}\n\nThe \\texttt{*} character represents all packages that the module refers\nto explicitly. Bnd detects the referenced packages.\n\nCongratulations! Resolving all of your module's package dependencies,\nespecially those from traditional Java libraries, is a quite an\naccomplishment.\n\n\\section{Related Topics}\\label{related-topics-2}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{Importing\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/exporting-packages}{Exporting\nPackages}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Creating\na Project}\n\n\\chapter{Understanding Excluded JARs}\\label{understanding-excluded-jars}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Module\\%20Framework}{Portal\nproperty \\texttt{module.framework.web.generator.excluded.paths}}\ndeclares JARs that are stripped from all Liferay DXP\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{generated\nWABs}. These JARs are excluded from web application bundles (WABs)\nbecause Liferay DXP provides them already. All JARs listed for this\nproperty are excluded from a WAB, even if the WAB lists the JAR in a\n\\texttt{portal-dependency-jars} property in its\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/liferay-plugin-package_7_2_0.properties.html}{\\texttt{liferay-plugin-package.properties}}\nfile.\n\nIf your WAR requires different versions of the packages Liferay DXP\nexports, you must include them in JARs named differently from the ones\n\\texttt{module.framework.web.generator.excluded.paths} excludes.\n\nFor example, Liferay DXP's\n\\href{https://github.com/liferay/liferay-portal/blob/7.2.x/modules/core/portal-bootstrap/system.packages.extra.bnd}{\\texttt{system.packages.extra}}\nmodule exports Spring Framework version 4.1.9 packages:\n\n\\begin{verbatim}\nExport-Package:\\\n ...\n org.springframework.*;version='4.1.9',\\\n ...\n\\end{verbatim}\n\nLiferay DXP uses the\n\\texttt{module.framework.web.generator.excluded.paths} portal property\nto exclude their JARs.\n\n\\begin{verbatim}\nmodule.framework.web.generator.excluded.paths=\\\n ...\n WEB-INF/lib/spring-aop.jar,\\\n WEB-INF/lib/spring-aspects.jar,\\\n WEB-INF/lib/spring-beans.jar,\\\n WEB-INF/lib/spring-context.jar,\\\n WEB-INF/lib/spring-context-support.jar,\\\n WEB-INF/lib/spring-core.jar,\\\n WEB-INF/lib/spring-expression.jar,\\\n WEB-INF/lib/spring-jdbc.jar,\\\n WEB-INF/lib/spring-jms.jar,\\\n WEB-INF/lib/spring-orm.jar,\\\n WEB-INF/lib/spring-oxm.jar,\\\n WEB-INF/lib/spring-tx.jar,\\\n WEB-INF/lib/spring-web.jar,\\\n WEB-INF/lib/spring-webmvc.jar,\\\n WEB-INF/lib/spring-webmvc-portlet.jar,\\\n ...\n\\end{verbatim}\n\nTo use a different Spring Framework version in your WAR, you must name\nthe corresponding Spring Framework JARs differently from the\nglob-patterned JARs\n\\texttt{module.framework.web.generator.excluded.paths} lists.\n\nFor example, to use Spring Framework version 3.0.7's Spring AOP JAR,\ninclude it in your plugin's \\texttt{WEB-INF/lib} but name it something\nother than \\texttt{spring-aop.jar}. Adding the version to the JAR name\n(i.e., \\texttt{spring-aop-3.0.7.RELEASE.jar}) differentiates it from the\nexcluded JAR and prevents it from being stripped from the WAB (the\nbundled WAR).\n\n\\section{Related Topics}\\label{related-topics-3}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/configuring-dependencies}{Configuring\nDependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Deploying\nWARs (WAB Generator)}\n\n\\chapter{Using the Felix Gogo Shell}\\label{using-the-felix-gogo-shell}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nThe Gogo shell provides a way to interact with Liferay DXP's module\nframework. You can\n\n\\begin{itemize}\n\\tightlist\n\\item\n dynamically install/uninstall bundles\n\\item\n examine package dependencies\n\\item\n examine extension points\n\\item\n list service references\n\\item\n etc.\n\\end{itemize}\n\nThere are two ways you can access the Gogo shell.\n\nThe recommended way to access the Gogo shell for a production\nenvironment is through the Control Panel. Accessing it there is the most\nsecure way to use the Gogo shell. You can set permissions in your\nLiferay DXP instance to only give certain people access to it. The Gogo\nshell is extremely powerful and should only be given to trusted admins,\nas you can manipulate the platform's core functionality. You can access\nthe Gogo shell in the Control Panel by navigating to\n\\emph{Configuration} → \\emph{Gogo Shell}.\n\nYou can also interact with Liferay DXP's module framework via a local\ntelnet session. This is only recommended when you're developing your\nLiferay DXP instance. This is not recommended for production\nenvironments.\n\nTo open the Gogo shell via telnet, execute the following command:\n\n\\begin{verbatim}\ntelnet localhost 11311\n\\end{verbatim}\n\nRunning this command requires a local running instance of Liferay DXP\nand your machine's telnet command line utilities enabled. You must also\nhave\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/using-developer-mode-with-themes\\#enabling-developer-mode-manually}{Developer\nMode enabled}.\n\nTo disconnect the session, execute the \\texttt{disconnect} command.\nAvoid using the following commands, which stop the OSGi framework:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{close}\n\\item\n \\texttt{exit}\n\\item\n \\texttt{shutdown}\n\\end{itemize}\n\nIf you have\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI}\ninstalled and the telnet capability enabled, you can run the Gogo shell\nvia Blade command too:\n\n\\begin{verbatim}\nblade sh \n\\end{verbatim}\n\nHere are some useful Gogo shell commands:\n\n\\texttt{b\\ {[}BUNDLE\\_ID{]}}: lists information about a specific bundle\nincluding the bundle's symbolic name, bundle ID, data root, registered\n(provided) and used services, imported and exported packages, and more\n\n\\texttt{diag\\ {[}BUNDLE\\_ID{]}}: lists information about why the\nspecified bundle is not working (e.g., unresolved dependencies, etc.)\n\n\\texttt{headers\\ {[}BUNDLE\\_ID{]}}: lists metadata about the bundle from\nthe bundle's \\texttt{MANIFEST.MF} file\n\n\\texttt{help}: lists all the available Gogo shell commands. Notice that\neach command has two parts to its name, separated by a colon. For\nexample, the full name of the \\texttt{help} command is\n\\texttt{felix:help}. The first part is the command scope while the\nsecond part is the command function. The scope allows commands with the\nsame name to be disambiguated. E.g., scope allows the\n\\texttt{felix:refresh} command to be distinguished from the\n\\texttt{equinox:refresh} command.\n\n\\texttt{help\\ {[}COMMAND\\_NAME{]}}: lists information about a specific\ncommand including a description of the command, the scope of the\ncommand, and information about any flags or parameters that can be\nsupplied when invoking the command.\n\n\\texttt{inspect\\ capability\\ service\\ {[}BUNDLE\\_ID{]}}: lists services\nexposed by a bundle\n\n\\texttt{install\\ {[}PATH\\_TO\\_JAR\\_FILE{]}}: installs the specified\nbundle into Liferay's module framework\n\n\\texttt{lb}: lists all of the bundles installed in Liferay's module\nframework. Use the \\texttt{-s} flag to list the bundles using the\nbundles' symbolic names.\n\n\\texttt{packages\\ {[}PACKAGE\\_NAME{]}}: lists all of the named package's\ndependencies\n\n\\texttt{scr:list}: lists all of the components registered in the module\nframework (\\emph{scr} stands for service component runtime)\n\n\\texttt{scr:info\\ {[}COMPONENT\\_NAME{]}}: lists information about a\nspecific component including the component's description, services,\nproperties, configuration, references, and more.\n\n\\texttt{services}: lists all of the services that have been registered\nin Liferay's module framework\n\n\\texttt{start\\ {[}BUNDLE\\_ID{]}}: starts the specified bundle\n\n\\texttt{stop\\ {[}BUNDLE\\_ID{]}}: stops the specified bundle\n\n\\texttt{uninstall\\ {[}BUNDLE\\_ID{]}}: uninstalls the specified bundle\nfrom Liferay's module framework. This does not remove the specified\nbundle from Liferay's module framework; it's hidden from Gogo's\n\\texttt{lb} command, but is still present. Adding a new version of the\nuninstalled bundle, therefore, will not reinstall it; it will update the\ncurrently hidden uninstalled version. To remove a bundle from Liferay's\nmodule framework permanently, manually delete it from the\n\\texttt{LIFERAY\\_HOME/osgi} folder. For more information on the\n\\texttt{uninstall} command, see OSGi's\n\\href{https://osgi.org/javadoc/r6/core/org/osgi/framework/Bundle.html\\#uninstall()}{uninstall}\ndocumentation.\n\nFor more information about the Gogo shell, visit\n\\href{http://felix.apache.org/documentation/subprojects/apache-felix-gogo.html}{Apache's\nofficial documentation}.\n\n\\chapter{Importing Packages}\\label{importing-packages}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nPlugins often must use Java classes from packages outside of themselves.\nAnother OSGi bundle (a module or an OSGi Web Application Bundle) in the\nOSGi framework must\n\\href{/docs/7-2/customization/-/knowledge_base/c/exporting-packages}{export}\na package for your plugin to import it.\n\nWhen an OSGi bundle (bundle) is set up to import packages, the OSGi\nframework finds other registered bundles that export the needed packages\nand wires them to the importing bundle. At run time, the importing\nbundle gets the class from the wired bundle that exports the class's\npackage.\n\nFor this to happen, a bundle's \\texttt{META-INF/MANIFEST.MF} file must\nspecify the\n\\href{https://bnd.bndtools.org/heads/import_package.html}{\\texttt{Import-Package}}\nOSGi manifest header with a comma-separated list of the Java packages it\nneeds. For example, if a bundle needs classes from the\n\\texttt{javax.portlet} and \\texttt{com.liferay.portal.kernel.util}\npackages, it must specify them like so:\n\n\\begin{verbatim}\nImport-Package: javax.portlet,com.liferay.portal.kernel.util,*\n\\end{verbatim}\n\nThe \\texttt{*} character represents all packages that the module refers\nto explicitly. Bnd detects the referenced packages.\n\nImport packages must sometimes be specified manually, but not always.\nConveniently, Liferay DXP\n\\href{/docs/7-2/reference/-/knowledge_base/r/project-templates}{project\ntemplates} and\n\\href{/docs/7-2/reference/-/knowledge_base/r/tooling}{tools}\nautomatically detect the packages a bundle uses and add them to the\npackage imports in the bundle's manifest. Here are the different package\nimport scenarios:\n\n\\begin{itemize}\n\\item\n \\hyperref[automatic-package-import-generation]{Automatic Package\n Import Generation}\n\\item\n \\hyperref[manually-adding-package-imports]{Manually Adding Package\n Imports}\n\\end{itemize}\n\nLet's explore how package imports are specified in these scenarios.\n\n\\section{Automatic Package Import\nGeneration}\\label{automatic-package-import-generation}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/project-templates}{Gradle\nand Maven module projects} created using\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI},\n\\href{/docs/7-2/reference/-/knowledge_base/r/maven}{Liferay's Maven\narchetypes}, or\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP} use \\href{http://bnd.bndtools.org/}{bnd}. On building\nsuch a project's module JAR, bnd detects the packages the module uses\nand generates a \\texttt{META-INF/MANIFEST.MF} file whose\n\\texttt{Import-Package} header specifies the packages.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Liferay's Maven module archetypes use the\n\\texttt{bnd-maven-plugin}. Liferay's Gradle module project templates use\n\\href{https://github.com/TomDmitriev/gradle-bundle-plugin}{a third-party\nGradle plugin} to invoke bnd.\n\n\\noindent\\hrulefill\n\nFor example, suppose you're developing a Liferay module using Maven or\nGradle. In most cases, you specify your module's dependencies in your\n\\texttt{pom.xml} or \\texttt{build.gradle} file. At build time, the Maven\nor Gradle module plugin reads your \\texttt{pom.xml} or\n\\texttt{build.gradle} file and bnd adds the required\n\\texttt{Import-Package} headers to your module JAR's\n\\texttt{META-INF/MANIFEST.MF}.\n\nHere's an example dependencies section from a module's\n\\texttt{build.gradle} file:\n\n\\begin{verbatim}\ndependencies {\n compileOnly group: \"com.liferay.portal\", name: \"com.liferay.portal.kernel\", version: \"2.0.0\"\n compileOnly group: \"javax.portlet\", name: \"portlet-api\", version: \"2.0\"\n compileOnly group: \"org.osgi\", name: \"org.osgi.service.component.annotations\", version: \"1.3.0\"\n}\n\\end{verbatim}\n\nAnd here's the \\texttt{Import-Package} header that's generated in the\nmodule JAR's \\texttt{META-INF/MANIFEST.MF} file:\n\n\\begin{verbatim}\nImport-Package: com.liferay.portal.kernel.portlet.bridges.mvc;version=\n\"[1.0,2)\",com.liferay.portal.kernel.util;version=\"[7.0,8)\",javax.nami\nng,javax.portlet;version=\"[2.0,3)\",javax.servlet,javax.servlet.http,j\navax.sql\n\\end{verbatim}\n\nNote that your build file need only specify artifact dependencies. bnd\nexamines your module's class path to determine which packages from those\nartifacts contain classes your application uses and imports the\npackages. The examination includes all classes found in the class\npath--even those from embedded\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{third\nparty library JARs}.\n\nRegarding classes used by a plugin WAR,\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Liferay's\nWAB Generator} detects their use in the WAR's JSPs, descriptor files,\nand classes (in \\texttt{WEB-INF/classes} and embedded JARs). The WAB\nGenerator searches the \\texttt{web.xml}, \\texttt{liferay-web.xml},\n\\texttt{portlet.xml}, \\texttt{liferay-portlet.xml}, and\n\\texttt{liferay-hook.xml} descriptor files. It adds package imports for\nclasses that are neither found in the plugin's \\texttt{WEB-INF/classes}\nfolder nor in its embedded JARs.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Packages for Java APIs, such as Java Portlet, aren't\nsemantically versioned but have Portable Java Contracts. Each API's\ncontract specifies the JSR it satisfies. Bundles that use these APIs\nmust specify requirements on the API contracts. The contract requirement\nspecifies your bundle's relationship with the imported API packages. If\nthe system you're running does \\emph{not} provide the exact contract,\nyour bundle does not resolve. Resolving the missing package is better\nthan handling an incompatibility failure during execution.\n\n\\begin{itemize}\n\\item\n \\textbf{Blade CLI and Liferay Dev Studio DXP module projects} specify\n Portable Java Contracts automatically! For example, if your Blade CLI\n or Liferay Dev Studio DXP module uses the Java Portlet API and you\n compile against the Java Portlet 2.0 artifact, a contract requirement\n for the package is added to your module's manifest.\n\\item\n \\textbf{Module projects that use bnd but are not created using Blade\n CLI or Liferay Dev Studio DXP} must specify contracts in their\n \\texttt{bnd.bnd} file. For example, here are contract instructions for\n Java Portlet and Java Servlet APIs:\n\n\\begin{verbatim}\n-contract: JavaPortlet,JavaServlet\n\\end{verbatim}\n\n At build time, bnd adds the contract instructions to your module's\n manifest. It adds a requirement for the first version of the API found\n in your classpath and \\emph{removes} version range information from\n \\texttt{Import-Package} entries for corresponding API packages---the\n package version information isn't needed.\n\\item\n \\textbf{Projects that don't use bnd} must specify contracts in their\n OSGi bundle manifest. For example, here's the specified contract for\n \\texttt{JavaPortlet} 2.0, which goes in your\n \\texttt{META-INF/MANIFEST.MF} file:\n\n\\begin{verbatim}\nImport-Package: javax.portlet\nRequire-Capability: osgi.contract;filter:=(&(osgi.contract=JavaPortlet)(version=2.0))\n\\end{verbatim}\n\\end{itemize}\n\nFor Portable Java Contract details, see\n\\href{https://www.osgi.org/portable-java-contract-definitions/}{Portable\nJava Contract Definitions}.\n\n\\noindent\\hrulefill\n\n\\section{Manually Adding Package\nImports}\\label{manually-adding-package-imports}\n\nThe WAB Generator and bnd don't add package imports for classes\nreferenced in these places:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Unrecognized descriptor file\n\\item\n Custom or unrecognized descriptor element or attribute\n\\item\n Reflection code\n\\item\n Class loader code\n\\end{itemize}\n\nIn such cases, you must manually determine these packages and specify an\n\\texttt{Import-Package} OSGi header that includes these packages and the\npackages that Bnd detects automatically. The \\texttt{Import-Package}\nheader belongs in the location appropriate to your project type:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.2727}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 2\\tabcolsep) * \\real{0.7273}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nProject type\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\texttt{Import-Package} header location\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\nModule (uses bnd) & \\texttt{{[}project{]}/bnd.bnd} \\\\\nModule (doesn't use bnd) &\n\\texttt{{[}module\\ JAR{]}/META-INF/MANIFEST.MF} \\\\\nTraditional Liferay plugin WAR &\n\\texttt{WEB-INF/liferay-plugin-package.properties} \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\nHere's an example of adding a package called\n\\texttt{com.liferay.docs.foo} to the list of referenced packages that\nBnd detects automatically:\n\n\\begin{verbatim}\nImport-Package:\\\n com.liferay.docs.foo,\\\n *\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{WAB\nGenerator} refrains from adding WAR project embedded third-party JARs to\na WAB if\n\\href{/docs/7-2/customization/-/knowledge_base/c/understanding-excluded-jars}{Liferay\nDXP already exports the JAR's packages}.\n\nIf your WAR requires a different version of a third-party package that\nLiferay DXP exports, specify that package in your\n\\texttt{Import-Package:} list. Then if the package provider is an OSGi\nmodule, publish its exported packages by deploying the module. If the\npackage provider is not an OSGi module, follow the instructions for\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{adding\nthird-party libraries}.\n\n\\noindent\\hrulefill\n\nPlease see the\n\\href{https://bnd.bndtools.org/heads/import_package.html}{\\texttt{Import-Package}}\nheader documentation for more information.\n\nCongratulations! Now you can import all kinds of packages for your\nmodules and plugins to use.\n\n\\section{Related Topics}\\label{related-topics-4}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/configuring-dependencies}{Configuring\nDependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Deploying\nWARs (WAB Generator)}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/project-templates}{Project\nTemplates}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/maven}{Liferay's Maven\nArchetypes}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP}\n\n\\chapter{Exporting Packages}\\label{exporting-packages}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\nAn OSGi bundle's Java packages are private by default. To expose a\npackage, you must explicitly export it. This way you share only the\nclasses you want to share. Exporting a package in your OSGi bundle\n(bundle) manifest makes all the package's classes available for other\nbundles to\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{import}.\n\nTo export a package, add it to your module's or plugin's\n\\texttt{Export-Package} OSGi header. A header exporting\n\\texttt{com.liferay.petra.io} and \\texttt{com.liferay.petra.io.unsync}\nwould look like this:\n\n\\begin{verbatim}\nExport-Package:\\\ncom.liferay.petra.io,\\\ncom.liferay.petra.io.unsync\n\\end{verbatim}\n\nThe correct location for the header depends on your project's type:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}ll@{}}\n\\toprule\\noalign{}\nProject Type & \\texttt{Export-Package} header location \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\nModule JAR (uses bnd) & \\texttt{{[}project{]}/bnd.bnd} \\\\\nModule JAR (doesn't use bnd) &\n\\texttt{{[}module\\ JAR{]}/META-INF/MANIFEST.MF} \\\\\nPlugin WAR & \\texttt{WEB-INF/liferay-plugin-package.properties} \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\nModule projects created using\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI},\n\\href{/docs/7-2/reference/-/knowledge_base/r/maven}{Liferay's Maven\narchetypes}, or\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP} use \\href{http://bnd.bndtools.org/}{bnd}. On building\nsuch a project's module JAR, bnd propagates the OSGi headers from the\nproject's \\texttt{bnd.bnd} file to the JAR's\n\\texttt{META-INF/MANIFEST.MF}.\n\nIn module projects that don't use bnd, you must manually add package\nexports to an \\texttt{Export-Package} header in the module JAR's\n\\texttt{META-INF/MANIFEST.MF}.\n\nIn plugin WAR projects, you must add package exports to an\n\\texttt{Export-Package} header in the project's\n\\texttt{WEB-INF/liferay-plugin-package.properties}. On copying the WAR\ninto the \\texttt{{[}Liferay\\ Home{]}/deploy} folder, the\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{WAB\nGenerator} propagates the OSGi headers from the WAR's\n\\texttt{liferay-plugin-package.properties} file to the\n\\texttt{META-INF/MANIFEST.MF} file in the generated Web Application\nBundle (WAB).\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} bnd makes a module's exported packages\n\\emph{substitutable}. That is, the OSGi framework can substitute your\nmodule's exported package with a compatible package of the same name,\nbut potentially different version, that's exported from a different OSGi\nbundle. bnd enables this for your module by automatically making your\nmodule import every package it exports. In this way, your module can\nwork on its own, but can also work in conjunction with bundles that\nprovide a different (compatible) version, or even the same version, of\nthe package. A package from another bundle might provide better\n``wiring'' opportunities with other bundles.\n\\href{http://blog.osgi.org/2007/04/importance-of-exporting-nd-importing.html}{Peter\nKriens' blog post} provides more details on how substitutable exports\nworks.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Don't export the same package from different JARs.\nMultiple exports of the same package leads to ``split package'' issues,\nwhose side affects differ from case to case.\n\n\\noindent\\hrulefill\n\nNow you can share your module's or plugin's terrific {[}EDITOR: or\nterrible!{]} packages with other OSGi bundles!\n\n\\section{Related Topics}\\label{related-topics-5}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/configuring-dependencies}{Configuring\nDependencies}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/deploying-wars-wab-generator}{Deploying\nWARs (WAB Generator)}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/project-templates}{Project\nTemplates}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/maven}{Liferay's Maven\nArchetypes}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/semantic-versioning}{Semantic\nVersioning}\n\n\\chapter{Semantic Versioning}\\label{semantic-versioning}\n\n{ This document has been updated and ported to Liferay Learn and is no\nlonger maintained here.}\n\n\\href{https://semver.org}{Semantic Versioning} is a three tiered\nversioning system that increments version numbers based on the type of\nAPI change introduced to a releasable software component. It's a\nstandard way of communicating programmatic compatibility of a package or\nmodule for dependent consumers and API implementations. If a package is\nprogrammatically (i.e., semantically) incompatible with a project,\n\\href{http://bnd.bndtools.org}{bnd} (used when building\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Liferay\ngenerated module projects}) fails that project's build immediately.\n\nThe semantic version format looks like this:\n\n\\begin{verbatim}\nMAJOR.MINOR.MICRO\n\\end{verbatim}\n\nCertain events force each tier to increment:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\emph{MAJOR:} an incompatible, API-breaking change is made\n\\item\n \\emph{MINOR:} a change that affects only providers of the API, or new\n backwards- compatible functionality is added\n\\item\n \\emph{MICRO:} a backwards-compatible bug fix is made\n\\end{itemize}\n\nFor more details on semantic versioning, see the official\n\\href{https://semver.org/}{Semantic Versioning} site and\n\\href{http://www.osgi.org/wp-content/uploads/SemanticVersioning1.pdf}{OSGi\nAlliance's Semantic Versioning} technical whitepaper.\n\nAll of Liferay DXP's modules use Semantic Versioning.\n\nFollowing Semantic Versioning is especially important because Liferay\nDXP is a modular platform containing hundreds of independent OSGi\nmodules. With many independent modules containing a slew of\ndependencies, releasing new package versions can quickly become\nterrifying. With this complex intertwined system of dependencies, you\nmust meticulously manage your own project's API versions to ensure\ncompatibility for those who leverage it. With Semantic Versioning's\nstraightforward system and the help of\n\\href{/docs/7-2/reference/-/knowledge_base/r/tooling}{Liferay tooling},\nmanaging your module project's versions is easy.\n\n\\section{Baselining Your Project}\\label{baselining-your-project}\n\nFollowing Semantic Versioning manually seems deceptively easy. There's a\nsad history of good-intentioned developers updating their projects'\nsemantic versions manually, only to find out later they made a mistake.\nThe truth is, it's hard to anticipate the ramifications of a simple\nupdate. To avoid this, you can \\emph{baseline} your project after it has\nbeen updated. Baselining verifies that the Semantic Versioning rules are\nobeyed by your project. This can catch many obvious API changes that are\nnot so obvious to humans. Care must always be taken, however, when\nmaking any kind of code change because this tool is not smart enough to\nidentify compatibility changes not represented in the signatures of Java\nclasses or interfaces, or in API \\emph{use} changes (e.g., assumptions\nabout method call order, or changes to input and/or output encoding).\nBaseline, as the name implies, does give you a certain measure of\n\\emph{baseline} comfort that a large class of compatibility issues won't\nsneak past you.\n\nYou can use Liferay's Baseline Gradle plugin to provide baselining\ncapabilities. Add it to your Gradle build configuration and execute the\nfollowing command:\n\n\\begin{verbatim}\n./gradlew baseline\n\\end{verbatim}\n\nSee the\n\\href{/docs/7-2/reference/-/knowledge_base/r/baseline-gradle-plugin}{Baseline\nGradle Plugin} article for configuration details. This plugin is not\nprovided in\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace} by default.\n\nWhen you run the \\texttt{baseline} command, the plugin baselines your\nnew module against the latest released non-snapshot module (i.e., the\nbaseline). That is, it compares the public exported API of your new\nmodule with the baseline. If there are any changes, it uses the OSGi\nSemantic Versioning rules to calculate the minimum new version. If your\nnew module has a lower version, errors are thrown.\n\nWith baselining, your project's Semantic Versioning is as accurate as\nits API expresses.\n\n\\section{Managing Artifact and Dependency\nVersions}\\label{managing-artifact-and-dependency-versions}\n\nThere are two ways to track your project's artifact and dependency\nversions with Semantic Versioning:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Range of versions\n\\item\n Exact version (one-to-one)\n\\end{itemize}\n\nYou should track a range of versions if you intend to build your project\nfor multiple versions of Liferay DXP and maintain maximum compatibility.\nIn other words, if several versions of a package work for an app, you\ncan configure the app to use any of them. What's more, bnd automatically\ndetermines the semantically compatible range of each package a module\ndepends on and records the range to the module's manifest.\n\nFor help with version range syntax, see the\n\\href{https://osgi.org/specification/osgi.core/7.0.0/framework.module.html\\#i3189032}{OSGi\nSpecifications}.\n\nA version range for imported packages in an OSGi bundle's\n\\texttt{bnd.bnd} looks like this:\n\n\\begin{verbatim}\nImport-Package: com.liferay.docs.test; version=\"[1.0.0,2.0.0)\"\n\\end{verbatim}\n\nPopular build tools also follow this syntax. In Gradle, a version range\nfor a dependency looks like this:\n\n\\begin{verbatim}\ncompile group: \"com.liferay.portal\", name: \"com.liferay.portal.test\", version: \"[1.0.0,2.0.0)\"\n\\end{verbatim}\n\nIn Maven, it looks like this:\n\n\\begin{verbatim}\ncom.liferay.portal\ncom.liferay.portal.test\n[1.0.0,2.0.0)\n\\end{verbatim}\n\nSpecifying the latest release version can also be considered a range of\nversions with no upper limit. For example, in Gradle, it's specified as\n\\texttt{version:\\ \"latest.release\"}. This can be done in Maven 2.x with\nthe usage of the version marker \\texttt{RELEASE}. This is not possible\nif you're using Maven 3.x. See \\href{https://gradle.org/docs}{Gradle}\nand \\href{http://maven.apache.org/guides/}{Maven}'s respective docs for\nmore information.\n\nTracking a range of versions comes with a price. It's hard to reproduce\nold builds when you're debugging an issue. It also comes with the risk\nof differing behaviors depending on the version used. Also, relying on\nthe latest release could break compatibility with your project if a\nmajor change is introduced. You should proceed with caution when\nspecifying a range of versions and ensure your project is tested on all\nincluded versions.\n\nTracking a dependency's exact version is much safer, but is less\nflexible. This might limit you to a specific version of Liferay DXP. You\nwould also be locked in to APIs that only exist for that specific\nversion. This means your module is much easier to test and has less\nchance for unexpected failures.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} When specifying package versions in your \\texttt{bnd.bnd}\nfile, exact versions are typically specified like this:\n\\texttt{version=\"1.1.2\"}. However, this syntax is technically a range;\nit is interpreted as {[}1.1.2, ∞). Therefore, if a higher version of the\npackage is available, it's used instead of the version you specified.\nFor these cases, it may be better to specify a version range for\ncompatible versions that have been tested. If you want to specify a true\nexact match, the syntax is like this: \\texttt{{[}1.1.2{]}}. See the\n\\href{https://osgi.org/specification/osgi.core/7.0.0/framework.module.html\\#i3189032}{Version\nRange} section in the OSGi specifications for more info.\n\nGradle and Maven use exact versions when only one version is specified.\n\n\\noindent\\hrulefill\n\nYou now know the pros and cons for tracking dependencies as a range and\nas an exact match.\n\n\\section{Related Topics}\\label{related-topics-6}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/importing-packages}{Importing\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/exporting-packages}{Exporting\nPackages}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/configuring-dependencies}{Configuring\nDependencies}\n\n\\chapter{Deploying WARs (WAB\nGenerator)}\\label{deploying-wars-wab-generator}\n\nYou can create applications for Liferay DXP as Java EE-style Web\nApplication ARchive (WAR) artifacts or as Java ARchive (JAR) OSGi bundle\nartifacts. Bean Portlets, PortletMVC4Spring Portlets, and JSF Portlets\nmust be packaged as WAR artifacts because their frameworks are designed\nfor Java EE. Therefore, they expect a WAR layout and require Java EE\nresources such as the \\texttt{WEB-INF/web.xml} descriptor.\n\nLiferay provides a way for these WAR-styled plugins to be deployed and\ntreated like OSGi modules by Liferay's OSGi runtime. They can be\nconverted to \\emph{WABs}.\n\nLiferay DXP supports the OSGi Web Application Bundle (WAB) standard for\ndeployment of Java EE style WARs. Simply put, a WAB is an archive that\nhas a WAR layout and contains a \\texttt{META-INF/MANIFEST.MF} file with\nthe \\texttt{Bundle-SymbolicName} OSGi directive. A WAB is an OSGi\nbundle. Although the project source has a WAR layout, the artifact\nfilename may end with either the \\texttt{.jar} or \\texttt{.war}\nextension.\n\nLiferay only supports the use of WABs that have been auto-generated by\nthe WAB Generator. The WAB Generator transforms a traditional WAR-style\nplugin into a WAB during deployment. So what exactly does the WAB\nGenerator do to a WAR file to transform it into a WAB?\n\nThe WAB Generator detects packages referenced in the plugin WAR's JSPs,\ndescriptor files, and classes (in \\texttt{WEB-INF/classes} and embedded\nJARs). The descriptor files include \\texttt{web.xml},\n\\texttt{liferay-web.xml}, \\texttt{portlet.xml},\n\\texttt{liferay-portlet.xml}, and \\texttt{liferay-hook.xml}. The WAB\nGenerator verifies whether the detected packages are in the plugin's\n\\texttt{WEB-INF/classes} folder or in an embedded JAR in the\n\\texttt{WEB-INF/lib} folder. Packages that aren't found in either\nlocation are added to an \\texttt{Import-Package} OSGi header in the\nWAB's \\texttt{META-INF/MANIFEST.MF} file.\n\nTo import a package that is only referenced in the following types of\nlocations, you must add an \\texttt{Import-Package} OSGi header to the\nplugin's \\texttt{WEB-INF/liferay-plugin-package.properties} file and add\nthe package to that header's list of values.\n\n\\begin{itemize}\n\\tightlist\n\\item\n Unrecognized descriptor file\n\\item\n Custom or unrecognized descriptor element or attribute\n\\item\n Reflection code\n\\item\n Class loader code\n\\end{itemize}\n\n\\section{WAR versus WAB Structure}\\label{war-versus-wab-structure}\n\nThe WAB folder structure and WAR folder structure differ. Consider the\nfollowing folder structure of a WAR-style portlet.\n\n\\textbf{WAR}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{my-war-portlet}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java}\n \\item\n \\texttt{webapp}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{WEB-INF}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{classes}\n \\item\n \\texttt{lib}\n \\item\n \\texttt{resources}\n \\item\n \\texttt{views}\n \\item\n \\texttt{liferay-display.xml}\n \\item\n \\texttt{liferay-plugin-package.properties}\n \\item\n \\texttt{liferay-portlet.xml}\n \\item\n \\texttt{portlet.xml}\n \\item\n \\texttt{web.xml}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n\\end{itemize}\n\nWhen a WAR-style portlet is deployed to Liferay DXP and processed by the\nWAB Generator, the portlet's folder structure is transformed.\n\n\\textbf{WAB}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{my-war-portlet-that-is-now-a-wab}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{META-INF}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{MANIFEST.MF}\n \\end{itemize}\n \\item\n \\texttt{WEB-INF}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{classes}\n \\item\n \\texttt{lib}\n \\item\n \\texttt{resources}\n \\item\n \\texttt{views}\n \\item\n \\texttt{liferay-display.xml}\n \\item\n \\texttt{liferay-plugin-package.properties}\n \\item\n \\texttt{liferay-portlet.xml}\n \\item\n \\texttt{portlet.xml}\n \\item\n \\texttt{web.xml}\n \\end{itemize}\n \\end{itemize}\n\\end{itemize}\n\nThe major difference is the addition of the\n\\texttt{META-INF/MANIFEST.MF} file. The WAB Generator automatically\ngenerates an OSGi-ready manifest file. If you want to affect the content\nof the manifest file, you can place bnd directives and OSGi headers\ndirectly into your plugin's \\texttt{liferay-plugin-package.properties}\nfile.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} Adding a \\texttt{bnd.bnd} file or a build-time plugin\n(e.g., \\texttt{bnd-maven-plugin}) to your WAR plugin is pointless,\nbecause the generated WAB cannot use them.\n\n\\noindent\\hrulefill\n\n\\section{Deploying a WAR}\\label{deploying-a-war}\n\nTo deploy a WAB based on your WAR plugin, copy your WAR plugin to your\nLiferay DXP instance's \\texttt{deploy/} folder in your\n\\href{/docs/7-2/deploy/-/knowledge_base/d/liferay-home}{\\texttt{{[}Liferay\\ Home{]}}}.\n\n\\section{Saving a Copy of the WAB}\\label{saving-a-copy-of-the-wab}\n\nOptionally, save the WAB to a local folder. This gives you the\nopportunity to inspect the generated WAB. To store generated WABs, add\nthe following portal properties to a\n\\texttt{{[}Liferay\\ Home{]}/portal-ext.properties} file. Then restart\nLiferay DXP:\n\n\\begin{verbatim}\nmodule.framework.web.generator.generated.wabs.store=true\nmodule.framework.web.generator.generated.wabs.store.dir=${module.framework.base.dir}/wabs\n\\end{verbatim}\n\nThese properties instruct the WAB generator to store generated WABs in\nyour Liferay instance's \\texttt{osgi/wabs/} folder. The generated WABs\nhave the same structure as the example WAB structure listed above. The\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Module\\%20Framework\\%20Web\\%20Application\\%20Bundles}{Module\nFramework Web Application Bundles} properties section explains more\ndetails.\n\nAwesome! You have deployed your WAR plugin as a WAB and you know how to\nsave a copy of the WAB to examine it!\n\n\\section{Related Topics}\\label{related-topics-7}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Creating\na Project}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{Deploying\na Project}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/web-front-ends}{Developing Web\nFront-Ends}\n\n\\chapter{Architecture}\\label{architecture}\n\nLiferay DXP architecture comprises these parts:\n\n\\textbf{Core:} Bootstraps Liferay DXP and its frameworks. The Core\nprovides a runtime environment for managing services, UI components, and\ncustomizations.\n\n\\textbf{Services:} Liferay and custom functionality is exposed via Java\nAPIs and web APIs.\n\n\\textbf{UI:} The optional web application UI for adding portals, sites,\npages, widgets, and content.\n\nYou can use the Liferay DXP UI and services together or focus solely on\nusing services via\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/headless-rest-apis}{REST\nweb APIs}.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/architecture-options.png}\n\\caption{Liferay DXP portals and Sites contain content and widgets.\nLiferay DXP can also be used ``headless''---without the UI.}\n\\end{figure}\n\nThe architecture satisfies these requirements:\n\n\\begin{itemize}\n\\item\n Supports using common development technologies\n\\item\n Leverages development standards\n\\item\n Facilitates swapping components\n\\item\n Starts fast and performs well\n\\item\n Its runtime is easy to configure and inspect\n\\end{itemize}\n\nThe Core supports UI and service deployments and orchestrates wiring\nthem together.\n\n\\section{Core}\\label{core}\n\nLiferay DXP is a web application that runs on your application server.\nThe Core bootstraps the application and\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/frameworks}{Liferay's\nbuilt-in frameworks}.\n\nThere are frameworks for these things and more:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/adaptive-media}{Adaptive\n Media}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/configurable-applications}{Application\n Configuration}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/application-security}{Application\n Security}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/asset-framework}{Asset\n Framework}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/documents-and-media-api}{File\n Management}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{Localization}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/search}{Search}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/segmentation-personalization}{Segmentation\n and Personalization}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/upgrade-processes}{Upgrade\n Processes}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/page-fragments}{Web\n Fragments}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/the-workflow-framework}{Workflow}\n\\end{itemize}\n\nThe Core provides the component runtime environment for the frameworks,\nservices, and UI. Here are some component examples:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Services}\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{Service\n customizations}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{Portlets}\n (templates, controllers, and resources)\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/web-front-ends}{JavaScript\n applications} (templates, routers, and resources)\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{JSP\n customization via Portlet Filters}\n\\item\n \\href{(/docs/7-2/frameworks/-/knowledge_base/f/themes-introduction)}{Theme}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/creating-a-language-module}{Shared\n Language Keys}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/screen-navigation-framework}{Navigation\n components}\n\\end{itemize}\n\nThe following figure shows these component types in the runtime\nenvironment.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/component-runtime-environment.png}\n\\caption{The Core provides a runtime environment for components, such as\nthe ones here. New component implementations can extend or replace\nexisting implementations dynamically.}\n\\end{figure}\n\nThe runtime environment supports adding, replacing, and customizing\ncomponents on-the-fly. This makes the following scenarios possible:\n\n\\textbf{Replacement:} If the \\texttt{ServiceC\\ Impl\\ 2} component has a\nhigher ranking than existing component \\texttt{ServiceC\\ Impl\\ 1},\n\\texttt{ServiceC\\ Impl\\ 2} is used in its place.\n\n\\textbf{Customization:} The \\texttt{PortletA\\ Filter} intercepts and\nmodifies requests to and responses from \\texttt{PortletA}, affecting the\ncontent \\texttt{PortletA} displays.\n\nComponent WAR and module JAR projects install as\n\\href{https://www.osgi.org/}{OSGi bundles} (modules). Liferay DXP's OSGi\nframework defines the module lifecycle, enforces dependencies, defines\nthe class loading structure, and provides an API and CLI\n(\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Felix\nGogo Shell}) for managing modules and components. The Core is configured\nvia \\href{/docs/7-2/deploy/-/knowledge_base/d/portal-properties}{portal\nproperties files} and\n\\href{/docs/7-2/user/-/knowledge_base/u/server-administration}{Server\nAdministration panels}.\n\nThe service components provide business functionality.\n\n\\section{Services}\\label{services}\n\nBusiness logic is implemented in services deployed to the component\nruntime environment. Built-in Core services and framework services\noperate on Liferay models such as Users, Roles, Web Content, Documents\nand Media, and more. You can write and deploy custom services to\nintroduce new models and functionality. Service components can access\neach other in Liferay DXP via\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{dependency\ninjection}.\n\nFront-end applications invoke the services to do work. You can deploy\nJava-based applications that call services directly using the\n\\href{/docs/7-2/reference/-/knowledge_base/r/java-apis}{Java APIs}, and\nany web-based (Java and non-Java) application, whether deployed on\nLiferay DXP or not, can use the web APIs, which include\n\\href{/docs/7-2/appdev/-/knowledge_base/a/generating-apis-with-rest-builder}{headless\nREST APIs} that conform to the\n\\href{https://swagger.io/docs/specification/about/}{OpenAPI} standard\nand include\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/web-services}{plain\nweb/REST services}. The following figure shows Liferay DXP applications\nand external clients invoking Liferay services.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/apps-invoking-services.png}\n\\caption{Remote and Liferay DXP applications can invoke services via\nREST web APIs. Liferay DXP Java-based portlets can also invoke services\nvia Java APIs.}\n\\end{figure}\n\nLiferay services are built using\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder} and made REST-ful using\n\\href{/docs/7-2/appdev/-/knowledge_base/a/rest-builder}{REST Builder}.\nThe services are easy to\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-osgi-services}{override\nand extend} too.\n\nLiferay DXP also provides a web-based UI, which makes content and\nservice functionality available in browsers.\n\n\\section{UI}\\label{ui}\n\n\\href{/docs/7-2/user/-/knowledge_base/u/the-liferay-distinction}{Liferay\nDXP's UI} helps people do work,\n\\href{/docs/7-2/user/-/knowledge_base/u/collaboration}{collaborate}, and\n\\href{/docs/7-2/user/-/knowledge_base/u/web-experience-management}{enjoy\ncontent}. The UI consists of\n\n\\begin{itemize}\n\\item\n \\href{/docs/7-2/user/-/knowledge_base/u/the-liferay-distinction}{Liferay\n DXP application}: The web application for managing Portals, Sites,\n Users, Pages, Widgets, and more.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/application-development}{Applications}:\n Widgets that provide a user interface for services already deployed.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/themes-introduction}{Themes}:\n Plugins for styling Sites with a unique look and feel.\n\\end{itemize}\n\nThe UI concepts article digs deeper into developing and customizing UI\ncomponents.\n\nAs you can see, the Liferay DXP architecture supports developing\nservices, UI components, and customizations. The architecture section\ncovers Core, service, and UI topics. Next, we dive into the Core to\ndescribe class loading, modularity, and more. But you can jump ahead to\nany service or UI architecture topics, if you like. Enjoy exploring the\nLiferay DXP architecture!\n\n\\chapter{Liferay Portal Classloader\nHierarchy}\\label{liferay-portal-classloader-hierarchy}\n\nAll Liferay DXP applications live in its OSGi container. Portal is a web\napplication deployed on your application server. Portal's Module\nFramework bundles (modules) live in the OSGi container and have\nclassloaders. All the classloaders from Java's Bootstrap classloader to\nclassloaders for bundle classes and JSPs are part of a hierarchy.\n\nThis article explains Liferay's classloader hierarchy and describes how\nit works in the following contexts:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Web application, such as Liferay Portal, deployed on the app server\n\\item\n OSGi bundle deployed in the Module Framework\n\\end{itemize}\n\nThe following diagram shows Liferay DXP's classloader hierarchy.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-classloader-hierarchy.png}\n\\caption{0: Here is Liferay's classloader hierarchy.}\n\\end{figure}\n\nHere are the classloader descriptions:\n\n\\begin{itemize}\n\\item\n \\textbf{Bootstrap}: The JRE's classes (from packages \\texttt{java.*})\n and Java extension classes (from \\texttt{\\$JAVA\\_HOME/lib/ext}). No\n matter the context, loading all \\texttt{java.*} classes is delegated\n to the Bootstrap classloader.\n\\item\n \\textbf{System}: Classes configured on the \\texttt{CLASSPATH} and or\n passed in via the application server's Java classpath (\\texttt{-cp} or\n \\texttt{-classpath}) parameter.\n\\item\n \\textbf{Common}: Classes accessible globally to web applications on\n the application server.\n\\item\n \\textbf{Web Application}: Classes in the application's\n \\texttt{WEB-INF/classes} folder and \\texttt{WEB-INF/lib/*.jar}.\n\\item\n \\textbf{Module Framework}: Liferay's OSGi module framework classloader\n which is used to provide controlled isolation for the module framework\n bundles.\n\\item\n \\textbf{bundle}: Classes from a bundle's packages or from packages\n other bundles export.\n\\item\n \\textbf{JSP}: A classloader that aggregates the following bundle and\n classloaders:\n\n \\begin{itemize}\n \\tightlist\n \\item\n Bundle that contains the JSPs' classloader\n \\item\n JSP servlet bundle's classloader\n \\item\n Javax Expression Language (EL) implementation bundle's classloader\n \\item\n Javax JSTL implementation bundle's classloader\n \\end{itemize}\n\\item\n \\textbf{Service Builder}: Service Builder classes\n\\end{itemize}\n\nThe classloader used depends on context. Classloading rules vary between\napplication servers. Classloading in web applications and OSGi bundles\ndiffers too. In all contexts, however, the Bootstrap classloader loads\nclasses from \\texttt{java.*} packages.\n\nClassloading from a web application perspective is up next.\n\n\\section{Web Application Classloading\nPerspective}\\label{web-application-classloading-perspective}\n\nApplication servers dictate where and in what order web applications,\nsuch as Liferay DXP, search for classes and resources. Application\nservers such as\n\\href{https://tomcat.apache.org/tomcat-9.0-doc/class-loader-howto.html}{Apache\nTomcat} enforce the following default search order:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\tightlist\n\\item\n Bootstrap classes\n\\item\n Web app's \\texttt{WEB-INF/classes}\n\\item\n web app's \\texttt{WEB-INF/lib/*.jar}\n\\item\n System classloader\n\\item\n Common classloader\n\\end{enumerate}\n\nFirst, the web application searches Bootstrap. If the class/resource\nisn't there, the web application searches its own classes and JARs. If\nthe class/resource still isn't found, it checks the System classloader\nand then Common classloader. Except for the web application checking its\nown classes and JARs, it searches the hierarchy in parent-first order.\n\nApplication servers such as\n\\href{https://docs.oracle.com/cd/E19501-01/819-3659/beadf/index.html}{Oracle\nWebLogic} and IBM WebSphere have additional classloaders. They may also\nhave a different classloader hierarchy and search order. Consult your\napplication server's documentation for classloading details.\n\n\\section{Other Classloading\nPerspectives}\\label{other-classloading-perspectives}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/bundle-classloading-flow}{Bundle\nClassloading Flow} explains classloading from an OSGi bundle\nperspective.\n\nClassloading for JSPs and Service Builder classes is similar to that of\nweb applications and OSGi bundle classes.\n\nYou now know Liferay DXP's classloading hierarchy, understand it in\ncontext of web applications, and have references to information on other\nclassloading perspectives.\n\n\\section{Related Topics}\\label{related-topics-8}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/bundle-classloading-flow}{Bundle\nClassloading Flow}\n\n\\chapter{Liferay DXP Startup Phases}\\label{liferay-dxp-startup-phases}\n\nKnowing Liferay's startup phases helps you troubleshoot startup\nfailures. By learning the phase triggered events, you can listen for\nphases and act on them. This article describes the startup phases and\nidentifies how to \\hyperref[acting-on-events]{implement actions for\nphase events}.\n\nStartup consists of these main phases:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\textbf{Portal Context Initialization Phase:} focuses on low level\n tasks without a web context.\n\\item\n \\textbf{Main Servlet Initialization Phase:} focuses on the portlet\n container and the Liferay DXP web application's UI features such as\n Struts, Themes, and more.\n\\end{enumerate}\n\nThe Portal Context Initialization Phase sets the stage for the Main\nServlet Initialization Phase.\n\n\\section{Portal Context Initialization\nPhase}\\label{portal-context-initialization-phase}\n\nThe Portal Context Initialization phase runs first with these tasks:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Set up low level utilities such as logging and those in\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/util/PortalUtil.html}{\\texttt{PortalUtil}}\n and\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-impl/com/liferay/portal/util/InitUtil.html}{\\texttt{InitUtil}}.\n\\item\n OSGi framework is initialized.\n\\item\n Spring Phase 1: INFRASTRUCTURE beans specified by the Spring context\n files listed in Portal property\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Spring}{\\texttt{spring.infrastructure.configs}}\n are loaded.\n\\item\n INFRASTRUCTURE beans are published as\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\n services}.\n\\item\n OSGi framework starts.\n\n \\begin{enumerate}\n \\def\\labelenumii{\\arabic{enumii}.}\n \\tightlist\n \\item\n Static bundles are installed and started.\n \\item\n Dynamic bundles are started.\n \\end{enumerate}\n\\item\n OSGi framework starts the runtime.\n\\item\n Spring Phase 2: MAIN\n\n \\begin{enumerate}\n \\def\\labelenumii{\\arabic{enumii}.}\n \\tightlist\n \\item\n Load Spring beans specified by the Spring context files listed in\n Portal property\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Spring}{\\texttt{spring.configs}}.\n \\item\n A\n \\hyperref[moduleservicelifecycle-events]{\\texttt{ModuleServiceLifecycle}\n event service} with a service property\n \\texttt{module.service.lifecycle} value \\texttt{spring.initialized}\n (i.e.,\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/constant-values.html\\#com.liferay.portal.kernel.module.framework.ModuleServiceLifecycle.SPRING_INITIALIZED}{\\texttt{SPRING\\_INITIALIZED}})\n registers.\n \\end{enumerate}\n\\item\n MAIN Spring beans are published as\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\n services}.\n\\end{enumerate}\n\n\\section{Main Servlet Initialization\nPhase}\\label{main-servlet-initialization-phase}\n\nHere's the phase's activity sequence:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n The\n \\hyperref[moduleservicelifecycle-events]{\\texttt{ModuleServiceLifecycle}\n event service} is updated with the service property\n \\texttt{module.service.lifecycle} value \\texttt{database.initialized}\n (i.e.,\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/constant-values.html\\#com.liferay.portal.kernel.module.framework.ModuleServiceLifecycle.DATABASE_INITIALIZED}{\\texttt{DATABASE\\_INITIALIZED}}).\n\\item\n The \\hyperref[portal-startup-events]{Global Startup event} fires.\n\\item\n For each portal instance, the\n \\hyperref[portal-startup-events]{Application Startup events} fire.\n\\item\n The\n \\hyperref[moduleservicelifecycle-events]{\\texttt{ModuleServiceLifecycle}\n event service} is updated with the service property\n \\texttt{module.service.lifecycle} value \\texttt{portal.initialized}\n (i.e.,\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/constant-values.html\\#com.liferay.portal.kernel.module.framework.ModuleServiceLifecycle.PORTAL_INITIALIZED}{\\texttt{PORTAL\\_INITIALIZED}}).\n\\end{enumerate}\n\nNow that you're acquainted with the startup phases, you can concentrate\non the events they fire.\n\n\\section{Acting on Events}\\label{acting-on-events}\n\nThe ways to act on events depends on the event type. These subsections\ndescribe the event types.\n\n\\section{ModuleServiceLifecycle\nEvents}\\label{moduleservicelifecycle-events}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/waiting-on-lifecycle-events}{You\ncan wait for and act on \\texttt{ModuleServiceLifecycle} event services.}\n\n\\section{Portal Startup Events}\\label{portal-startup-events}\n\nIn your \\texttt{liferay-portal-ext.properties} file, you can override\nthe following properties and add your own\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/events/LifecycleAction.html}{\\texttt{LifecycleAction}}\nclasses to the list of action classes to invoke on the events.\n\n\\textbf{Global Startup Event} runs once when Liferay DXP initializes.\nThe\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Startup\\%20Events}{\\texttt{global.startup.events}\nproperty} defines the event's default actions.\n\n\\textbf{Application Startup Events} runs once for each Site instance\nLiferay DXP initializes. The\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/propertiesdoc/portal.properties.html\\#Startup\\%20Events}{\\texttt{application.startup.events}\nproperty} defines the event's default actions.\n\n\\section{Related Topics}\\label{related-topics-9}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/waiting-on-lifecycle-events}{Waiting\non Lifecycle Events}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/declarative-services}{OSGi\nServices and Dependency Injection with Declarative Services}\n\n\\chapter{The Benefits of Modularity}\\label{the-benefits-of-modularity}\n\nDictionary.com defines\n\\href{http://www.dictionary.com/browse/modularity}{modularity} as\n\\emph{the use of individually distinct functional units, as in\nassembling an electronic or mechanical system.} The distinct functional\nunits are called \\emph{modules}.\n\nNASA's Apollo spacecraft, for example, comprised three modules, each\nwith a distinct function:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\emph{Lunar Module}: Carried astronauts from the Apollo spacecraft to\n the moon's surface and back.\n\\item\n \\emph{Service Module}: Provided fuel for propulsion, air conditioning,\n and water.\n\\item\n \\emph{Command Module}: Housed the astronauts and communication and\n navigation controls.\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/modularity_apollo_spacecraft_diagram.png}\n\\caption{The Apollo spacecraft's modules collectively took astronauts to\nthe moon's surface and back to Earth.}\n\\end{figure}\n\nThe spacecraft and its modules exemplified these modularity\ncharacteristics:\n\n\\begin{itemize}\n\\item\n \\textbf{Distinct functionality}: Each module provides a distinct\n function (purpose); modules can be combined to provide an entirely new\n collective function.\n\n The Apollo spacecraft's modules were grouped together for a distinct\n collective function: take astronauts from the Earth's atmospheric rim,\n to the moon's surface, and back to Earth. The previous list identifies\n each module's distinct function.\n\\item\n \\textbf{Dependencies}: Modules can require capabilities other modules\n satisfy.\n\n The Apollo modules had these dependencies:\n\n \\begin{itemize}\n \\item\n Lunar Module depended on the Service Module to get near the moon.\n \\item\n Command Module depended on the Service Module for power and oxygen.\n \\item\n Service Module depended on the Command Module for instruction.\n \\end{itemize}\n\\item\n \\textbf{Encapsulation}: Modules hide their implementation details but\n publicly define their capabilities and interfaces.\n\n Each Apollo module was commissioned with a contract defining its\n capabilities and interface, while each module's details were\n encapsulated (hidden) from other modules. NASA integrated the modules\n based on their interfaces.\n\\item\n \\textbf{Reusability}: A module can be applied to different scenarios.\n\n The Command Module's structure and design were reusable. NASA used\n different versions of the Command Module, for example, throughout the\n Apollo program, and in the Gemini Program, which focused on Earth\n orbit.\n\\end{itemize}\n\nNASA used modularity to successfully complete over a dozen missions to\nthe moon. Can modularity benefit software too? Yes! The following\nsections show you how:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[modularity-benefits-for-software]{Modularity benefits for\n software}\n\\item\n \\hyperref[example-designing-a-modular-application]{Example: How to\n design a modular application}\n\\end{itemize}\n\n\\section{Modularity Benefits for\nSoftware}\\label{modularity-benefits-for-software}\n\nJava applications have predominantly been monolithic: they're developed\nin large code bases. In a monolith, it's difficult to avoid tight\ncoupling of classes. Modular application design, conversely, facilitates\nloose coupling, making the code easier to maintain. It's much easier and\nmore fun to develop small amounts of cohesive code in modules. Here are\nsome key benefits of developing modular software.\n\n\\section{Distinct Functionality}\\label{distinct-functionality}\n\nIt's natural to focus on developing one piece of software at a time. In\na module, you work on a small set of classes to define and implement the\nmodule's function. Keeping scope small facilitates writing high quality,\nelegant code. The more cohesive the code, the easier it is to test,\ndebug, and maintain. Modules can be combined to provide a new function,\ndistinguishable from each module's function.\n\n\\section{Encapsulation}\\label{encapsulation}\n\nA module encapsulates a function (capability). Module implementations\nare hidden from consumers, so you can create and modify them as you\nlike. Throughout a module's lifetime, you can fix and improve the\nimplementation or swap in an entirely new one. You make the changes\nbehind the scenes, transparent to consumers. A module's contract defines\nits capability and interface, making the module easy to understand and\nuse.\n\n\\section{Dependencies}\\label{dependencies}\n\nModules have requirements and capabilities. The interaction between\nmodules is a function of the capability of one satisfying the\nrequirement of another and so on. Modules are published to artifact\nrepositories, such as Maven Central. Module versioning schemes let you\nspecify dependencies on particular module versions or version ranges.\n\n\\section{Reusability}\\label{reusability}\n\nModules that do their job well are hot commodities. They're reusable\nacross projects, for different purposes. As you discover helpful\nreliable modules, you'll use them again and again.\n\nIt's time to design a modular application.\n\n\\section{Example: Designing a Modular\nApplication}\\label{example-designing-a-modular-application}\n\nApplication design often starts out simple but gets more complex as you\ndetermine capabilities the application requires. If a third party\nlibrary already provides the capability, you can\n\\href{/docs/7-2/customization/-/knowledge_base/c/adding-third-party-libraries-to-a-module}{deploy\nit with your app}. You can otherwise implement the capability yourself.\n\nAs you design various aspects of your app to support its function, you\nmust decide how those aspects fit into the code base. Putting them in a\nsingle monolithic code base often leads to tight coupling, while\ndesignating separate modules for each aspect fosters loose coupling.\nAdopting a modular approach to application design lets you reap the\nmodularity benefits.\n\nFor example, you can apply modular design to a speech recognition app.\nHere are the app's function and required capabilities:\n\n\\emph{Function}: interface with users to translate their speech into\ntext for the computer to understand.\n\n\\emph{Required capabilities}:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Translates user words to text\n\\item\n Uses a selected computer voice to speak to users.\n\\item\n Interacts with users based on a script of instructions that include\n questions, commands, requests, and confirmations.\n\\end{itemize}\n\nYou could create modules to provide the required capabilities:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\emph{Speech to text}: Translates spoken words to text the computer\n understands.\n\\item\n \\emph{Voice UI}: Interacts with users based on stored questions,\n commands, and confirmations.\n\\item\n \\emph{Instruction manager}: Stores and provides the application's\n questions, commands, and confirmations.\n\\item\n \\emph{Computer voice}: Stores and provides computer voices for users\n to choose from.\n\\end{itemize}\n\nThe following diagram contrasts a monolithic design for the speech\nrecognition application with a modular design.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/modularity-benefits-application-design-example.png}\n\\caption{The speech recognition application can be implemented in a\nsingle monolithic code base or in modules, each focused on a particular\nfunction.}\n\\end{figure}\n\nDesigning the app as a monolith lumps everything together. There are no\ninitial boundaries between the application aspects, whereas the modular\ndesign distinguishes the aspects.\n\nDevelopers can create the modules in parallel, each one with its own\nparticular capability. Designing applications that comprise modules\nfosters writing cohesive pieces of code that represent capabilities.\nEach module's capability can potentially be \\emph{reused} in other\nscenarios too.\n\nFor example, the \\emph{Instruction manager} and \\emph{Computer voice}\nmodules can be \\emph{reused} by a navigation app.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/modularity-benefits-module-reuse.png}\n\\caption{The \\emph{Instruction manager} and \\emph{Computer voice}\nmodules designed for the speech recognition app can be used (or\n\\emph{reused}) by a navigation app.}\n\\end{figure}\n\nHere are the benefits of designing the speech recognition app as\nmodules:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Each module represents a capability that contributes to the app's\n overall function.\n\\item\n The app depends on modules, that are easy to develop, test, and\n maintain.\n\\item\n The modules can be reused in different applications.\n\\end{itemize}\n\nIn conclusion, modularity has literally taken us to the moon and back.\nIt benefits software development too. The example speech recognition\napplication demonstrated how to design an app that comprises modules.\n\nNext you'll learn how OSGi facilitates creating modules that provide and\nconsume services.\n\n\\chapter{OSGi and Modularity}\\label{osgi-and-modularity}\n\nModularity makes writing software, especially as a team, fun! Here are\nsome benefits to modular development on DXP:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Liferay DXP's runtime framework is lightweight, fast, and secure.\n\\item\n The framework uses the OSGi standard. If you have experience using\n OSGi with other projects, you can apply your existing knowledge to\n developing on DXP.\n\\item\n Modules publish services to and consume services from a service\n registry. Service contracts are loosely coupled from service providers\n and consumers, and the registry manages the contracts automatically.\n\\item\n Modules' dependencies are managed automatically by the container,\n dynamically (no restart required).\n\\item\n The container manages module life cycles dynamically. Modules can be\n installed, started, updated, stopped, and uninstalled while Liferay is\n running, making deployment a snap.\n\\item\n Only a module's classes whose packages are explicitly exported are\n publicly visible; OSGi hides all other classes by default.\n\\item\n Modules and packages are semantically versioned and declare\n dependencies on specific versions of other packages. This allows two\n applications that depend on different versions of the same packages to\n each depend on their own versions of the packages.\n\\item\n Team members can develop, test, and improve modules in parallel.\n\\item\n You can use your existing developer tools and environment to develop\n modules.\n\\end{itemize}\n\nThere are many benefits to modular software development with OSGi, and\nwe can only scratch the surface here. Once you start developing modules,\nyou might find it hard to go back to developing any other way.\n\n\\section{Modules}\\label{modules}\n\nIt's time to see what module projects look like and see Liferay DXP's\nmodular development features in action. To keep things simple, only\nproject code and structure are shown: you can\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{create\nmodules} like these anytime.\n\nThese modules collectively provide a command that takes a String and\nuses it in a greeting. Consider it ``Hello World'' for modules.\n\n\\section{API}\\label{api}\n\nThe API module is first. It defines the contract that a provider\nimplements and a consumer uses. Here is its structure:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{greeting-api}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com/liferay/docs/greeting/api}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{Greeting.java}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{bnd.bnd}\n \\item\n \\texttt{build.gradle}\n \\end{itemize}\n\\end{itemize}\n\nVery simple, right? Beyond the Java source file, there are only two\nother files: a Gradle build script (though you can use any build system\nyou want), and a configuration file called \\texttt{bnd.bnd}. The\n\\texttt{bnd.bnd} file describes and configures the module:\n\n\\begin{verbatim}\nBundle-Name: Greeting API\nBundle-SymbolicName: com.liferay.docs.greeting.api\nBundle-Version: 1.0.0\nExport-Package: com.liferay.docs.greeting.api\n\\end{verbatim}\n\nThe module's name is \\emph{Greeting API}. Its symbolic name--a name that\nensures uniqueness--is \\texttt{com.liferay.docs.greeting.api}. Its\nsemantic version is declared next, and its package is \\emph{exported},\nwhich means it's made available to other modules. This module's package\nis just an API other modules can implement.\n\nFinally, there's the Java class, which in this case is an interface:\n\n\\begin{verbatim}\npackage com.liferay.docs.greeting.api;\n\nimport aQute.bnd.annotation.ProviderType;\n\n@ProviderType\npublic interface Greeting {\n\n public void greet(String name);\n\n}\n\\end{verbatim}\n\nThe interface's \\texttt{@ProviderType} annotation tells the service\nregistry that anything implementing the interface is a provider. The\ninterface's one method asks for a \\texttt{String} and doesn't return\nanything.\n\nThat's it! As you can see, creating modules is not very different from\ncreating other Java projects.\n\n\\section{Provider}\\label{provider}\n\nAn interface only defines an API; to do something, it must be\nimplemented. This is what the provider module is for. Here's what a\nprovider module for the Greeting API looks like:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{greeting-impl}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com/liferay/docs/greeting/impl}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{GreetingImpl.java}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{bnd.bnd}\n \\item\n \\texttt{build.gradle}\n \\end{itemize}\n\\end{itemize}\n\nIt has the same structure as the API module: a build script, a\n\\texttt{bnd.bnd} configuration file, and an implementation class. The\nonly differences are the file contents. The \\texttt{bnd.bnd} file is a\nlittle different:\n\n\\begin{verbatim}\nBundle-Name: Greeting Impl\nBundle-SymbolicName: com.liferay.docs.greeting.impl\nBundle-Version: 1.0.0\n\\end{verbatim}\n\nThe bundle name, symbolic name, and version are all set similarly to the\nAPI.\n\nFinally, there's no \\texttt{Export-Package} declaration. A client (which\nis the third module you'll create) just wants to use the API: it doesn't\ncare how its implementation works as long as the API returns what it's\nsupposed to return. The client, then, only needs to declare a dependency\non the API; the service registry injects the appropriate implementation\nat runtime.\n\nPretty cool, eh?\n\nAll that's left, then, is the class that provides the implementation:\n\n\\begin{verbatim}\npackage com.liferay.docs.greeting.impl;\n\nimport com.liferay.docs.greeting.api.Greeting;\n\nimport org.osgi.service.component.annotations.Component;\n\n@Component(\n immediate = true,\n property = {\n },\n service = Greeting.class\n)\npublic class GreetingImpl implements Greeting {\n\n @Override\n public void greet(String name) {\n System.out.println(\"Hello \" + name + \"!\");\n }\n\n}\n\\end{verbatim}\n\nThe implementation is simple. It uses the \\texttt{String} as a name and\nprints a hello message. A better implementation might be to use\nLiferay's API to collect all the names of all the users in the system\nand send each user a greeting notification, but the point here is to\nkeep things simple. You should understand, though, that there's nothing\nstopping you from replacing this implementation by deploying another\nmodule whose Greeting implementation's \\texttt{@Component} annotation\nspecifies a higher service ranking property (e.g.,\n\\texttt{\"service.ranking:Integer=100\"}).\n\nThis \\texttt{@Component} annotation defines three options:\n\\texttt{immediate\\ =\\ true}, an empty property list, and the service\nclass that it implements. The \\texttt{immediate\\ =\\ true} setting means\nthat this module should not be lazy-loaded; the service registry loads\nit as soon as it's deployed, instead of when it's first used. Using the\n\\texttt{@Component} annotation declares the class as a Declarative\nServices component, which is the most straightforward way to create\ncomponents for OSGi modules. A component is a POJO that the runtime\ncreates automatically when the module starts.\n\nTo compile this module, the API it's implementing must be on the\nclasspath. If you're using Gradle, you'd add the \\texttt{greetings-api}\nproject to your \\texttt{dependencies\\ \\{\\ ...\\ \\}} block. In a\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace} module, the dependency looks like this:\n\n\\begin{verbatim}\ncompileOnly project (':modules:greeting-api')\n\\end{verbatim}\n\nThat's all there is to a provider module.\n\n\\section{Consumer}\\label{consumer}\n\nThe consumer or client uses the API that the API module defines and the\nprovider module implements. DXP has many different kinds of consumer\nmodules.\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{Portlets} are\nthe most common consumer module type, but since they are a topic all by\nthemselves, this example stays simple by creating an command for the\nApache Felix Gogo shell. Note that consumers can, of course, consume\nmany different APIs to provide functionality.\n\nA consumer module has the same structure as the other module types:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{greeting-command}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{src}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{main}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{java}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{com/liferay/docs/greeting/command}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{GreetingCommand.java}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\end{itemize}\n \\item\n \\texttt{bnd.bnd}\n \\item\n \\texttt{build.gradle}\n \\end{itemize}\n\\end{itemize}\n\nAgain, you have a build script, a \\texttt{bnd.bnd} file, and a Java\nclass. This module's \\texttt{bnd.bnd} file is almost the same as the\nprovider's:\n\n\\begin{verbatim}\nBundle-Name: Greeting Command\nBundle-SymbolicName: com.liferay.docs.greeting.command\nBundle-Version: 1.0.0\n\\end{verbatim}\n\nThere's nothing new here: you declare the same things you declared for\nthe provider.\n\nYour Java class has a little bit more going on:\n\n\\begin{verbatim}\npackage com.liferay.docs.greeting.command;\n\nimport org.osgi.service.component.annotations.Component;\nimport org.osgi.service.component.annotations.Reference;\n\nimport com.liferay.docs.greeting.api.Greeting;\n\n@Component(\n immediate = true,\n property = {\n \"osgi.command.scope=greet\",\n \"osgi.command.function=greet\"\n },\n service = Object.class\n)\npublic class GreetingCommand {\n\n public void greet(String name) {\n Greeting greeting = _greeting;\n\n greeting.greet(name);\n }\n\n @Reference\n private Greeting _greeting;\n\n}\n\\end{verbatim}\n\nThe \\texttt{@Component} annotation declares the same attributes, but\nspecifies different properties and a different service. As in Java,\nwhere every class is a subclass of \\texttt{java.lang.Object} (even\nthough you don't need to specify it by default), in Declarative\nServices, the runtime needs to know the type of class to register.\nBecause you're not implementing any particular type, your parent class\nis \\texttt{java.lang.Object}, so you must specify that class as the\nservice. While Java doesn't require you to specify \\texttt{Object} as\nthe parent when you're creating a class that doesn't inherit anything,\nDeclarative Services does.\n\nThe two properties define a command scope and a command function. All\ncommands have a scope to define their context, as it's common for\nmultiple APIs to have similar functions, such as \\texttt{copy} or\n\\texttt{delete}. These properties specify you're creating a command\ncalled \\texttt{greet} in a scope called \\texttt{greet}. While you get no\npoints for imagination, this sufficiently defines the command.\n\nSince you specified \\texttt{osgi.command.function=greet} in the\n\\texttt{@Component} annotation, your class must have a method named\n\\texttt{greet}, and you do. But how does this \\texttt{greet} method\nwork? It obtains an instance of the \\texttt{Greeting} OSGi service and\ninvokes its \\texttt{greet} method, passing in the \\texttt{name}\nparameter. How is an instance of the \\texttt{Greeting} OSGi service\nobtained? The \\texttt{GreetingCommand} class declares a private service\nbean, \\texttt{\\_greeting} of type \\texttt{Greeting}. This is the OSGi\nservice type that the provider module registers. The \\texttt{@Reference}\nannotation tells the OSGi runtime to instantiate the service bean with a\nservice from the service registry. The runtime binds the\n\\texttt{Greeting} object of type \\texttt{GreetingImpl} to the private\nfield \\texttt{\\_greeting}. The \\texttt{greet} method uses the\n\\texttt{\\_greeting} field value.\n\nJust like the provider, the consumer needs to have the API on its\nclasspath in order to compile, but at runtime, since you've declared all\nthe dependencies appropriately, the container knows about these\ndependencies, and provides them automatically.\n\nIf you were to\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{deploy\nthese modules to a DXP instance}, you'd be able to attach to the\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Gogo\nShell} and execute a command like this:\n\n\\begin{verbatim}\ngreet:greet \"Captain\\ Kirk\"\n\\end{verbatim}\n\nThe shell would then return your greeting:\n\n\\begin{verbatim}\nHello Captain Kirk!\n\\end{verbatim}\n\nThis most basic of examples should make it clear that module-based\ndevelopment is easy and straightforward. The API-Provider-Consumer\ncontract fosters loose coupling, making your software easy to manage,\nenhance, and support.\n\n\\section{A Typical Liferay\nApplication}\\label{a-typical-liferay-application}\n\nIf you look at a typical application from Liferay's source, you'll\ngenerally find at least four modules:\n\n\\begin{itemize}\n\\tightlist\n\\item\n An API module\n\\item\n A Service (provider) module\n\\item\n A Test module\n\\item\n A Web (consumer) module\n\\end{itemize}\n\nThis is exactly what you'll find for some smaller applications, like the\nMentions application that lets users mention other users with the\n\\texttt{@username} nomenclature in comments, blogs, or other\napplications. Larger applications like the Documents and Media library\nhave more modules. In the case of the Documents and Media library, there\nare separate modules for different document storage back-ends. In the\ncase of the Wiki, there are separate modules for different Wiki engines.\n\nEncapsulating capability variations as modules facilitates\nextensibility. If you have a document storage back-end that Liferay\ndoesn't yet support, you can implement Liferay's document storage API\nfor your solution by developing a module for it and thus extend\nLiferay's Documents and Media library. If there's a Wiki dialect that\nyou like better than what Liferay's wiki provides, you can write a\nmodule for it and extend Liferay's wiki.\n\nAre you excited yet? Are you ready to start developing? Here are some\nresources for you to learn more.\n\n\\section{Related Topics}\\label{related-topics-10}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/maven}{Maven}\n\n\\href{/docs/7-2/tutorials/-/knowledge_base/t/upgrading-code-to-product-ver}{Upgrading\nCode to 7.2}\n\n\\chapter{Module Lifecycle}\\label{module-lifecycle}\n\nIn OSGi, all components, Java classes, resources, and descriptors are\ndeployed via modules. The \\texttt{MANIFEST.MF} file describes the\nmodule's physical characteristics, such as the packages it exports and\nimports. The module's component description files specify its functional\ncharacteristics (i.e., the services its components offer and consume).\nAlso modules and their components have their own lifecycles and\nadministrative APIs. Declarative Services and shell tools give you\nfine-grained control over module and component deployment.\n\nSince a module's contents depend on its activation, consider the\nactivation steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n \\emph{Installation}: Copying the module JAR into Liferay DXP's\n \\texttt{{[}Liferay\\ Home{]}/deploy} folder installs the module to the\n OSGi framework, marking the module \\texttt{INSTALLED}.\n\\item\n \\emph{Resolution}: Once all the module's requirements are met (e.g.,\n all packages it imports are available), the framework publishes the\n module's exported packages and marks the module \\texttt{RESOLVED}.\n\\item\n \\emph{Activation}: Modules are activated \\emph{eagerly} by default.\n That is, they're started in the framework and marked \\texttt{ACTIVE}\n on resolution. An active module's components are enabled. If a module\n specifies a \\texttt{lazy} activation policy, as shown in the manifest\n header below, it's activated only after another module requests one of\n its classes.\n\n\\begin{verbatim}\nBundle-ActivationPolicy: lazy\n\\end{verbatim}\n\\end{enumerate}\n\nThe figure below illustrates the module lifecycle.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/module-state-diagram.png}\n\\caption{This state diagram illustrates the module lifecycle.}\n\\end{figure}\n\nThe\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Apache\nFelix Gogo Shell} lets you manage the module lifecycle. You can\ninstall/uninstall modules and start/stop them. You can update a module\nand notify dependent modules to use the update. Liferay's tools,\nincluding\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\nDev Studio DXP},\n\\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\nWorkspace}, and\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI} offer\nsimilar shell commands that use the OSGi Admin API.\n\nOn activating a module, its components are enabled. But only\n\\emph{activated} components can be used. Component activation requires\nall its referenced services be satisfied. That is, all services it\nreferences must be registered. The highest ranked service that matches a\nreference is bound to the component. When the container finds and binds\nall the services the component references, it registers the component.\nIt's now ready for activation.\n\nComponents can use \\emph{delayed} (default) or \\emph{immediate}\nactivation policies. To specify immediate activation, the developer adds\nthe attribute \\texttt{immediate=true} to the \\texttt{@Component}\nannotation.\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n ...\n)\n\\end{verbatim}\n\nUnless immediate activation is specified, the component's activation is\ndelayed. That is, the component's object is created and its classes are\nloaded once the component is requested. In this way, delayed activation\ncan improve startup times and conserve resources.\n\nGogo Shell's\n\\href{http://felix.apache.org/documentation/subprojects/apache-felix-service-component-runtime.html\\#shell-command}{Service\nComponent Runtime commands} let you manage components:\n\n\\begin{itemize}\n\\item\n \\texttt{scr:list\\ {[}bundleID{]}}: Lists the module's (bundle's)\n components.\n\\item\n \\texttt{scr:info\\ {[}componentID\\textbar{}fullClassName{]}}: Describes\n the component, including its status and the services it provides.\n\\item\n \\texttt{scr:enable\\ {[}componentID\\textbar{}fullClassName{]}}: Enables\n the component.\n\\item\n \\texttt{scr:disable\\ {[}componentID\\textbar{}fullClassName{]}}:\n Disables the component. It's disabled on the server (or current server\n node in a cluster) until the server is restarted.\n\\end{itemize}\n\nService references are static and reluctant by default. That is, an\ninjected service remains bound to the referencing component until the\nservice is disabled. Alternatively, you can specify \\emph{greedy}\nservice policies for references. Every time a higher ranked matching\nservice is registered, the framework unbinds the lower ranked service\nfrom the component (whose service policy is greedy) and binds the new\nservice in its place automatically. Here's a \\texttt{@Reference}\nannotation that uses a greedy policy:\n\n\\begin{verbatim}\n@Reference(policyOption = ReferencePolicyOption.GREEDY)\n\\end{verbatim}\n\nDeclarative Services annotations let you specify component activation\nand service policies. Gogo Shell commands let you control modules and\ncomponents.\n\n\\section{Related Topics}\\label{related-topics-11}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Creating\na Project}\n\n\\href{/docs/7-2/tutorials/-/knowledge_base/t/upgrading-code-to-product-ver}{Upgrading\nCode to 7.2}\n\n\\chapter{UI Architecture}\\label{ui-architecture}\n\n\\href{/docs/7-2/user/-/knowledge_base/u/the-liferay-distinction}{Liferay\nDXP's UI} is a portal for adding sites, pages, widgets, and content. It\nhelps people do work,\n\\href{/docs/7-2/user/-/knowledge_base/u/collaboration}{collaborate}, and\n\\href{/docs/7-2/user/-/knowledge_base/u/web-experience-management}{share\ncontent}.\n\nThe UI comprises the following parts:\n\n\\begin{itemize}\n\\item\n Content: images, videos, and text.\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/application-development}{Applications}:\n Widgets and portlets that expose functionality for accomplishing\n tasks.\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/themes-introduction}{Themes}:\n Plugins that use CSS, FreeMarker templates, HTML, and JavaScript to\n provide a site's overall look and feel.\n\\item\n Product navigation sidebars and panels: Use these for administering\n sites.\n\\end{itemize}\n\n\\section{Content}\\label{content}\n\nLiferay DXP's built-in applications help you publish images, video,\nforms, markup text, and more to site pages.\n\\href{/docs/7-2/user/-/knowledge_base/u/managing-documents-and-media}{Documents\nand Media} stores images, videos, and documents to use throughout your\nsite. The\n\\href{/docs/7-2/user/-/knowledge_base/u/web-experience-management}{Web\nExperience Management} suite helps you create, maintain, and organize\ncontent. \\href{/docs/7-2/user/-/knowledge_base/u/forms}{Liferay Forms}\ngives you robust form building capability.\n\\href{/docs/7-2/user/-/knowledge_base/u/creating-forums-with-message-boards}{Message\nBoards} facilitate lively discussions and\n\\href{/docs/7-2/user/-/knowledge_base/u/publishing-blogs}{Blogs} let\nusers express themselves with markup text and images. These are just a\nfew of the built-in applications for adding site content.\n\n\\section{Applications}\\label{applications}\n\nLiferay DXP applications provide content and help users accomplish\ntasks. They're\n\\href{/7-2/appdev/-/knowledge_base/a/web-front-ends}{developed the same\nway} as other web applications, and Liferay DXP can combine multiple\napplications on one page.\n\nLiferay DXP supports developing JavaScript-based applications using\npopular front-end frameworks:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-an-angular-application}{Angular}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-react-application}{React}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/developing-a-vue-application}{Vue}\n\\end{itemize}\n\nJava-based portlet applications use the latest portlet standards and\nframeworks, including ones familiar to experienced Liferay portlet\ndevelopers:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/liferay-mvc-portlet}{Liferay\n MVC Portlet}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/portletmvc4spring}{PortletMVC4Spring}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/jsf-portlet}{JSF Portlet}\n\\end{itemize}\n\nIn the UI, applications are referred to as Widgets and categorized for\nusers to add to pages. Administrative applications are available in the\nproduct menu panels.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/architecture-ui-widgets.png}\n\\caption{Widget pages offer users functionality. Widgets are organized\ninto a page template's rows and columns. This template has two columns:\na smaller left column and larger right column. On this page, users\nselect tags in the Tag Cloud widget and the matching tagged images show\nthe Asset Publisher widget.}\n\\end{figure}\n\n\\section{Themes}\\label{themes}\n\nA\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/themes-introduction}{theme}\nstyles a site with a unique look and feel. It's developed as a WAR\nproject that includes CSS, JavaScript, and markup content. You can\ndevelop themes using whatever tools you prefer, but Liferay DXP offers\n\\href{https://getbootstrap.com/}{Bootstrap}-based components and\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/developing-themes}{theme\ntooling} to create and deploy themes in no time.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/architecture-ui-themes.png}\n\\caption{You can select an attractive theme and apply it to your site.}\n\\end{figure}\n\nHere's a quick demonstration of developing a theme:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a theme using the\n \\href{/docs/7-2/reference/-/knowledge_base/r/theme-generator}{Theme\n Generator}. The theme extends the base theme you specified to the\n Theme Generator---Liferay's\n \\href{https://github.com/liferay/liferay-portal/tree/7.2.x/modules/apps/frontend-theme/frontend-theme-styled}{Styled\n theme} is the default.\n\\item\n Run\n \\href{https://portal.liferay.dev/docs/7-2/frameworks/-/knowledge_base/f/building-your-themes-files}{\\texttt{gulp\\ build}}\n to generate the base theme files to the \\texttt{build} folder\n subfolders:\n\n \\begin{itemize}\n \\item\n \\texttt{templates}: FreeMarker templates specify site page markup.\n \\texttt{portal\\_normal.ftl} is the central file; it includes\n templates that define the page parts (e.g., header, navigation,\n footer). The \\texttt{init.ftl} file defines default variables\n available to the templates.\n \\item\n \\texttt{css}: SCCS files that provide styling.\n \\item\n \\texttt{font}: Font Awesome and Glyphicons fonts.\n \\item\n \\texttt{js}: JavaScript files; \\texttt{main.js} is the Styled\n theme's JavaScript.\n \\item\n \\texttt{images}: Image files.\n \\end{itemize}\n\\item\n Override aspects of the base theme by copying relevant files from the\n \\texttt{build} subfolders to folders of the same name in your\n \\texttt{src} folder. The\n \\href{/docs/7-2/reference/-/knowledge_base/r/theme-reference-guide}{Theme\n Anatomy Guide} describes all the files. Here's an example of a\n customized \\texttt{portal\\_normal.ftl}:\n\\end{enumerate}\n\n\\begin{verbatim}\n\n\n \n \n \n <#include \"${full_templates_path}/navigation.ftl\" />\n \n \n ${portlets}\n \n <#include \"${full_templates_path}/footer.ftl\" />\n \n\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\tightlist\n\\item\n Add custom styling using your theme's \\texttt{\\_custom.scss} file\n (i.e., \\texttt{src/css/\\_custom.scss}). Liferay DXP supports\n \\href{https://getbootstrap.com/}{Bootstrap}, as well as\n \\href{https://sass-lang.com/}{Sass}, so you can use Bootstrap\n utilities in your markup and Sass nesting, variables, and more in your\n CSS files. This snippet styles the logo:\n\\end{enumerate}\n\n\\begin{verbatim}\n.logo {\n margin-left: 15px;\n\n img {\n height: auto;\n }\n\n @include media-breakpoint-down(md) {\n text-align: center;\n width: 100%;\n }\n}\n\\end{verbatim}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/architecture-ui-portal-dev-logo.png}\n\\caption{You can provide custom styling using the theme's\n\\texttt{\\_custom.sccs} file.}\n\\end{figure}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{4}\n\\tightlist\n\\item\n Deploy your theme by executing \\texttt{gulp\\ deploy}.\n\\end{enumerate}\n\nThe theme is available to\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/deploying-and-applying-themes}{apply}\nto your site.\n\nFor details,\n\\href{/docs/7-2/customization/-/knowledge_base/c/theme-components}{Theme\nComponents} breaks down a theme's parts, and the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/themes-introduction}{Themes\nsection} provides theme development details.\n\n\\section{Product Navigation Sidebars and\nPanels}\\label{product-navigation\\noindent\\hrulefills-and-panels}\n\nThe product navigation sidebars and panels enable administrators to\nbuild sites, add pages, apply themes, and configure the portal. It's\nalso where you can provide administrative functionality for your custom\napplications. The navigation sidebars and panels are customizable.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/architecture-ui-menus-and-panel-app.png}\n\\caption{Liferay facilitates integrating custom administrative\nfunctionality through navigation menus and administrative applications.}\n\\end{figure}\n\nAs you can see, Liferay DXP's UI is highly flexible and customizable.\nHere's where to learn more:\n\n\\begin{itemize}\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/theme-components}{Theme\n Components}: Explains available mechanisms and extensions for\n customizing and theming pages, content, and applications.\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/understanding-the-page-structure}{Understanding\n the Page Structure}: Describes how the page's UI is organized and\n introduces tools for populating and developing each section.\n\\end{itemize}\n\n\\chapter{Theme Components}\\label{theme-components}\n\nThis guide provides an overview of the following theme development and\ncustomization topics:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[theme-templates]{Theme Templates}\n\\item\n \\hyperref[css-frameworks-and-extensions]{CSS Frameworks and\n Extensions}\n\\item\n \\hyperref[theme-customizations-and-extensions]{Theme Customizations\n and Extensions}\n\\item\n \\hyperref[portlet-customizations-and-extensions]{Portlet\n Customizations and Extensions}\n\\end{itemize}\n\n\\section{Theme Templates and\nUtilities}\\label{theme-templates-and-utilities}\n\nThe default FreeMarker templates provide helpful utilities and handle\nkey pieces of page layout (page) functionality:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{portal\\_normal.ftl}: Similar to a static site's\n \\texttt{index.html}, this file is the hub for all the theme templates\n and provides the overall markup for the page.\n\\item\n \\texttt{init.ftl}: Contains variables commonly used throughout the\n theme templates. Refer to it to look up theme objects. For\n convenience, the\n \\href{/docs/7-2/reference/-/knowledge_base/r/freemarker-variable-reference-guide}{FreeMarker\n Variable Reference Guide} lists the objects. \\textbf{DO NOT override\n this file}.\n\\item\n \\texttt{init\\_custom.ftl}: Used to override FreeMarker variables in\n \\texttt{init.ftl} and to define new variables, such as\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/making-configurable-theme-settings}{theme\n settings}.\n\\item\n \\texttt{portlet.ftl}: Controls the theme's portlets. If your theme\n uses\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/theming-portlets\\#portlet-decorators}{Portlet\n Decorators}, modify this file to create application decorator-specific\n theme settings.\n\\item\n \\texttt{navigation.ftl}: Contains the navigation markup. To customize\n pages in the navigation, you must use the\n \\texttt{liferay.navigation\\_menu} macro. Then you can leverage\n \\href{https://github.com/liferay/liferay-portal/tree/7.2.x/modules/apps/site-navigation/site-navigation-menu-web/src/main/resources/com/liferay/site/navigation/menu/web/portlet/template/dependencies}{widget\n templates} for the navigation menu. Note that \\texttt{navigation.ftl}\n also defines the hamburger icon and \\texttt{navbar-collapse} class\n that provides the simplified navigation toggle for mobile viewports,\n as shown in the snippet below for the Classic theme:\n\\end{itemize}\n\n\\begin{verbatim}\n<#if has_navigation && is_setup_complete>\n \n\n
\n\n\\end{verbatim}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-mobile-nav.png}\n\\caption{The collapsed navbar provides simplified user-friendly\nnavigation for mobile devices.}\n\\end{figure}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{portal\\_pop\\_up.ftl}: Controls pop up dialogs for the theme's\n portlets. Similar to \\texttt{portal\\_normal.ftl},\n \\texttt{portal\\_pop\\_up.ftl} provides the markup template for all\n pop-up dialogs, such as a portlet's Configuration menu. It also has\n access to the FreeMarker variables defined in \\texttt{init.ftl} and\n \\texttt{init\\_custom.ftl}.\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-theme-templates.png}\n\\caption{Each theme template provides a portion of the page's markup and\nfunctionality.}\n\\end{figure}\n\n\\begin{itemize}\n\\item\n \\href{https://github.com/liferay/liferay-portal/blob/7.2.x/modules/apps/portal-template/portal-template-freemarker/src/main/resources/FTL_liferay.ftl}{\\texttt{FTL\\_Liferay.ftl}}:\n Provides\n \\href{/docs/7-2/reference/-/knowledge_base/r/product-freemarker-macros}{macros}\n for commonly used portlets and theme resources.\n\\item\n \\texttt{taglib-mappings.properties}: Maps the portal taglibs to\n FreeMarker macros. Taglibs can quickly create common UI components.\n This properties file is provided separately for each app taglib. For\n convenience, these FreeMarker macros appear in the\n \\href{/docs/7-2/reference/-/knowledge_base/r/freemarker-taglib-macros}{FreeMarker\n Taglib Mappings reference guide}. See the\n \\href{/docs/7-2/reference/-/knowledge_base/r/front-end-taglibs}{Taglib\n reference} for more information on using each taglib in your theme\n templates.\n\\end{itemize}\n\n\\section{CSS Frameworks and\nExtensions}\\label{css-frameworks-and-extensions}\n\nThemes are integrated with \\href{https://sass-lang.com/}{SASS}, so you\ncan take full advantage of Sass mixins, nesting, partials, and variables\nin your CSS.\n\nAlso important to note is \\href{https://clayui.com/}{Clay CSS}, the web\nimplementation of Liferay's \\href{https://lexicondesign.io/}{Lexicon\ndesign language}. An extension of Bootstrap, Clay CSS fills the gaps\nbetween Bootstrap and the needs of Liferay DXP, providing additional\ncomponents and CSS patterns that you can use in your themes. Clay base,\nLiferay's Bootstrap API extension, along with Atlas, a custom Bootstrap\ntheme, creates Liferay DXP's Classic theme. See\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/customizing-atlas-and-clay-base-themes}{Customizing\nAtlas and Clay Base Themes} for more information.\n\n\\section{Theme Customizations and\nExtensions}\\label{theme-customizations-and-extensions}\n\nThe theme templates, along with the CSS, provide much of the overall\nlook and feel for the page, but additional extension\npoints/customizations are available. The following extensions and\nmechanisms are available for themes:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Color Schemes:} Specifies configurable color scheme settings\n Administrators can configure via the Look and Feel menu. See the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/creating-color-schemes-for-your-theme}{color\n scheme tutorial} for more information.\n\\item\n \\textbf{Configurable Theme Settings:} Administrators can configure\n theme aspects that change frequently, such as the visibility of\n certain elements, changing a daily quote, etc. See the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/making-configurable-theme-settings}{Configurable\n Theme Settings tutorial} for more information.\n\\item\n \\textbf{Context Contributor:} Exposes Java variables and functionality\n for use in FreeMarker templates. This allows non-JSP templating\n languages in themes, widget templates, and any other templates. See\n the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/injecting-additional-context-variables-and-functionality-into-your-theme-templates}{Context\n Contributors tutorial} or more information.\n\\item\n \\textbf{Theme Contributor:} A package containing UI resources, not\n attached to a theme, that you want to include on every page. See the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/packaging-independent-ui-resources-for-your-site}{Theme\n Contributors tutorial} for more information.\n\\item\n \\textbf{Themelet:} Small, extendable, and reusable pieces of code\n containing CSS and JavaScript. They can be shared with other\n developers to provide common components for themes. See\n \\href{/docs/7-2/reference/-/knowledge_base/r/creating-themelets-with-the-themes-generator}{Generating\n Themelets} for more information.\n\\end{itemize}\n\n\\section{Portlet Customizations and\nExtensions}\\label{portlet-customizations-and-extensions}\n\nYou can customize portlets with these mechanisms and extensions:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Portlet FTL Customizations:} Customize the base template\n markup for all portlets. See the\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/theming-portlets}{Theming\n Portlets} for more information.\n\\item\n \\textbf{Widget Templates:} Provides an alternate display style for a\n portlet. Note that not all portlets support widget templates. See the\n \\href{/docs/7-2/user/-/knowledge_base/u/styling-widgets-with-widget-templates}{Widget\n Templates User Guide} for more information.\n\\item\n \\textbf{Portlet Decorator:} Customizes the exterior decoration for a\n portlet. See\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/theming-portlets\\#portlet-decorators}{Portlet\n Decorators} for more information.\n\\item\n \\textbf{Web Content Template:} Defines how structures are displayed\n for web content. See the\n \\href{/docs/7-2/user/-/knowledge_base/u/designing-web-content-with-templates}{Web\n Content Templates User Guide articles} for more information.\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-portlet-customizations.png}\n\\caption{There are several extension points for customizing portlets}\n\\end{figure}\n\n\\section{Related Topics}\\label{related-topics-12}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/understanding-the-page-structure}{Understanding\n the Page Structure}\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/installing-the-theme-generator-and-creating-a-theme}{Installing\n the Theme Generator and Creating a Theme}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/developing-themes}{Developing\n Themes}\n\\end{itemize}\n\n\\chapter{Understanding the Page\nStructure}\\label{understanding-the-page-structure}\n\nUnderstanding the page's structure is crucial to targeting the correct\nmarkup for styling, organizing your content, and creating your site.\nYour page layout is unique to the requirements and design for your site.\nThe Unstyled theme's default page layout is organized into three key\nsections in its \\texttt{portal\\_normal.ftl} template:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Header:} Contains the navigation, site logo and title (if\n shown), and sign-in link when the user isn't logged in.\n\\item\n \\textbf{Main Content:} Contains the portlets or fragments for the\n page.\n\\item\n \\textbf{Footer:} contains additional information, such as the\n copyright or author.\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-sections.png}\n\\caption{The page layout is broken into three key sections.}\n\\end{figure}\n\n\\section{Portlets or Fragments}\\label{portlets-or-fragments}\n\nThe \\texttt{\\#content} \\texttt{Section} makes up the majority of the\npage. Portlets or fragments are contained inside the\n\\texttt{\\#main-content} \\texttt{div}. Liferay DXP ships with a default\nset of applications that provide common functionality, such as forums\nand Wikis, documents and media, blogs, and more. For more information on\nusing Liferay DXP and its native portlets, see the\n\\href{/documentation/user}{User \\& Admin documentation}. You can also\ncreate custom portlets for your site. Portlets can be added via the Add\nMenu (referred to as widget), included in a sitemap through the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/importing-resources-with-a-theme}{Resources\nImporter}, or they can be\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/embedding-portlets-in-themes}{embedded\nin the page's theme}. See the\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{portlet\ntutorials section} for more information on creating and developing\nportlets.\n\nYou can target the elements and IDs shown in the table below to style\nthe page:\n\n\\noindent\\hrulefill\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3333}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3333}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3333}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\nElement\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nID\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\nDescription\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\texttt{div} & \\texttt{\\#wrapper} & The container div for the page\ncontents \\\\\n\\texttt{header} & \\texttt{\\#banner} & The page's header \\\\\n\\texttt{section} & \\texttt{\\#content} \\textgreater{}\n\\texttt{\\#main-content} & The main contents of the page (portlets or\nfragments) \\\\\n\\texttt{footer} & \\texttt{\\#footer} & The page's footer \\\\\n\\end{longtable}\n\n\\noindent\\hrulefill\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-elements.png}\n\\caption{Each section of the page has elements and IDs that you can\ntarget for styling.}\n\\end{figure}\n\nAs shown in the diagram above, you can also add\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/page-fragments}{fragments}\nto a page. Fragments are components---composed of CSS, JavaScript, and\nHTML---that provide key pieces of functionality for the page (i.e.~a\ncarousel or banner). Liferay DXP provides an editor for creating\ncollections of fragments that you can then add to the page. These\nfragments can be edited on the page to suit your vision.\n\n\\section{Layout Templates, Page Templates, and Site\nTemplates}\\label{layout-templates-page-templates-and-site-templates}\n\nThe page layout within the \\texttt{\\#content} Section is determined by\nthe\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/layout-templates-intro}{Layout\nTemplate}. Several layout templates are included out-of-the-box. You can\nalso\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/layout-templates-intro}{create\ncustom layout templates manually} or with the\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-layout-templates-with-the-themes-generator}{Liferay\nTheme Generator's layout sub-generator}.\n\nLayout templates can be pre-configured depending on the\n\\href{/docs/7-2/user/-/knowledge_base/u/creating-pages}{page type} you\nchoose when the page is created. Along with setting the types of\nportlets to include on the page, the page template may also define the\ndefault layout template for the page. Climbing further up the scope\nchain, you can create\n\\href{/docs/7-2/user/-/knowledge_base/u/building-sites-from-templates}{Site\nTemplates}, which can define the pages, page templates, layout\ntemplates, and theme(s) to use for site pages.\n\n\\section{Product Navigation Sidebars and\nPanels}\\label{product-navigation-sidebars-and-panels-1}\n\nThe main page layout also contains a few notable sidebars an\nadministrative user can trigger through the Control Menu. These are\nlisted below:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{Add Menu:} For adding portlets (widgets) and fragments (if\n applicable) to the page\n\\item\n \\textbf{Control Menu:} Provides the main navigation for accessing the\n Add Menu, Product Menu, and Simulation Panel\n\\item\n \\textbf{Product Menu:} Contains administrative apps, configuration\n settings, and user account settings, profile, and dashboard page\n\\item\n \\textbf{Simulation Panel:} Simulates how the page appears on different\n devices\n\\end{itemize}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-nav-control-menu.png}\n\\caption{Remember to account for the product navigation sidebars and\npanels when styling your site.}\n\\end{figure}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-nav-add-menu.png}\n\\caption{The Add Menu pushes the main contents to the left.}\n\\end{figure}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-nav-product-menu.png}\n\\caption{The Product Menu pushes the main contents to the right.}\n\\end{figure}\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/portal-layout-nav-simulation-panel.png}\n\\caption{The Simulation Panel pushes the main contents to the left.}\n\\end{figure}\n\nWhen styling the page, you must keep the navigation menus in mind,\nespecially for absolutely positioned elements, such as a fixed navbar.\nIf the user is logged in and can view the Control Menu, the fixed navbar\nmust have a top margin equal to the Control Menu's height.\n\nSee the\n\\href{/docs/7-2/customization/-/knowledge_base/c/product-navigation}{Product\nNavigation articles} for more information on customizing these menus.\n\n\\section{Related Topics}\\label{related-topics-13}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/creating-layout-templates-with-the-themes-generator}{Creating\n Layout Templates with the Layouts Sub-generator}\n\\item\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/including-layout-templates-with-a-theme}{Bundling\n Layout Templates with a Theme}\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/installing-the-theme-generator-and-creating-a-theme}{Installing\n the Liferay Theme Generator and Creating a Theme}\n\\end{itemize}\n\n\\chapter{Bundle Classloading Flow}\\label{bundle-classloading-flow}\n\nThe OSGi container searches several places for imported classes. It's\nimportant to know where it looks and in what order. Liferay DXP's\nclassloading flow for OSGi bundles follows the OSGi Core specification.\nIt's straightforward, but complex. The figure below illustrates the flow\nand this article walks you through it.\n\n\\begin{figure}\n\\centering\n\\includegraphics{./images/bundle-classloading-flow-chart.png}\n\\caption{This flow chart illustrates classloading in a bundle.}\n\\end{figure}\n\nHere is the algorithm for classloading in a bundle:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n If the class is in a \\texttt{java.*} package, delegate loading to the\n parent classloader. Otherwise, continue.\n\\item\n If the class is in the OSGi Framework's boot delegation list, delegate\n loading to the parent classloader. Otherwise, continue.\n\\item\n If the class is in one of the packages the bundle imports from a wired\n exporter, the exporting bundle's classloader loads it. A \\emph{wired\n exporter} is another bundle's classloader that previously loaded the\n package. If the class isn't found, continue.\n\\item\n If the class is imported by one of the bundle's required bundles, the\n required bundle's classloader loads it.\n\\item\n If the class is in the bundle's classpath (manifest header\n \\texttt{Bundle-ClassPath}), the bundle's classloader loads it.\n Otherwise, continue.\n\\item\n If the class is in the bundle's fragments classpath, the bundle's\n classloader loads it.\n\\item\n If the class is in a package that's dynamically imported using\n \\texttt{DynamicImport-Package} and a wire is established with the\n exporting bundle, the exporting bundle's classloader loads it.\n Otherwise, the class isn't found.\n\\end{enumerate}\n\nCongratulations! Now you know how Liferay DXP finds and loads classes\nfor OSGi bundles.\n\n\\chapter{Finding Extension Points}\\label{finding-extension-points}\n\nLiferay DXP provides many features that help users accomplish their\ntasks. Sometimes, however, you may find it necessary to\n\\href{/docs/7-2/customization/-/knowledge_base/c/liferay-customization}{customize\na built-in feature}. It's easy to \\textbf{find} an area you want to\ncustomize, but it may seem like a daunting task to figure out\n\\textbf{how} to customize it. Liferay DXP was developed for easy\ncustomization, meaning it has many extension points you can use to add\nyour own flavor.\n\nThere's a process you can follow that makes finding an extension point a\nbreeze.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\tightlist\n\\item\n Locate the bundle (module) that provides the functionality you want to\n change.\n\\item\n Find the components available in the module.\n\\item\n Discover the extension points for the components you want to\n customize.\n\\end{enumerate}\n\nThis article demonstrates finding an extension point. It steps through a\nsimple example that locates an extension point for importing LDAP users.\nThe example includes using Liferay DXP's\n\\href{/docs/7-2/user/-/knowledge_base/u/managing-and-configuring-apps\\#using-the-app-manager}{Application\nManager} and\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Felix\nGogo Shell}.\n\n\\section{Locate the Related Module and\nComponent}\\label{locate-the-related-module-and-component}\n\nFirst think of words that describe the application behavior you want to\nchange. The right keywords can help you easily track down the desired\nmodule and its component. Consider the example for importing LDAP users.\nSome candidate keywords for finding the component are \\emph{import},\n\\emph{user}, \\emph{security, }and \\emph{LDAP}.\n\nThe easiest way to discover the module responsible for a particular\nLiferay feature is to use the Application Manager. The Application\nManager lists apps and their included modules/components in an\neasy-to-use interface. It even lists third party apps! You'll use your\nkeywords to target the applicable component.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Open the App Manager by navigating to \\emph{Control Panel} →\n \\emph{Apps} → \\emph{App Manager}. The top level lists independent apps\n and independent modules.\n\\item\n Navigate the apps and modules to find components that might provide\n your desired extension point. Remember to check for your keywords in\n element names. The keyword \\emph{security} is found in the Liferay CE\n Portal Security app. Select it.\n\\item\n The Security application has several modules to inspect. Select the\n \\emph{Liferay Portal Security LDAP Implementation} module.\n\n \\begin{figure}\n \\centering\n \\includegraphics{./images/ldapimplementation-module.png}\n \\caption{The module name can be found using the App Manager.}\n \\end{figure}\n\\item\n Search through the components, applying your keywords as a guide. Copy\n the component name you think best fits the functionality you want to\n customize; you'll inspect it later using the Gogo shell.\n\n \\begin{figure}\n \\centering\n \\includegraphics{./images/usermodellistener-component.png}\n \\caption{The component name can be found using the App Manager.}\n \\end{figure}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** When using the Gogo shell later, understand that it can take \n several tries to find the component you're looking for; Liferay's naming \n conventions facilitate finding extension points in a manageable time frame. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\nNext, you'll use the Gogo shell to inspect the component for extension\npoints.\n\n\\section{Finding Extension Points in a\nComponent}\\label{finding-extension-points-in-a-component}\n\nOnce you have the component that relates to the functionality you want\nto extend, you can use the Gogo shell's Service Component Runtime (SCR)\ncommands to inspect it. You can execute SCR commands using\n\\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Liferay Blade\nCLI} or in\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Gogo\nshell}. This article assumes you're using the Gogo shell.\n\nExecute the following command:\n\n\\begin{verbatim}\nscr:info [COMPONENT_NAME]\n\\end{verbatim}\n\nFor the LDAP example component you copied previously, the command would\nlook like this:\n\n\\begin{verbatim}\nscr:info com.liferay.portal.security.ldap.internal.messaging.UserImportMessageListener\n\\end{verbatim}\n\nThe output includes a lot of information. For this exercise, you're\ninterested in services the component references. They are extension\npoints. For example, here's the reference for the service that imports\nLDAP users:\n\n\\begin{verbatim}\n- _ldapUserImporter: \n com.liferay.portal.security.ldap.exportimport.LDAPUserImporter \n SATISFIED \n 1..1 \n dynamic+greedy\n target=(*) scope=bundle (1 binding):\n * Bound to [7764] from bundle 1754 (com.liferay.portal.security.ldap.impl:2.0.4)\n\\end{verbatim}\n\nThe \\texttt{LDAPUserImporter} is the extension point for customizing the\nLDAP user import process! If none of the references satisfy what you're\nlooking for, search other components from the App Manager.\n\nIf you plan on overriding the referenced service, you'll need to\nunderstand the reference's policy and policy option. In the example, the\npolicy is \\texttt{dynamic} and the policy option is \\texttt{greedy}. If\nthe policy is \\texttt{static} and the policy option is\n\\texttt{reluctant}, binding a new higher ranking service in place of a\nbound service requires reactivating the component or changing the\ntarget. For information on the other policies and policy options, visit\nthe \\href{https://osgi.org/download/r6/osgi.enterprise-6.0.0.pdf}{OSGi\nspecification}, in particular, sections 112.3.5 and 112.3.6. See\n\\href{/docs/7-2/customization/-/knowledge_base/c/overriding-osgi-services}{Overriding\nOSGi Services} to learn how to override a component's service reference.\n\n\\textbf{Important} Not all Liferay extension points are available as\nreferenced services. Service references are common in Declarative\nServices (DS) components, but extension points can be exposed in other\nways too. Here's a brief list of other potential extension points in\nLiferay DXP:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Instances of\n \\texttt{org.osgi.util.tracker.ServiceTracker\\textless{}S,\\ T\\textgreater{}}\n\\item\n Uses of Liferay's \\texttt{Registry.getServiceTracker}\n\\item\n Uses of Liferay's \\texttt{ServiceTrackerMap} or\n \\texttt{ServiceTrackerCollection}\n\\item\n Any other component framework or whiteboard implementation (e.g.,\n HTTP, JAX-RS) that supports tracking services; Blueprint, Apache\n Dependency Manager, etc. could also introduce extension points.\n\\end{itemize}\n\nThere you have it! In the App Manager, you used keywords to find the\nmodule component whose behavior you wanted to change. Then you used Gogo\nshell to find the component extension point for implementing your\ncustomization.\n\n\\chapter{Troubleshooting\nCustomizations}\\label{troubleshooting-customizations}\n\nWhen coding on any platform, you can sometimes run into issues that have\nno clear resolution. This can be particularly frustrating. If you have\nissues building, deploying, or running apps and modules, you want to\nresolve them fast. These frequently asked questions and answers help you\ntroubleshoot and correct problems.\n\nClick a question to view the answer.\n\n{Why aren't my fragment's JSP overrides showing?~{}}\n\n\\begin{verbatim}\n
\n\\end{verbatim}\n\n\\phantomsection\\label{cacheable-web-content-taglibs}\n{Why does my web content break when I refresh the page?~{}}\n\n\\begin{verbatim}\n
Some taglibs, such as the liferay-map taglib, have limitations when used in a cacheable template (e.g., FreeMarker and Velocity). For instance, when the liferay-map taglib is used in a cacheable template and the user refreshes the page, the map does not show.
\n
One possible workaround is to disable cache for the template by editing it and unchecking the cacheable option. Alternatively, you can disable cache for all templates by navigating to System Settings→Template Engines and setting Resource Modification Check to 0.
\n
As best practice, however, we recommend that you don't use taglibs in cacheable web content.
\n\\end{verbatim}\n\n\\chapter{Why doesn't the package I use from the fragment host\nresolve?}\\label{why-doesnt-the-package-i-use-from-the-fragment-host-resolve}\n\nAn OSGi fragment can access all of the fragment host's packages---it\ndoesn't need to import them from another bundle. bnd adds external\npackages the fragment uses (even ones in the fragment host) to the\nfragment's \\texttt{Import-Package:\\ {[}package{]},...} OSGi manifest\nheader. That's fine for packages exported to the OSGi runtime. The\nproblem is, however, when bnd tries to import a host's internal package\n(a package the host doesn't export). The OSGi runtime can't activate the\nfragment because the internal package remains an\n\\texttt{Unresolved\\ requirement}---a fragment shouldn't import a\nfragment host's packages.\n\nResolve the issue by explicitly excluding host packages that the host\ndoesn't export.\n\nFor example, this fragment bundle's JSP uses classes from the fragment\nhost bundle's internal package\n\\texttt{com.liferay.portal.search.web.internal.custom.facet.display.context}:\n\n\\begin{verbatim}\n<%@\npage import=\"com.liferay.portal.search.web.internal.custom.facet.display.context.CustomFacetDisplayContext\" %><%@\npage import=\"com.liferay.portal.search.web.internal.custom.facet.display.context.CustomFacetTermDisplayContext\" %>\n\\end{verbatim}\n\nSince the example host bundle doesn't export the package, the fragment\nbundle can avoid importing the package by using an OSGi manifest header,\nlike the one below, to explicitly exclude the package from package\nimports:\n\n\\begin{verbatim}\nImport-Package: !com.liferay.portal.search.web.internal.*,*\n\\end{verbatim}\n\n\\chapter{Why Aren't JSP overrides I Made Using Fragments\nShowing?}\\label{why-arent-jsp-overrides-i-made-using-fragments-showing}\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} It's strongly recommended to\n\\href{/docs/7-2/customization/-/knowledge_base/c/customizing-jsps}{customize\nJSPs using Liferay DXP's API}. Since overriding a JSP using an OSGi\nfragment is not based on APIs there's no way to guarantee that it will\nfail gracefully. Instead, if your customization is buggy (because of\nyour code or because of a change in Liferay), you are most likely to\nfind out at runtime, where functionality breaks and nasty log errors\ngreet you. Overriding a JSP using a fragment should only be used as a\nlast resort.\n\n\\noindent\\hrulefill\n\nThe fragment module must specify the exact version of the host module. A\nLiferay DXP upgrade might have changed some JSPs in the host module,\nprompting a version update. If this occurs, check that your JSP\ncustomizations are compatible with the updated host JSPs and then update\nyour fragment module's targeted version to match the host module.\n\nFor example, this \\texttt{bnd.bnd} file from a fragment module uses\n\\texttt{Fragment-Host} to specify the host module and host module\nversion:\n\n\\begin{verbatim}\nBundle-Name: custom-login-jsp\nBundle-SymbolicName: custom.login.jsp\nBundle-Version: 1.0.0\nFragment-Host: com.liferay.login.web;bundle-version=\"1.1.18\"\n\\end{verbatim}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/finding-artifacts}{Finding\nversions of deployed modules} is straightforward.\n\n\\section{Related Topics}\\label{related-topics-14}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{JSP\nOverrides using Portlet Filters}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/customizing-jsps}{Customizing\nJSPs}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/finding-artifacts}{Finding\nArtifacts}\n\n\\chapter{Using OSGi Services from EXT\nPlugins}\\label{using-osgi-services-from-ext-plugins}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/service-trackers-for-osgi-services}{\\texttt{ServiceTrackers}}\nare the best way for Ext plugins to access OSGi services. They account\nfor the possibility of OSGi services coming and going.\n\n\\section{Related Topics}\\label{related-topics-15}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/detecting-unresolved-osgi-components}{Detecting\nUnresolved OSGi Components}\n\n\\href{/docs/7-2/customization/-/knowledge_base/c/using-the-felix-gogo-shell}{Felix\nGogo Shell}\n\n\\chapter{Contributing to Liferay\nPortal}\\label{contributing-to-liferay-portal}\n\nLiferay Portal is developed by its community consisting of users,\nenthusiasts, employees, customers, partners, and others. We strongly\nencourage you to contribute to Liferay's open source projects by\nimplementing new features, enhancing existing features, and fixing bugs.\nWe also welcome your participation in our forums, chat, writing\ndocumentation, and translating existing documentation.\n\nLiferay Portal is known for its innovative top quality features. To\nmaintain this reputation, all code changes are reviewed by a core set of\nproject maintainers. We encourage you to join our\n\\href{https://liferay-community.slack.com}{Slack Chat} and introduce\nyourself to the core maintainer(s) and engage them as you contribute to\nthe areas they maintain.\n\nDeveloping features and fixes requires cloning the source tree and\nbuilding Liferay Portal.\n\n\\section{Building Liferay Portal from\nsource}\\label{building-liferay-portal-from-source}\n\nThe first step to contributing to Liferay Portal is to clone the\n\\texttt{liferay-portal} repo from GitHub and build the platform from\nsource code.\n\nPlease follow the instructions for\n\\href{https://portal.liferay.dev/participate/fix-a-bug/building-liferay-source}{building\nLiferay Portal from source code}.\n\nTo better understand the code structure, please also read\n\\href{https://portal.liferay.dev/participate/fix-a-bug/how-the-source-is-organized}{How\nthe source is organized}.\n\n\\section{Tooling}\\label{tooling}\n\n\\href{/docs/7-2/reference/-/knowledge_base/r/tooling}{Liferay tooling}\nfacilitates creating customizations and debugging code. Consider using\nthese Liferay development tools:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/blade-cli}{Blade CLI}: a\n command line interface used to build and manage Liferay Workspaces and\n Liferay Portal projects. This CLI is intended for Gradle or Maven\n development.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/liferay-workspace}{Liferay\n Workspace}: a generated Gradle/Maven environment built to hold and\n manage Liferay Portal projects.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/liferay-dev-studio}{Liferay\n Dev Studio}: an Eclipse-based IDE supporting development for Liferay\n Portal.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/intellij}{Liferay\n IntelliJ Plugin}: a plugin providing support for Liferay Portal\n development with IntelliJ IDEA.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/theme-generator}{Liferay\n Theme Generator}: a generator that creates themes, layouts templates,\n and themelets for Liferay Portal development.\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/js-generator}{Liferay JS\n Generator}: a generator that creates JavaScript portlets with\n JavaScript tooling.\n\\end{itemize}\n\nThe\n\\href{https://portal.liferay.dev/participate/fix-a-bug/ide-support}{Configure\nan IDE for use with the Liferay Source} page, explains how to set up the\nproject in your favorite IDE.\n\n\\section{Additional Resources}\\label{additional-resources}\n\n\\href{https://liferay.dev}{Liferay Community Site}\n\n\\href{https://liferay-community.slack.com/}{Liferay Community Slack\nChat}\n\n\\href{https://liferay.dev/chat}{Liferay Community Slack Chat Self\nInvite}\n\n\\href{https://www.liferay.com/legal/contributors-agreement}{Contributor\nLicense Agreement}\n\n\\href{http://help.github.com/}{General GitHub documentation}\n\n\\href{http://help.github.com/send-pull-requests/}{GitHub pull request\ndocumentation}\n\n\\chapter{Model Listeners}\\label{model-listeners}\n\nModel Listeners implement the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/model/ModelListener.html}{\\texttt{ModelListener}\ninterface}. They are used to listen for persistence events on models and\ndo something in response (either before or after the event).\n\nModel listeners are designed to perform lightweight actions in response\nto a \\texttt{create}, \\texttt{remove}, or \\texttt{update} attempt on an\nentity's database table or a mapping table (for example,\n\\texttt{users\\_roles}). Here are some supported use cases:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Audit Listener: In a separate database, record information about\n updates to an entity's database table.\n\\item\n Cache Clearing Listener: Clear caches that you've added to improve the\n performance of custom code.\n\\item\n Validation Listener: Perform additional validation on a model's\n attribute values before they are persisted to the database.\n\\item\n Entity Update Listener: Do some additional processing when an entity\n table is updated. For example, notify users when changes are made to\n their account.\n\\end{itemize}\n\nThere are also use cases that are not recommended, since they're likely\nto break unpredictably and give you headaches:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Setting a model's attributes in an \\texttt{onBeforeUpdate} call. If\n some other database table has already been updated with the values\n before your model listener is invoked, your database gets out of sync.\n To change how an entity's attributes are set, consider using a\n \\href{/docs/7-2/customization/-/knowledge_base/c/overriding-service-builder-services-service-wrappers}{service\n wrapper} instead.\n\\item\n Wrapping a model. Model listeners are not called when fetching records\n from the database.\n\\item\n Creating worker threads to do parallel processing and querying data\n you updated via your listener. Model listeners are called\n \\emph{before} the database transaction is complete (even the\n \\texttt{onAfter...} methods), so the queries could be executed before\n the database transaction completes.\n\\end{itemize}\n\nIf there is no existing listener on the model, your model listener is\nthe only one that runs. However, there can be multiple listeners on a\nsingle model, and the order in which the listeners run cannot be\ncontrolled.\n\nYou can create a model listener in a module by doing two simple things:\n\n\\begin{itemize}\n\\tightlist\n\\item\n Implement \\texttt{ModelListener}\n\\item\n Register the service in Liferay's OSGi runtime\n\\end{itemize}\n\n\\section{Creating a Model Listener\nClass}\\label{creating-a-model-listener-class}\n\nCreate a \\texttt{-ModelListener} class that extends the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/model/BaseModelListener.html}{\\texttt{BaseModelListener}\nclass}.\n\n\\begin{verbatim}\npackage ...;\n\nimport ...;\n\npublic class CustomEntityListener extends BaseModelListener {\n\n // Override one or more methods from the ModelListener interface.\n \n}\n\\end{verbatim}\n\nIn the body of the class, override any methods from the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/model/ModelListener.html}{\\texttt{ModelListener}\ninterface}. The available methods are listed and described at the end of\nthis article.\n\nIn your model listener class, the parameterized type (for example,\n\\texttt{CustomEntity} in the snippet above) tells the listener's\n\\texttt{ServiceTrackerCustomizer} which model class to register the\nlistener against.\n\n\\section{Register the Model Listener\nService}\\label{register-the-model-listener-service}\n\nRegister the service with Liferay's OSGi runtime for immediate\nactivation. If using Declarative Services, set\n\\texttt{service=\\ ModelListener.class} and \\texttt{immediate=true} in\nthe Component:\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n service = ModelListener.class\n)\n\\end{verbatim}\n\nThat's all there is to preparing a model listener. Now learn what model\nevents you can respond to.\n\n\\section{Listening For Persistence\nEvents}\\label{listening-for-persistence-events}\n\nThe \\texttt{ModelListener} interface provides lots of opportunity to\nlisten for model events:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{\\texttt{onAfterAddAssociation}:} If there's an association\n between two models (if they have a mapping table), use this method to\n do something after an association record is added.\n\\item\n \\textbf{\\texttt{onAfterCreate}:} Use this method to do something after\n the persistence layer's \\texttt{create} method is called.\n\\item\n \\textbf{\\texttt{onAfterRemove}:} Use this method to do something after\n the persistence layer's \\texttt{remove} method is called.\n\\item\n \\textbf{\\texttt{onAfterRemoveAssociation}:} If there's an association\n between two models (if they have a mapping table), do something after\n an association record is removed.\n\\item\n \\textbf{\\texttt{onAfterUpdate}:} Use this method to do something after\n the persistence layer's \\texttt{update} method is called.\n\\item\n \\textbf{\\texttt{onBeforeAddAssociation}:} If there's an association\n between two models (if they have a mapping table), do something before\n an addition to the mapping table.\n\\item\n \\textbf{\\texttt{onBeforeCreate}:} Use this method to do something\n before the persistence layer's \\texttt{create} method is called.\n\\item\n \\textbf{\\texttt{onBeforeRemove}:} Use this method to do something\n before the persistence layer's \\texttt{remove} method is called.\n\\item\n \\textbf{\\texttt{onBeforeRemoveAssociation}:} If there's an association\n between two models (if they have a mapping table), do something before\n a removal from the mapping table.\n\\item\n \\textbf{\\texttt{onBeforeUpdate}:} Use this method to do something\n before the persistence layer's \\texttt{update} method is called.\n\\end{itemize}\n\nLook in Liferay source file\n\\texttt{portal-kernel/src/com/liferay/portal/kernel/service/persistence/impl/BasePersistenceImpl.java},\nparticularly the \\texttt{remove} and \\texttt{update} methods, and you'll\nsee how model listeners are accounted for before (for the\n\\texttt{onBefore...} case) and after (for the \\texttt{onAfter...} case)\nthe model persistence event.\n\nNow that you know how to create model listeners, keep in mind that\nthey're useful as standalone projects or inside of your application. If\nyour application needs to do something (like add a custom entity) every\ntime a User is added in Liferay, you can include the model listener\ninside your application.\n\n\\section{Related Topics}\\label{related-topics-16}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/tutorials/-/knowledge_base/t/upgrading-model-listener-hooks}{Upgrading\n Model Listener Hooks}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\n Builder}\n\\item\n \\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\n Builder Persistence}\n\\end{itemize}\n\n\\chapter{Customizing JSPs}\\label{customizing-jsps}\n\nThere are several different ways to customize JSPs in portlets and the\ncore. Liferay DXP's API provides the safest ways to customize them. If\nyou customize a JSP by other means, new versions of the JSP can render\nyour customization invalid and leave you with runtime errors. It's\nhighly recommended to use one of the API-based ways.\n\n\\section{Using Liferay DXP's API to Override a\nJSP}\\label{using-liferay-dxps-api-to-override-a-jsp}\n\nHere are API-based approaches to overriding JSPs in Liferay DXP:\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.2857}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3571}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3571}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Approach}\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Description}\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Cons/Limitations}\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\href{/docs/7-2/customization/-/knowledge_base/c/customizing-jsps-with-dynamic-includes}{Dynamic\nincludes} & Adds content at dynamic include tags. & Limited to JSPs that\nhave \\texttt{dynamic-include} tags (or tags whose classes inherit from\n\\texttt{IncludeTag}). Only inserts content in the JSPs at the dynamic\ninclude tags. \\\\\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{Portlet\nfilters} & Modifies portlet requests and/or responses to simulate a JSP\ncustomization. & Although this approach doesn't directly customize a\nJSP, it achieves the effect of a JSP customization. \\\\\n\\end{longtable}\n\n\\section{Overriding a JSP Without Using Liferay DXP's\nAPI}\\label{overriding-a-jsp-without-using-liferay-dxps-api}\n\nIt's strongly recommended to customize JSPs using Liferay DXP's API, as\nthe previous section describes. Since overriding a JSP using an OSGi\nfragment or a Custom JSP Bag is not based on APIs there's no way to\nguarantee that they'll fail gracefully. Instead, if your customization\nis buggy (because of your code or because of a change in Liferay), you\nare most likely to find out at runtime, where functionality breaks and\nnasty log errors greet you. These approaches should only be used as a\nlast resort.\n\nIf you're maintaining a JSP customization that uses one of these\napproaches, you should know how they work. This section describes them\nand links to their tutorials.\n\nHere are ways to customize JSPs without using Liferay DXP's API:\n\n\\begin{longtable}[]{@{}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.2857}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3571}}\n >{\\raggedright\\arraybackslash}p{(\\columnwidth - 4\\tabcolsep) * \\real{0.3571}}@{}}\n\\toprule\\noalign{}\n\\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Approach}\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Description}\n\\end{minipage} & \\begin{minipage}[b]{\\linewidth}\\raggedright\n\\textbf{Cons/Limitations}\n\\end{minipage} \\\\\n\\midrule\\noalign{}\n\\endhead\n\\bottomrule\\noalign{}\n\\endlastfoot\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-osgi-fragments}{OSGi\nfragment} & Completely overrides a module's JSP using an OSGi fragment &\nChanges to the original JSP or module can cause runtime errors. \\\\\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-custom-jsp-bag}{Custom\nJSP bag} & Completely override a Liferay DXP core JSP or one of its\ncorresponding \\texttt{-ext.jsp} files. & For Liferay DXP core JSPs only.\nChanges to the original JSP or module can cause runtime errors. \\\\\n\\end{longtable}\n\nAll the JSP customization approaches are available to you. It's time to\ncustomize some JSPs!\n\n\\chapter{Customizing JSPs with Dynamic\nIncludes}\\label{customizing-jsps-with-dynamic-includes}\n\nThe\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/taglibs/util-taglib/liferay-util/dynamic-include.html}{\\texttt{liferay-util:dynamic-include}\ntag} is placeholder into which you can inject content. Every JSP's\ndynamic include tag is an extension point for inserting content (e.g.,\nJavaScript code, HTML, and more). To do this, create a module that has\ncontent you want to insert, register that content with the dynamic\ninclude tag, and deploy your module.\n\n\\noindent\\hrulefill\n\n\\textbf{Note}: If the JSP you want to customize has no\n\\texttt{liferay-util:dynamic-include} tags (or tags whose classes\ninherit from \\texttt{IncludeTag}), you must use a different\ncustomization approach, such as\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{portlet\nfilters}.\n\n\\noindent\\hrulefill\n\nBlogs entries contain a good example of how dynamic includes work. For\nreference, you can download the\n\\href{https://portal.liferay.dev/documents/113763090/114000186/example-dynamic-include-blogs-master.zip}{example\nmodule}.\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Find the \\texttt{liferay-util:dynamic-include} tag where you want to\n insert content and note the tag's key.\n\n The Blogs app's \\texttt{view\\_entry.jsp} has a dynamic include tag at\n the top and another at the very bottom.\n\n\\begin{verbatim}\n<%@ include file=\"/blogs/init.jsp\" %>\n\n\n\n ... JSP content is here\n\n\n\\end{verbatim}\n\n Here are the Blogs view entry dynamic include keys:\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\texttt{key=\"com.liferay.blogs.web\\#/blogs/view\\_entry.jsp\\#pre\"}\n \\item\n \\texttt{key=\"com.liferay.blogs.web\\#/blogs/view\\_entry.jsp\\#post\"}\n \\end{itemize}\n\\item\n \\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{Create\n a module} (e.g., \\texttt{blade\\ create\\ my-dynamic-include}). The\n module will hold your dynamic include implementation.\n\\item\n Specify compile-only dependencies, like these Gradle dependencies, in\n your module build file:\n\n\\begin{verbatim}\ndependencies {\n compileOnly group: \"javax.portlet\", name: \"portlet-api\", version: \"2.0\"\n compileOnly group: \"javax.servlet\", name: \"javax.servlet-api\", version: \"3.0.1\"\n compileOnly group: \"com.liferay\", name: \"com.liferay.petra.string\", version: \"1.0.0\"\n compileOnly group: \"com.liferay.portal\", name: \"com.liferay.portal.kernel\", version: \"2.0.0\"\n compileOnly group: \"org.osgi\", name: \"osgi.cmpn\", version: \"6.0.0\"\n}\n\\end{verbatim}\n\\item\n Create an OSGi component class that implements the\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/servlet/taglib/DynamicInclude.html}{\\texttt{DynamicInclude}\n interface}.\n\n Here's an example dynamic include implementation for Blogs:\n\n\\begin{verbatim}\nimport java.io.IOException;\nimport java.io.PrintWriter;\n\nimport javax.servlet.http.HttpServletRequest;\nimport javax.servlet.http.HttpServletResponse;\n\nimport org.osgi.service.component.annotations.Component;\n\nimport com.liferay.portal.kernel.servlet.taglib.DynamicInclude;\n\n@Component(\n immediate = true,\n service = DynamicInclude.class\n)\npublic class BlogsDynamicInclude implements DynamicInclude {\n\n @Override\n public void include(\n HttpServletRequest request, HttpServletResponse response,\n String key)\n throws IOException {\n\n PrintWriter printWriter = response.getWriter();\n\n printWriter.println(\n \"
Added by Blogs Dynamic Include!
\");\n }\n\n @Override\n public void register(DynamicIncludeRegistry dynamicIncludeRegistry) {\n dynamicIncludeRegistry.register(\n \"com.liferay.blogs.web#/blogs/view_entry.jsp#pre\");\n }\n\n}\n\\end{verbatim}\n\n Giving the class an \\texttt{@Component} annotation that has the\n service attribute \\texttt{service\\ =\\ DynamicInclude.class} makes the\n class a \\texttt{DynamicInclude} service component.\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n service = DynamicInclude.class\n)\n\\end{verbatim}\n\n In the \\texttt{include} method, add your content. The example\n \\texttt{include} method writes a heading.\n\n\\begin{verbatim}\n@Override\npublic void include(\n HttpServletRequest request, HttpServletResponse response,\n String key)\n throws IOException {\n\n PrintWriter printWriter = response.getWriter();\n\n printWriter.println(\n \"
Added by Blogs Dynamic Include!
\");\n}\n\\end{verbatim}\n\n In the \\texttt{register} method, specify the dynamic include tag to\n use. The example register method targets the dynamic include at the\n top of the Blogs \\texttt{view\\_entry.jsp}.\n\n\\begin{verbatim}\n@Override\npublic void register(DynamicIncludeRegistry dynamicIncludeRegistry) {\n dynamicIncludeRegistry.register(\n \"com.liferay.blogs.web#/blogs/view_entry.jsp#pre\");\n}\n\\end{verbatim}\n\\end{enumerate}\n\nOnce you've\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{deployed\nyour module}, the JSP dynamically includes your content. Congratulations\non injecting dynamic content into a JSP!\n\n\\chapter{JSP Overrides Using Portlet\nFilters}\\label{jsp-overrides-using-portlet-filters}\n\nPortlet filters let you intercept portlet requests before they're\nprocessed and portlet responses after they're processed but before\nthey're sent back to the client. You can operate on the request and / or\nresponse to modify the JSP content. Unlike dynamic includes, portlet\nfilters give you access to all the content sent back to the client.\n\nThis demonstration uses a portlet filter to modify content in Liferay's\nBlogs portlet. For reference, you can download the\n\\href{https://portal.liferay.dev/documents/113763090/114000186/example-portlet-filter-customize-jsp-master.zip}{example\nmodule}.\n\nFollow these steps:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n Create a new module and make sure it specifies these compile-only\n dependencies, shown here in Gradle format:\n\n\\begin{verbatim}\ndependencies {\n compileOnly group: \"javax.portlet\", name: \"portlet-api\", version: \"2.0\"\n compileOnly group: \"javax.servlet\", name: \"javax.servlet-api\", version: \"3.0.1\"\n compileOnly group: \"com.liferay.portal\", name: \"com.liferay.portal.kernel\", version: \"2.0.0\"\n compileOnly group: \"org.osgi\", name: \"osgi.cmpn\", version: \"6.0.0\"\n}\n\\end{verbatim}\n\\item\n Create an OSGi component class that implements the\n \\texttt{javax.portlet.filter.RenderFilter} interface.\n\n Here's an example portlet filter implementation for Blogs:\n\n\\begin{verbatim}\nimport java.io.IOException;\n\nimport javax.portlet.PortletException;\nimport javax.portlet.RenderRequest;\nimport javax.portlet.RenderResponse;\nimport javax.portlet.filter.FilterChain;\nimport javax.portlet.filter.FilterConfig;\nimport javax.portlet.filter.PortletFilter;\nimport javax.portlet.filter.RenderFilter;\nimport javax.portlet.filter.RenderResponseWrapper;\n\nimport org.osgi.service.component.annotations.Component;\n\nimport com.liferay.portal.kernel.util.PortletKeys;\n\n@Component(\n immediate = true,\n property = {\n \"javax.portlet.name=\" + PortletKeys.BLOGS\n },\n service = PortletFilter.class\n)\npublic class BlogsRenderFilter implements RenderFilter {\n\n @Override\n public void init(FilterConfig config) throws PortletException {\n\n }\n\n @Override\n public void destroy() {\n\n }\n\n @Override\n public void doFilter(RenderRequest request, RenderResponse response, FilterChain chain)\n throws IOException, PortletException {\n\n RenderResponseWrapper renderResponseWrapper = new BufferedRenderResponseWrapper(response);\n\n chain.doFilter(request, renderResponseWrapper);\n\n String text = renderResponseWrapper.toString();\n\n if (text != null) {\n String interestingText = \"= 0) {\n String newText1 = text.substring(0, index);\n String newText2 = \"\\n
Added by Blogs Render Filter!
\\n\";\n String newText3 = text.substring(index);\n\n String newText = newText1 + newText2 + newText3;\n\n response.getWriter().write(newText);\n }\n }\n }\n\n}\n\\end{verbatim}\n\\item\n Make your class a \\texttt{PortletFilter} service component by giving\n it the \\texttt{@Component} annotation that has the service attribute\n \\texttt{service\\ \\ \\ \\ \\ \\ =\\ PortletFilter.class}. Target the portlet\n whose content you're overriding by assigning it a javax.portlet.name\n property that's the same as your portlet's key. Here's the example\n \\texttt{@Component} annotation:\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n property = {\n \"javax.portlet.name=\" + PortletKeys.BLOGS\n },\n service = PortletFilter.class\n)\n\\end{verbatim}\n\\item\n Override the \\texttt{doFilterMethod} to operate on the request or\n response to produce the content you want. The example appends a\n paragraph stating \\texttt{Added\\ \\ \\ \\ \\ \\ by\\ Blogs\\ Render\\ Filter!}\n to the portlet content:\n\n\\begin{verbatim}\n@Override\npublic void doFilter(RenderRequest request, RenderResponse response, FilterChain chain)\n throws IOException, PortletException {\n\n RenderResponseWrapper renderResponseWrapper = new BufferedRenderResponseWrapper(response);\n\n chain.doFilter(request, renderResponseWrapper);\n\n String text = renderResponseWrapper.toString();\n\n if (text != null) {\n String interestingText = \"= 0) {\n String newText1 = text.substring(0, index);\n String newText2 = \"\\n
Added by Blogs Render Filter!
\\n\";\n String newText3 = text.substring(index);\n\n String newText = newText1 + newText2 + newText3;\n\n response.getWriter().write(newText);\n }\n }\n}\n\\end{verbatim}\n\n The example uses a \\texttt{RenderResponseWrapper} extension class\n called \\texttt{BufferedRenderResponseWrapper}.\n \\texttt{BufferedRenderResponseWrapper} is a helper class whose\n \\texttt{toString} method returns the current response text and whose\n \\texttt{getWriter} method lets you write data to the response before\n it's sent back to the client.\n\n\\begin{verbatim}\nimport java.io.CharArrayWriter;\nimport java.io.IOException;\nimport java.io.OutputStream;\nimport java.io.PrintWriter;\n\nimport javax.portlet.RenderResponse;\nimport javax.portlet.filter.RenderResponseWrapper;\n\npublic class BufferedRenderResponseWrapper extends RenderResponseWrapper {\n\n public BufferedRenderResponseWrapper(RenderResponse response) {\n super(response);\n\n charWriter = new CharArrayWriter();\n }\n\n public OutputStream getOutputStream() throws IOException {\n if (getWriterCalled) {\n throw new IllegalStateException(\"getWriter already called\");\n }\n\n getOutputStreamCalled = true;\n\n return super.getPortletOutputStream();\n }\n\n public PrintWriter getWriter() throws IOException {\n if (writer != null) {\n return writer;\n }\n\n if (getOutputStreamCalled) {\n throw new IllegalStateException(\"getOutputStream already called\");\n }\n\n getWriterCalled = true;\n\n writer = new PrintWriter(charWriter);\n\n return writer;\n }\n\n public String toString() {\n String s = null;\n\n if (writer != null) {\n s = charWriter.toString();\n }\n\n return s;\n }\n\n protected CharArrayWriter charWriter;\n protected PrintWriter writer;\n protected boolean getOutputStreamCalled;\n protected boolean getWriterCalled;\n\n}\n\\end{verbatim}\n\\end{enumerate}\n\nOnce you've\n\\href{/docs/7-2/reference/-/knowledge_base/r/deploying-a-project}{deployed\nyour module}, the portlet's JSP shows your custom content.\n\nYour portlet filter operates directly on portlet response content.\nUnlike dynamic includes, portlet filters let you work with all of a\nJSP's content.\n\n\\chapter{JSP Overrides Using OSGi\nFragments}\\label{jsp-overrides-using-osgi-fragments}\n\nYou can completely override JSPs using OSGi fragments. This approach is\npowerful but can make things unstable when the host module is upgraded:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\tightlist\n\\item\n By overriding an entire JSP, you might not account for new content or\n new widgets essential to new host module versions.\n\\item\n Fragments are tied to a specific host module version. If the host\n module is upgraded, the fragment detaches from it. In this scenario,\n the original JSPs are still available and the module is functional\n (but lacks your JSP enhancements).\n\\item\n Liferay cannot guarantee that JSPs overridden by fragments can be\n upgraded.\n\\end{enumerate}\n\nUsing OSGi fragments to override JSPs is a bad practice, equivalent to\nusing Ext plugins to customize Liferay DXP. They should only be used as\na last resort. Liferay's API based approaches to overriding JSPs (i.e.,\n\\href{/docs/7-2/customization/-/knowledge_base/c/customizing-jsps-with-dynamic-includes}{Dynamic\nIncludes} and\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{Portlet\nFilters}), on the other hand, provide more stability as they customize\nspecific parts of JSPs that are safe to override. Also, the API based\napproaches don't limit your override to a specific host module version.\nIf you are maintaining existing JSP overrides that use OSGi fragments,\nhowever, this tutorial explains how they work.\n\nAn OSGi fragment that overrides a JSP requires these two things:\n\n\\begin{itemize}\n\\item\n The host module's symbolic name and version in the OSGi header\n \\texttt{Fragment-Host} declaration.\n\\item\n The original JSP with any modifications you need to make.\n\\end{itemize}\n\nFor more information about fragment modules, you can refer to section\n3.14 of the\n\\href{https://osgi.org/specification/osgi.core/7.0.0/framework.module.html}{OSGi\nAlliance's core specification document}.\n\n\\section{Declaring a Fragment Host}\\label{declaring-a-fragment-host}\n\nThere are two players in this game: the fragment and the host. The\nfragment is a parasitic module that attaches itself to a host. That\nsounds harsh, so let's compare the fragment-host relationship to the\nrelationship between a pilot fish and a huge, scary shark. It's\nsymbiotic, really. Your fragment module benefits by not doing much work\n(like the pilot fish who benefits from the shark's hunting prowess). In\nreturn, the host module gets whatever benefits you've conjured up in\nyour fragment's JSPs (for the shark, it gets free dental cleanings!). To\nthe OSGi runtime, your fragment is part of the host module.\n\nYour fragment must declare two things to the OSGi runtime regarding the\nhost module:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n The Bundle Symbolic Name of the host module. This is the module\n containing the original JSP.\n\\item\n The exact version of the host module to which the fragment belongs.\n\\end{enumerate}\n\nBoth are declared using the OSGi manifest header \\texttt{Fragment-Host}.\n\n\\begin{verbatim}\nFragment-Host: com.liferay.login.web;bundle-version=\"[1.0.0,1.0.1)\"\n\\end{verbatim}\n\nSupplying a specific host module version is important. If that version\nof the module isn't present, your fragment won't attach itself to a\nhost, and that's a good thing. A new version of the host module might\nhave changed its JSPs, so if your now-incompatible version of the JSP is\napplied to the host module, you'll break the functionality of the host.\nIt's better to detach your fragment and leave it lonely in the OSGi\nruntime than it is to break the functionality of an entire application.\n\n\\section{Provide the Overridden JSP}\\label{provide-the-overridden-jsp}\n\nThere are two possible naming conventions for targeting the host\noriginal JSP: \\texttt{portal} or \\texttt{original}. For example, if the\noriginal JSP is in the folder \\texttt{/META-INF/resources/login.jsp},\nthen the fragment bundle should contain a JSP with the same path, using\nthe following pattern:\n\n\\begin{verbatim}\n\" \n/>\n\\end{verbatim}\n\nAfter that, make your modifications. Just make sure you mimic the host\nmodule's folder structure when overriding its JAR. If you're overriding\nLiferay's login application's \\texttt{login.jsp} for example, you'd put\nyour own \\texttt{login.jsp} in\n\n\\begin{verbatim}\nmy-jsp-fragment/src/main/resources/META-INF/resources/login.jsp\n\\end{verbatim}\n\nIf you must post-process the output, you can update the pattern to\ninclude Liferay DXP's buffering mechanism. Below is an example that\noverrides the original \\texttt{create\\_account.jsp}:\n\n\\begin{verbatim}\n<%@ include file=\"/init.jsp\" %>\n\n\n \"/>\n\n\n\" />\n\n\n\n\n\n\n \" message=\"no-such-registration-code\" />\n\n\n\n \n \n \n\n\n<%\n html = com.liferay.portal.kernel.util.StringUtil.replace(html, \n openIdFieldHtml, openIdFieldHtml + errorMessageHtml);\n html = com.liferay.portal.kernel.util.StringUtil.replace(html, \n userNameFieldsHtml, userNameFieldsHtml + registrationCodeFieldHtml);\n%>\n\n<%=html %>\n\\end{verbatim}\n\n\\section{Using Fragment Host Internal\nPackages}\\label{using-fragment-host-internal-packages}\n\nTo use an internal (unexported) host package, the fragment must\nexplicitly exclude the package from its \\texttt{Import-Package:}\nmanifest header. For example, this \\texttt{Import-Package} header\nexcludes packages that match\n\\texttt{com.liferay.portal.search.web.internal.*}.\n\n\\begin{verbatim}\nImport-Package: !com.liferay.portal.search.web.internal.*,*\n\\end{verbatim}\n\nUnless you explicitly exclude the package, bnd adds the package to the\n\\texttt{Import-Package:} header. Attempting to start the fragment while\nrequiring an unexported package fails because the package is an\nunresolved requirement. For this reason, make sure to exclude such\npackages from your fragment's \\texttt{Import-Package:} header.\n\nEach fragment has full access to the host packages, including its\ninternal (unexported) packages already.\n\nNow you can easily modify the JSPs of any application in Liferay.\n\n\\includegraphics{./images/sharks.jpg}\n\n\\section{Related Topics}\\label{related-topics-17}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{JSP\n Overrides Using Portlet Filters}\n\\end{itemize}\n\n\\chapter{JSP Overrides Using Custom JSP\nBag}\\label{jsp-overrides-using-custom-jsp-bag}\n\nLiferay's API based approaches to overriding JSPs (i.e.,\n\\href{/docs/7-2/customization/-/knowledge_base/c/customizing-jsps-with-dynamic-includes}{Dynamic\nIncludes} and\n\\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{Portlet\nFilters}) are the best way to override JSPs in apps and in the core. You\ncan also use Custom JSP Bags to override core JSPs. But the approach is\nnot as stable as the API based approaches. If your Custom JSP Bag's JSP\nis buggy (because of your code or because of a change in Liferay), you\nare most likely to find out at runtime, where functionality breaks and\nnasty log errors greet you. Using Custom JSP Bags to override JSPs is a\nbad practice, equivalent to using Ext plugins to customize Liferay DXP.\nIf you're maintaining existing Custom JSP Bags, however, this tutorial\nexplains how they work.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Liferay cannot guarantee that JSPs overridden using\nCustom JSP Bag can be upgraded.\n\n\\noindent\\hrulefill\n\nA Custom JSP Bag module must satisfy these criteria:\n\n\\begin{itemize}\n\\item\n Provides and specifies a custom JSP for the JSP you're extending.\n\\item\n Includes a\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-impl/com/liferay/portal/deploy/hot/CustomJspBag.html}{\\texttt{CustomJspBag}}\n implementation for serving the custom JSPs.\n\\end{itemize}\n\nThe module provides transportation for this code into Liferay's OSGi\nruntime. After you\n\\href{/docs/7-2/reference/-/knowledge_base/r/creating-a-project}{create\nyour new module}, continue with providing your custom JSP.\n\n\\section{Providing a Custom JSP}\\label{providing-a-custom-jsp}\n\nCreate your JSPs to override Liferay DXP core JSPs. If you're using the\nMaven\n\\href{https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html}{Standard\nDirectory Layout}, place your JSPs under\n\\texttt{src/main/resources/META-INF/jsps}. For example, if you're\noverriding\n\n\\begin{verbatim}\nportal-web/docroot/html/common/themes/bottom-ext.jsp \n\\end{verbatim}\n\nplace your custom JSP at\n\n\\begin{verbatim}\n[your module]/src/main/resources/META-INF/jsps/html/common/themes/bottom-ext.jsp\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} If you place custom JSPs somewhere other than\n\\texttt{src/main/resources/META-INF/jsps} in your module, assign that\nlocation to a \\texttt{-includeresource:\\ META-INF/jsps=} directive in\nyour module's \\texttt{bnd.bnd} file. For example, if you place custom\nJSPs in a folder \\texttt{src/META-INF/custom\\_jsps} in your module,\nspecify this in your \\texttt{bnd.bnd}:\n\n\\begin{verbatim}\n -includeresource: META-INF/jsps=src/META-INF/custom_jsps\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\section{Implement a Custom JSP Bag}\\label{implement-a-custom-jsp-bag}\n\nLiferay DXP (specifically the\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-impl/com/liferay/portal/deploy/hot/CustomJspBagRegistryUtil.html}{\\texttt{CustomJspBagRegistryUtil}\nclass}) loads JSPs from\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-impl/com/liferay/portal/deploy/hot/CustomJspBag.html}{\\texttt{CustomJspBag}}\nservices. Here are steps for implementing a custom JSP bag.\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\item\n In your module, create a class that implements\n \\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-impl/com/liferay/portal/deploy/hot/CustomJspBag.html}{\\texttt{CustomJspBag}}.\n\\item\n Register your class as an OSGi service by adding an\n \\texttt{@Component} annotation to it, like this:\n\n\\begin{verbatim}\n@Component(\n immediate = true,\n property = {\n \"context.id=BladeCustomJspBag\",\n \"context.name=Test Custom JSP Bag\",\n \"service.ranking:Integer=100\"\n }\n)\n\\end{verbatim}\n\n \\begin{itemize}\n \\tightlist\n \\item\n \\textbf{\\texttt{immediate\\ =\\ true}:} Makes the service available on\n module activation.\n \\item\n \\textbf{\\texttt{context.id}:} Your custom JSP bag class name.\n Replace \\texttt{BladeCustomJspBag} with your class name.\n \\item\n \\textbf{\\texttt{context.name}:} A more human readable name for your\n service. Replace it with a name of your own.\n \\item\n \\textbf{\\texttt{service.ranking:Integer}:} A priority for your\n implementation. The container chooses the implementation with the\n highest priority.\n \\end{itemize}\n\\item\n Implement the \\texttt{getCustomJspDir} method to return the folder\n path in your module's JAR where the JSPs reside (for example,\n \\texttt{META-INF/jsps}).\n\n\\begin{verbatim}\n@Override\npublic String getCustomJspDir() {\n return \"META-INF/jsps/\";\n}\n\\end{verbatim}\n\\item\n Create an \\texttt{activate} method and the following fields. The\n method adds the URL paths of all your custom JSPs to a list when the\n module is activated.\n\n\\begin{verbatim}\n@Activate\nprotected void activate(BundleContext bundleContext) {\n _bundle = bundleContext.getBundle();\n\n _customJsps = new ArrayList<>();\n\n Enumeration entries = _bundle.findEntries(\n getCustomJspDir(), \"*.jsp\", true);\n\n while (entries.hasMoreElements()) {\n URL url = entries.nextElement();\n\n _customJsps.add(url.getPath());\n }\n}\n\nprivate Bundle _bundle;\nprivate List _customJsps;\n\\end{verbatim}\n\\item\n Implement the \\texttt{getCustomJsps} method to return the list of this\n module's custom JSP URL paths.\n\n\\begin{verbatim}\n@Override\npublic List getCustomJsps() {\n return _customJsps;\n}\n\\end{verbatim}\n\\item\n Implement the \\texttt{getURLContainer} method to return a new\n \\texttt{com.liferay.portal.kernel.url.URLContainer}. Instantiate the\n URL container and override its \\texttt{getResources} and\n \\texttt{getResource} methods. The \\texttt{getResources} method looks\n up all the paths to resources in the container by a given path. It\n returns a \\texttt{HashSet} of \\texttt{Strings} for the matching custom\n JSP paths. The \\texttt{getResource} method returns one specific\n resource by its name (the path included).\n\n\\begin{verbatim}\n@Override\npublic URLContainer getURLContainer() {\n return _urlContainer;\n}\n\nprivate final URLContainer _urlContainer = new URLContainer() {\n\n @Override\n public URL getResource(String name) {\n return _bundle.getEntry(name);\n }\n\n @Override\n public Set getResources(String path) {\n Set paths = new HashSet<>();\n\n for (String entry : _customJsps) {\n if (entry.startsWith(path)) {\n paths.add(entry);\n }\n }\n\n return paths;\n }\n\n};\n\\end{verbatim}\n\\item\n Implement the \\texttt{isCustomJspGlobal} method to return\n \\texttt{true}.\n\n\\begin{verbatim}\n@Override\npublic boolean isCustomJspGlobal() {\n return true;\n}\n\\end{verbatim}\n\\end{enumerate}\n\nNow your module provides custom JSPs and a custom JSP bag\nimplementation. When you deploy it, Liferay DXP uses its custom JSPs in\nplace of the core JSPs they override.\n\n\\section{Extend a JSP}\\label{extend-a-jsp}\n\nIf you want to add something to a core JSP, see if it has an empty\n\\texttt{-ext.jsp} and override that instead of the whole JSP. It keeps\nthings simpler and more stable, since the full JSP might change\nsignificantly, breaking your customization in the process. By overriding\nthe \\texttt{-ext.jsp}, you're only relying on the original JSP including\nthe \\texttt{-ext.jsp}. For an example, open\n\\texttt{portal-web/docroot/html/common/themes/bottom.jsp}, and scroll to\nthe end. You'll see this:\n\n\\begin{verbatim}\n\n\\end{verbatim}\n\nIf you must add something to \\texttt{bottom.jsp}, override\n\\texttt{bottom-ext.jsp}.\n\nSince Liferay DXP 7.0, the content from the following JSP files formerly\nin \\texttt{html/common/themes} are inlined to improve performance.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{body\\_bottom-ext.jsp}\n\\item\n \\texttt{body\\_top-ext.jsp}\n\\item\n \\texttt{bottom-ext.jsp}\n\\item\n \\texttt{bottom-test.jsp}\n\\end{itemize}\n\nThey're no longer explicit files in the code base. But you can still\ncreate them in your module to add functionality and content.\n\nRemember, this type of customization is a last resort. Your override may\nbreak due to the nature of this implementation, and core functionality\nin Liferay can go down with it. If the JSP you want to override is in\nanother module, refer to the API based approaches to overriding JSPs\nmentioned at the beginning of the article.\n\n\\section{Site Scoped JSP\nCustomization}\\label{site-scoped-jsp-customization}\n\nIn Liferay Portal 6.2, you could use\n\\href{/docs/6-2/tutorials/-/knowledge_base/t/customizing-sites-and-site-templates-with-application-adapters}{Application\nAdapters} to scope your core JSP customizations to a specific Site.\nSince the majority of JSPs were moved into modules for Liferay DXP 7.0,\nthe use case for this has shrunk considerably. If you must scope a core\nJSP customization to a Site, prepare an application adapter\n\\href{/docs/6-2/tutorials/-/knowledge_base/t/customizing-sites-and-site-templates-with-application-adapters}{as\nyou would have for Liferay Portal 6.2}, and deploy it to 7.0. It will\nstill work. However, note that this approach is deprecated in 7.0 and\nwon't be supported at all in Liferay 8.0.\n\n\\section{Related Topics}\\label{related-topics-18}\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\href{/docs/7-1/tutorials/-/knowledge_base/t/upgrading-core-jsp-hooks}{Upgrading\n Core JSP Hooks}\n\\item\n \\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-portlet-filters}{JSP\n Overrides Using Portlet Filters}\n\\end{itemize}\n\n\\chapter{Overriding Inline Content Using\nJSPs}\\label{overriding-inline-content-using-jsps}\n\nSome Liferay DXP core content, such as tag library tags, can only be\noverridden using JSPs ending in \\texttt{.readme}. The suffix\n\\texttt{.readme} facilitates finding them. The code from these JSPs is\nnow inlined (brought into Liferay DXP Java source files) to improve\nperformance. Liferay DXP ignores JSP files with the \\texttt{.readme}\nsuffix. If you add code to a JSP \\texttt{.readme} file and remove the\n\\texttt{.readme} suffix, Liferay DXP uses that JSP instead of the core\ninline content. This tutorial shows you how to make these\ncustomizations.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} This type of customization is a last resort. Your\noverride may break due to the nature of this implementation, and core\nfunctionality can go down with it. Liferay cannot guarantee that content\noverridden using JSP \\texttt{.readme} files can be upgraded.\n\n\\noindent\\hrulefill\n\n\\noindent\\hrulefill\n\n\\textbf{Warning:} Modifying a Liferay DXP tag library tag affects all\nuses of that tag in your Liferay DXP installation.\n\n\\noindent\\hrulefill\n\nHere's how to override inline content using JSPs:\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\tightlist\n\\item\n Create a\n \\href{/docs/7-2/customization/-/knowledge_base/c/jsp-overrides-using-custom-jsp-bag}{Custom\n JSP Bag} for deploying your JSP. Note the module folder you're storing\n the JSPs in: the default folder is\n \\texttt{{[}your\\ module{]}/src/main/resources/META-INF/jsps/}\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** you can develop your JSP anywhere, but a Custom JSP Bag module \n provides a straightforward way to build and deploy it.\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{1}\n\\item\n Download the Liferay DXP source code or browse the source code on\n \\href{https://github.com/liferay/liferay-portal/tree/7.2.x}{GitHub\n (Liferay Portal CE)}.\n\\item\n Search the source code for a \\texttt{.jsp.readme} file that overrides\n the tag you're customizing.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Files ending in `-ext.jsp.readme` let you prepend or\n append new content to existing content. Examples include the\n `bottom-test.jsp.readme`, `bottom-ext.jsp.readme`,\n `body_top-ext.jsp.readme`, and `body_bottom-ext.jsp.readme` files in\n the Liferay DXP application's `portal-web/docroot/html/common/themes` folder.\n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{3}\n\\item\n Copy the \\texttt{.jsp.readme} file into your project and drop the\n \\texttt{.readme} suffix. Use the same relative file path Liferay DXP\n uses for the \\texttt{.jsp.readme} file. For example, if the file in\n Liferay DXP is\n\n\\begin{verbatim}\nportal-web/docroot/html/taglib/aui/fieldset/start.jsp.readme\n\\end{verbatim}\n\n use file path\n\n\\begin{verbatim}\n[your module]/src/main/resources/META-INF/jsps/html/taglib/aui/fieldset/start.jsp\n\\end{verbatim}\n\\item\n Familiarize yourself with the current UI content and logic, so you can\n override it appropriately. Tag library tag content logic, for example,\n is in the respective \\texttt{*Tag.java} file under\n \\texttt{util-taglib/src/com/liferay/taglib/{[}tag\\ library{]}/}.\n\\item\n Develop your new logic, keeping in mind the current inline logic\n you're replacing.\n\\item\n Deploy your JSP.\n\\end{enumerate}\n\nLiferay DXP uses your JSP in place of the current inline logic. If you\nwant to walk through an example override, continue with this tutorial.\nOtherwise, congratulations on a modified \\texttt{.jsp.readme} file to\noverride core inline content!\n\n\\section{Example: Overriding the fieldset Taglib\nTag}\\label{example-overriding-the-fieldset-taglib-tag}\n\nThis example demonstrates changing the \\texttt{liferay:aui} tag\nlibrary's \\texttt{fieldset} tag. Browsing the Liferay DXP web\napplication or the source code at\n\\texttt{portal-web/docroot/html/taglib/aui/fieldset} reveals these\nfiles:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\texttt{start.jsp.readme}\n\\item\n \\texttt{end.jsp.readme}\n\\end{itemize}\n\nThey can override the logic that creates the start and end of the\n\\texttt{fieldset} tag. The \\texttt{FieldsetTag.java} class's\n\\texttt{processStart} and \\texttt{processEnd} methods implement the\ncurrent inline content. Here's the\n\\href{https://github.com/liferay/liferay-portal/blob/7.2.x/util-taglib/src/com/liferay/taglib/aui/FieldsetTag.java\\#L86-L141}{\\texttt{processStart}}\nmethod:\n\n\\begin{verbatim}\n@Override\nprotected int processStartTag() throws Exception {\n JspWriter jspWriter = pageContext.getOut();\n\n jspWriter.write(\"
![\"Liferay](\"guidelines/images/liferayDeveloperNetworkSmallerEdit7.jpg\")
\n![\"React](\"/o/react-guestbook-migrated/logo.png\"){kind=logo}
\n\\end{verbatim}\n\\item\n Merge your entry module with \\texttt{src/index.js}, configuring it to\n dynamically load components.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Components must be loaded dynamically to attach to the portlet's\n DOM. The DOM is determined at run time when the portlet's page is\n rendered. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n- Use the `HashRouter` for routing between component views, as Liferay DXP \n requires hash routing for proper portal navigation:\n\n ```javascript\n import { HashRouter as Router } from 'react-router-dom';\n ```\n\n- Place your code inside the `main()` function.\n\n- Render your app inside the `portletElementId` element that is passed in \n the `main()` function. This is required to render the React app inside\n the portlet.\n\nYour entry module `index.js` should look like this. \n\n```javascript\nimport React from 'react';\nimport ReactDOM from 'react-dom';\n//import './index.css';//removed for Portal Migration\nimport App from './App';\nimport { HashRouter as Router } from 'react-router-dom';\n\nexport default function main({portletNamespace, contextPath, \nportletElementId}) {\n ReactDOM.render((\n ![\"Vue](\"/o/vue-guestbook-migrated/logo.png\"){kind=logo}
\n\\end{verbatim}\n\\item\n Merge your entry module with \\texttt{src/index.js}, following these\n steps to dynamically load components.\n\\end{enumerate}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n **Note:** Components must be loaded dynamically to attach to the portlet's\n DOM. The DOM is determined at runtime when the portlet's page is\n rendered. \n\\end{verbatim}\n\n\\noindent\\hrulefill\n\n\\begin{verbatim}\n- Use Vue's runtime + compiler module \n (`import Vue from 'vue/dist/vue.common';`) so you don't have to process \n templates during build time. This is imported by default at the top of \n the file.\n\n- Remove the sample content from the `main()` function (i.e. the `node` \n constant and its use), and replace it with your router code.\n\n- Make these updates to the `new Vue` instance:\n\n - Remove the default data properties (the ones you just removed in the \n sample content), and set the render element to `portletElementId`. \n This is required and ensures that your app is rendered inside the \n portlet.\n - Add the router.\n - Add a render function that mounts your component wrapper to the Vue \n instance and displays it.\n \n Your updated configuration should look like this:\n\n ```javascript\n new Vue({\n el: `#${portletElementId}`,\n render: h => h(App),\n router\n })\n ```\n\nYour entry module `index.js` should look like this. \n\n```javascript\nimport Vue from 'vue/dist/vue.common';\nimport App from './App.vue'\nimport VueRouter from 'vue-router'\n//Component imports\n\nexport default function main({portletNamespace, contextPath, portletElementId}) {\n\n Vue.config.productionTip = false\n\n Vue.use(VueRouter)\n\n const router = new VueRouter({\n routes: [\n {\n ...\n }\n ]\n })\n new Vue({\n el: `#${portletElementId}`,\n render: h => h(App),\n router\n })\n}\n```\n\\end{verbatim}\n\n\\begin{enumerate}\n\\def\\labelenumi{\\arabic{enumi}.}\n\\setcounter{enumi}{6}\n\\item\n Merge your app \\texttt{package.json} file's \\texttt{dependencies} and\n \\texttt{devDependencies} into the project's \\texttt{package.json}, and\n replace the \\texttt{babel-cli} and \\texttt{babel-preset-env} dev\n dependencies with the newer \\texttt{\"@babel/cli\":\\ \"\\^{}7.0.0\"} and\n \\texttt{\"@babel/preset-env\":\\ \"\\^{}7.4.2\"} packages instead. Also\n include the \\texttt{\"vueify\":\\ \"9.4.1\"} dev dependency.\n\\item\n Update the \\texttt{.babelrc} file to use \\texttt{@babel/preset-env}\n instead of \\texttt{env}:\n\n\\begin{verbatim}\n\"presets\": [\"@babel/preset-env\"]\n\\end{verbatim}\n\\item\n If you're using \\texttt{.vue} files, replace the build script in the\n \\texttt{package.json} with the one below to use\n \\texttt{vue-cli-service}. The updated build script uses vue-cli to\n access the main entrypoint for the app (\\texttt{index.js} in the\n example below) and combines all the Vue templates and JS files into\n one single file named \\texttt{index.common.js} and generates an\n \\texttt{index.css} file for any internal CSS included with\n \\texttt{\\textless{}style\\textgreater{}} tags in \\texttt{.vue} files:\n\n\\begin{verbatim}\n\"scripts\": {\n \"build\": \"babel --source-maps -d build src && vue-cli-service build --dest \n build/ --formats commonjs --target lib --name index ./src/index.js && npm \n run copy-assets && liferay-npm-bundler\",\n \"copy-assets\": \"lnbs-copy-assets\",\n \"deploy\": \"npm run build && lnbs-deploy\",\n \"start\": \"lnbs-start\"\n}\n\\end{verbatim}\n\\item\n Update the \\texttt{main} entry of the \\texttt{package.json} to match\n the new \\href{http://www.commonjs.org/}{CommonJS} file name specified\n in the previous step:\n\n\\begin{verbatim}\n\"main\": \"index.common\"\n\\end{verbatim}\n\\item\n Finally, deploy your portlet bundle:\n\n\\begin{verbatim}\nnpm run deploy\n\\end{verbatim}\n\\end{enumerate}\n\nCongratulations! Your Vue app is deployed and now available as a widget\nthat you can add to site pages.\n\nThe liferay-npm-bundler confirms the deployment:\n\n\\begin{verbatim}\nReport written to liferay-npm-bundler-report.html\nDeployed my-vue-guestbook-1.0.0.jar to c:\\git\\bundles\n\\end{verbatim}\n\nThe Liferay DXP console confirms your bundle started:\n\n\\begin{verbatim}\n2019-03-22 20:17:53.181 INFO \n[fileinstall-C:/git/bundles/osgi/modules][BundleStartStopLogger:39] \nSTARTED my-vue-guestbook_1.0.0 [1695]\n\\end{verbatim}\n\nFind your widget by selecting the \\emph{Add} icon\n(\\includegraphics{./images/icon-add-app.png}) and navigating to\n\\emph{Widgets} and the category you specified to the Liferay Bundle\nGenerator (\\emph{Sample} is the default category).\n\n\\section{Related Topics}\\label{related-topics-2}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/web-services}{Web\nServices}\n\n\\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}\n\n\\href{/docs/7-2/frameworks/-/knowledge_base/f/localization}{Localization}\n\n\\chapter{Liferay MVC Portlet}\\label{liferay-mvc-portlet}\n\nIf you're an experienced developer, this is not the first time you've\nheard about Model View Controller. If there are so many implementations\nof MVC frameworks in Java, why did Liferay create yet another one? Stay\nwith us and you'll see that Liferay MVC Portlet provides these benefits:\n\n\\begin{itemize}\n\\tightlist\n\\item\n It's lightweight, as opposed to many other Java MVC frameworks.\n\\item\n There are no special configuration files that need to be kept in sync\n with your code.\n\\item\n It's a simple extension of\n \\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/GenericPortlet.html}{\\texttt{GenericPortlet}}.\n\\item\n You avoid writing a bunch of boilerplate code, since Liferay's MVC\n Portlet framework only looks for some pre-defined parameters when the\n \\texttt{init()} method is called.\n\\item\n The controller can be broken down into MVC command classes, each of\n which handles the controller code for a particular\n \\href{/docs/7-2/frameworks/-/knowledge_base/f/portlets}{portlet phase}\n (render, action, and resource serving phases).\n\\item\n An MVC command class can serve multiple portlets.\n\\item\n Liferay's portlets use it. That means there are plenty of robust\n implementations to reference when you need to design or troubleshoot\n your Liferay applications.\n\\end{itemize}\n\nThe Liferay MVC Portlet framework is light and easy to use. The default\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-the-mvc-portlet-template}{\\texttt{MVCPortlet}\nproject} template generates a fully configured and working project.\n\nHere, you'll learn how MVCPortlet works by covering these topics:\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\hyperref[mvc-layers-and-modularity]{MVC layers and modularity}\n\\item\n \\hyperref[liferay-mvc-command-classes]{Liferay MVC command classes}\n\\item\n \\hyperref[liferay-mvc-portlet-component]{Liferay MVC portlet\n component}\n\\item\n \\hyperref[a-simpler-mvc-portlet]{Simple MVC portlets}\n\\end{itemize}\n\nReview how each layer of the Liferay MVC portlet framework helps you\nseparate the concerns of your application.\n\n\\section{MVC Layers and Modularity}\\label{mvc-layers-and-modularity}\n\nIn MVC, there are three layers, and you can probably guess what they\nare.\n\n\\textbf{Model:} The model layer holds the application data and logic for\nmanipulating it.\n\n\\textbf{View:} The view layer contains logic for displaying data.\n\n\\textbf{Controller:} The middle man in the MVC pattern, the Controller\ncontains logic for passing the data back and forth between the view and\nthe model layers.\n\nLiferay DXP's applications are divided into multiple discrete modules.\nWith \\href{/docs/7-2/appdev/-/knowledge_base/a/service-builder}{Service\nBuilder}, the model layer is generated into a \\texttt{service} and an\n\\texttt{api} module. That accounts for the model in the MVC pattern. The\nview and the controller layers share a module, the \\texttt{web} module.\n\nGenerating the skeleton for a\n\\href{/docs/7-2/reference/-/knowledge_base/r/using-the-service-builder-template}{multi-module\nService Builder-driven MVC application} saves you lots of time and gets\nyou started on the more important (and interesting, if we're being\nhonest) development work.\n\n\\section{Liferay MVC Command Classes}\\label{liferay-mvc-command-classes}\n\nIn a larger application, your \\texttt{-Portlet} class can become\nmonstrous and unwieldy if it holds all of the controller logic. Liferay\nprovides MVC command classes to break up your controller functionality.\n\n\\begin{itemize}\n\\tightlist\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCActionCommand.html}{\\texttt{MVCActionCommand}}:}\n Use \\texttt{-ActionCommand} classes to hold each of your portlet\n actions, which are invoked by action URLs.\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCRenderCommand.html}{\\texttt{MVCRenderCommand}}:}\n Use \\texttt{-RenderCommand} classes to hold a \\texttt{render} method\n that dispatches to the appropriate JSP, by responding to render URLs.\n\\item\n \\textbf{\\href{https://docs.liferay.com/dxp/portal/7.2-latest/javadocs/portal-kernel/com/liferay/portal/kernel/portlet/bridges/mvc/MVCResourceCommand.html}{\\texttt{MVCResourceCommand}}:}\n Use \\texttt{-ResourceCommand} classes to serve resources based on\n resource URLs.\n\\end{itemize}\n\nThere must be some confusing configuration files to keep everything\nwired together and working properly, right? Wrong: it's all easily\nmanaged in the \\texttt{-Portlet} class's\n\\href{https://docs.osgi.org/javadoc/osgi.cmpn/7.0.0/org/osgi/service/component/annotations/Component.html}{\\texttt{@Component}}\nannotation.\n\n\\section{Liferay MVC Portlet\nComponent}\\label{liferay-mvc-portlet-component}\n\nWhether or not you plan to split up the controller into MVC command\nclasses, the portlet \\texttt{@Component} annotation configures the\nportlet. Here's a simple portlet component as an example:\n\n\\begin{verbatim}\n@Component(\n property = {\n \"com.liferay.portlet.css-class-wrapper=portlet-hello-world\",\n \"com.liferay.portlet.display-category=category.sample\",\n \"com.liferay.portlet.icon=/icons/hello_world.png\",\n \"com.liferay.portlet.preferences-owned-by-group=true\",\n \"com.liferay.portlet.private-request-attributes=false\",\n \"com.liferay.portlet.private-session-attributes=false\",\n \"com.liferay.portlet.remoteable=true\",\n \"com.liferay.portlet.render-weight=50\",\n \"com.liferay.portlet.use-default-template=true\",\n \"javax.portlet.display-name=Hello World\",\n \"javax.portlet.expiration-cache=0\",\n \"javax.portlet.init-param.always-display-default-configuration-icons=true\",\n \"javax.portlet.name=\" + HelloWorldPortletKeys.HELLO_WORLD,\n \"javax.portlet.resource-bundle=content.Language\",\n \"javax.portlet.security-role-ref=guest,power-user,user\",\n \"javax.portlet.supports.mime-type=text/html\"\n },\n service = Portlet.class\n)\npublic class HelloWorldPortlet extends MVCPortlet {\n}\n\\end{verbatim}\n\nThe \\texttt{javax.portlet.name} property is required. When using MVC\ncommands, the \\texttt{javax.portlet.name} property value links\nparticular portlet URL/command combinations to the correct portlet.\n\n\\noindent\\hrulefill\n\n\\textbf{Important:} Make your portlet name unique, considering how\n\\href{/docs/7-2/reference/-/knowledge_base/r/portlet-descriptor-to-osgi-service-property-map\\#ten}{Liferay\nDXP uses the name to create the portlet's ID}.\n\n\\noindent\\hrulefill\n\nThere can be some confusion over exactly what kind of\n\\texttt{Portlet.class} implementation you're publishing with a\ncomponent. The service registry expects this to be the\n\\href{https://docs.liferay.com/portlet-api/3.0/javadocs/javax/portlet/Portlet.html}{\\texttt{javax.portlet.Portlet}}\ninterface. Import that, and not, for example,\n\\texttt{com.liferay.portal.kernel.model.Portlet}.\n\n\\noindent\\hrulefill\n\n\\textbf{Note:} The DTD\n\\href{https://docs.liferay.com/dxp/portal/7.2-latest/definitions/liferay-portlet-app_7_2_0.dtd.html}{liferay-portlet-app\\_7\\_2\\_0.dtd}\ndefines all the Liferay-specific attributes you can specify as\nproperties in your portlet components.\n\nConsider the \\texttt{\\textless{}css-class-wrapper\\textgreater{}} element\nfrom the above link as an example. To specify that property in your\ncomponent, use this syntax in your property list:\n\n\\texttt{\"com.liferay.portlet.css-class-wrapper=portlet-hello-world\",}\n\nThe properties namespaced with \\texttt{javax.portlet.} are elements of\nthe\n\\href{https://docs.liferay.com/portlet-api/3.0/portlet-app_3_0.xsd}{\\texttt{portlet.xml}\ndescriptor}.\n\n\\noindent\\hrulefill\n\n\\section{A Simpler MVC Portlet}\\label{a-simpler-mvc-portlet}\n\nIn simpler applications, you don't use MVC commands. Your portlet render\nURLs specify JSP paths in \\texttt{mvcPath} parameters.\n\n\\begin{verbatim}\n