Tài liệu Liferay Portal doc

Liferay Portal Liferay Portal by Brian Kim Copyright © 2005 bkim@liferay.com This is a tutorial for Liferay Portal. Liferay Portal is an open source portal that helps organizations collaborate more efficiently by providing a consolidated view of disparate applications via a web browser. Table of Contents 1. Introduction 1.1. Introduction 1.2. Recommended Requirements 2. Installation 2.1. Setting Up Your Development Environment 2.2. Obtaining Liferay Portal’s Source Code 2.3. Installing Your IDE – Eclipse 2.4. Developing with Liferay’s Core Source 2.4.1. Obtaining Orion Application Server 2.4.2. Configuring Eclipse with Orion 2.4.3. Setting Up Orion 2.4.4. Configuring Your Properties 2.4.5. Deploying to Orion 2.5. Creating an Extension Environment 2.5.1. Setting Up Ext 2.5.2. Adding Plugin support 2.5.3. Hooking Up To a Database 2.5.4. Starting Liferay Chapter 1. Introduction 1.1. Introduction In this document, my goal is to help you setup your environment so that you can begin developing your own custom portlets from scratch. This document assumes that you have some working knowledge of Servlets, JSPs, and web development in general. Although I’ll be assuming that you are running on a Windows OS, I’ll try to keep my explanations general enough so that they can be used for any operating system. This tutorial will cover the setup of a development environment, from using an IDE such as Eclipse to setting up your database connections. While my focus will be on using Liferay Professional – the Tomcat Spring framework version – I will briefly touch on the Enterprise version as well. 1.2. Recommended Requirements Although you could probably get away with lesser requirements, when developing and customizing Liferay, we recommend the following hardware requirements:  1 gig of RAM  2.0 ghz Pentium processor Chapter 2. Installation 2.1. Setting Up Your Development Environment As with any enterprise Java application, setting up Liferay can be a daunting task. Liferay leverages several frameworks. Fortunately for you, most of these frameworks come bundled with Liferay already. What you do need to install, however, are some of the basic tools that Liferay uses. Let’s first ensure that you’re using the right Java JDK. You should be using the latest release of J2SE 1.4.2, which may already be installed on your machine. If not, download the latest version from http://java.sun.com. Since we’ll be installing several Java technologies, I typically install/unzip my files under a common folder such as D:\Java. Obviously you can choose to install them into any directory of your preference, but from here on out I will reference the installation folder as {Java}. Although you can use Sun’s default Java compiler, we recommend using IBM’s Jikes compiler – it is generally more descriptive with compile errors. Make sure you download version 1.21, since version 1.22 is oriented towards J2SE 1.5, which Liferay Portal does not use due to backwards compatibility reasons. Finally, you’ll need to download the latest version of Ant, a Java-based build tool, from http://ant.apache.org. Once you’ve downloaded and installed/unzipped all the files described above, you’ll need to set your environmental variables to point to them. In Windows, open your Control Panel, choose System properties, click the Advanced tab, and click Environmental Variables. Figure 2.1. Environmental Variables Choose New, and then add the following three variables: JAVA_HOME, JIKES_HOME, and ANT_HOME. Each respective variable needs to point to the directory in which your tools reside. If you look at Figure 2.1, you can see that my JAVA_HOME variable points to {Java}\j2sdk1.4.2_05. It is recommended that you remove the CLASSPATH variable to prevent conflicts when compiling. It is generally good practice to develop without the use of a classpath variable, since doing so creates a dependency on the developer’s machine. Once you have your three System variables setup, you need to edit the Path variable by adding the following: %ANT_HOME%\bin;%JAVA_HOME%\bin;%JIKES_HOME%\bin 2.2. Obtaining Liferay Portal’s Source Code In order to keep up-to-date with Liferay’s upgrades, you will want to create an extension environment. To start, go to http://www.liferay.com/web/guest/downloads/portal_source and download the latest stable Liferay Portal Enterprise source. I would recommend unzipping the bundle into a directory like D:\cvsroot\liferay (I use CVS as a code repository), which I will refer to as {Liferay}. Then download the latest stable Liferay Portal bundle, in particular Liferay Portal Professional (Bundled with Tomcat) for this tutorial. I’ll explain what to do with the Tomcat bundle later on in this chapter. 2.3. Installing Your IDE – Eclipse Despite the fact that you could modify and deploy Liferay Portal with as simple as an editor as Textpad, a good IDE can help speed up the process. I’ll show you how Eclipse plugins can make life easier for editing, deploying, and running Liferay Portal. Download the newest version of the Eclipse from http://www.eclipse.org/downloads/index.php. Install Eclipse into {Java}\eclipse and then run it. Select File from the menu bar and then choose Switch Workspace…Within the input box, type the path of {Liferay}, as shown in Figure 2.2. Figure 2.2. Creating a new Workspace To setup your project within your workspace, select File from the menu bar, New, then Project. Select Java Project from the dialogue box and click Next. In the New Java Project window, enter portal as the Project Name, and then click Finish. Figure 2.3. Adding a new java project If you’ve setup the Workspace correctly, you should be able to see the portal project within the Navigator pane of the Resource perspective. If you right click on the root directory of the project, select Properties, choose Java Build Path from the left navigation, and the Libraries tab from the right, your portal project should have all the necessary jars loaded already. These jars are loaded via the .classpath file that exists in {Liferay}\portal. Adding plugin support for Eclipse is even easier. Since Eclipse comes bundled with Ant, setting up Ant is as easy as selecting Window from the menu bar, choosing Show View and then Ant. You should see the Ant tab displayed within your current perspective. Adding Liferay’s build files is just as easy. Simply select the Ant tab in your perspective and then click the Ant icon with the + symbol. Note that each directory within Liferay contains its own build.xml file, which Ant reads. When clicking the Ant icon, select the build.xml file within the portal directory. Your Ant setup should look like Figure 2.3. Figure 2.3. Adding the Ant plugin 2.4. Developing with Liferay’s Core Source The following section outlines how to develop and debug Liferay’s core source using Orion’s application server. It is important to note that working off the core source is not recommended. If you are trying to extend the functionality of Liferay Portal, it is suggested that you create an Extension Environment, as outlined in the next section (2.5). Development of the core portal should only be done for bug fixes or enhancements that potentially would make it into the next build. Typical developers will not need to read this section. 2.4.1. Obtaining Orion Application Server Although Liferay’s core source could be deployed to other application servers, the build files were written specifically with Orion in mind. An evaluation version of Orion is available for download at http://www.orionserver.com. Extract the files into your installation folder (i.e. {Java}\orion-2.0.6), which I will reference as {orion}. To test out your server, from your Orion home directory, run the command: “java –jar orion.jar”. 2.4.2. Configuring Eclipse with Orion Running Orion from your Eclipse IDE takes a little more time to setup. First change your perspective to Debug. Underneath the menu bar, there is a bug-like icon. Click the small drop down arrow to the right of it and then select “Debug…”, at which point a dialogue box should appear. Figure x.1. Debug If you have any existing configurations under the Java Application group that are no longer applicable, you can go ahead and delete them. Go ahead and click the New button, and then make the following changes: Main Tab 1. change the Name of the configuration to “orion” 2. set the Main class to be “com.evermind.server.ApplicationServer” Arguments Tab 1. Program arguments: -config {orion}/config/server.xml -userThreads (note that you need to change the directory path) 2. VM arguments: -Xmx256m -Dfile.encoding=UTF8 -Duser.timezone=GMT Classpath Tab 1. under the User Entries group, remove the “portal (default classpath)” entry 2. click Add External JARs, and then browse to your orion.jar to add it Note: make sure that within your JRE Tab, your Project JRE points to a SDK as opposed to just a JRE (i.e. my Project JRE has j2sdk1.4.2_05 next to it in parenthesis. This may require you to add another entry within Java (from the left navigation)  Installed JREs. 2.4.3. Setting Up Orion There are three key files when configuring Orion. The first, {orion}\config\server.xml, let’s you specify which “web-sites” will be accessible when started up. Add a new website by inserting the element: <web-site path="./web-sites/portal.liferay.com-web.xml" /> You can also specify for Orion to use another compiler by adding: <compiler executable="jikes" classpath="{Java}\jre\lib\rt.jar" /> Now that you’ve specified a new website, you need to create a file called portal.liferay.com-web.xml within {orion}\config\web-sites\. You’re file should look something like this: Figure x.2. portal.liferay.com-web.xml Finally, in {orion}\config\application.xml, you need to add both web-module elements and ejb-module elements. All web-app elements declared in your portal.liferay.com- web.xml must be defined in your application.xml: Figure x.3. application.xml Add the references to your EJBs as well by inserting the ejb-module elements. Note that by using the “file:” prefix, you can have Orion look for the direct files. An advantage of using this prefix is that you don’t have to deploy your files to the server. This can be particularly useful for quickly debugging JSPs (simply save your JSP and refresh). Another advantage is that for class files, you can just compile the source files rather than having to compile and deploy. Note: When using the “file:” prefix for the portal-ejb module, you need to ensure that the portal-ejb.jar does not exist within your {orion}\applications\ directory. Finally, you must edit your {orion}\config\data-sources.xml to allow your application to access your database. If you are using MySQL, make sure that the mysql.jar gets deployed to your {orion}\lib\ directory, and configure your data-sources.xml file like so: <data-sources> <data-source class="com.evermind.sql.DriverManagerDataSource" name="Liferay" location="jdbc/LiferayCore" pooled-location="jdbc/LiferayPool" xa-location="jdbc/xa/LiferayXA" ejb-location="jdbc/LiferayEJB" connection-driver="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost/lportal" username="root" password="" inactivity-timeout="30" schema="database-schemas/mysql.xml" /> </data-sources> 2.4.4. Configuring Your Properties Most of Liferay’s configuration is set using a flat file called portal.properties. Similar to your build.properties, you want to override any property settings within portal- ext.properties rather than in portal.properties itself. To configure your portal, create a new file within {Liferay}\portal\util-java\ called portal-ext.properties. Within there, add the following setting: portal.ctx=/portal Again, note that this property setting in portal-ext.properties overrides the property setting in portal.properties. 2.4.5. Deploying to Orion In order for your ant scripts to know where to deploy to, you need to create an extension file named like app.server.{username}.properties. Within the file, add the following line: app.server={orion} Remember that {orion} represents your orion home directory, and for this property, should also use forward slashes (i.e. app.server=D:/Java/orion-2.0.5). Finally, from your Ant View in Eclipse, run the start and deploy targets from your portal directory. If you’ve used the “file:” prefix, don’t forget to delete portal-ejb.jar after deploying! You’re all set! Go ahead and click the bug icon in your Debug perspective, and within your console you should see Orion startup. [...]... directory by going to {Liferay} \ext! Remember the Liferay Portal Professional (Bundled with Tomcat) that I had you     download in section 2.2? Well, here’s what you need to do with it Simply unzip the file into {Liferay} \ext\servers\tomcat Like before, you need to create an app.server.{username}.properties file within {Liferay} \ext that includes only the two lines: lp.ext.dir= {Liferay} /ext app.server.type=tomcat... since there are so many different databases you can use with Liferay Portal The best reference for this would be on Liferay s website, specifically here: http://www .liferay. com/web/guest/documentation/development/databases There it will go in depth into how to setup and connect to your database of choice depending on your server 2.5.4 Starting Liferay Now that you have your environment all configured,... need to select the appropriate Tomcat version If you downloaded Liferay Portal Professional (Bundled with Tomcat), then check Version 5.x You’ll also need to set the following variables: Tomcat home: {Liferay} \ext\servers\tomcat Configuration file: {Liferay} \ext\servers\tomcat\conf\server.xml ¡   Figure 2.4 Setting up Tomcat in Eclipse Since Liferay uses JAAS for authentication, you need to add a JVM... New Java Project (as described earlier for portal) However, this time, use the name ext as the Project name instead 2.5.2 Adding Plugin Support If you are planning on using Liferay Portal Professional, which implements the Spring framework, it would be a good idea to download the Sysdeo Eclipse Tomcat plugin This plugin would allow you to troubleshoot Liferay Portal using Eclipse’s debugger Download... This would allow you to upgrade your portal without any headaches Any time a new stable version of Liferay Portal is released, all you would need to do is drop in the new jars and you’re set to go With that said, your development should only be done within the Extension Environment as well Meaning, all new classes, JSPs, and all changes in general, should be within {Liferay} \ext 2.5.1 Setting Up Ext Setting... prompt from Start Run and seeing what name shows up after Documents and Settings (i.e release.Brian Kim.properties) Within your new properties file, add just one line (with {Liferay} being the actual directory of course): lp.ext.dir= {Liferay} /ext (Note that it’s a forward slash) Next, in the Ant View described in 2.3, you should be able to expand portal s build.xml target list Among the targets, you should... your portal will be running on, check out your {Liferay} \ext\servers\tomcat\conf\server.xml and search for your “Connector port” ¢   setting To test to see if you’ve setup Tomcat correctly, click on the cat-like icon at the upper left of your Eclipse window, and it should start up Remember that you still have a database to setup, however 2.5.3 Hooking Up To a Database Unfortunately, writing documentation... you’ve left the default settings, you should be able to browse to http://localhost and see Liferay Portal load up! Note: because of the nature of Hypersonic, the Sysdeo plugin will not work correctly with our configuration If you plan on using Hypersonic as your database, you will need to actually browse to {Liferay} \ext\servers\tomcat\bin in your command prompt, and manually type in startup to start... node) and click the Add button respective to the Append to JVM Parameters section When the small prompt comes up, add this: -Djava.security.auth.login.config= {Liferay} /ext/servers/tomcat/conf/jaas.config To allocate enough memory for Tomcat when Liferay is running, you need to add the following parameter as well (assuming you have at least 512 megs of RAM): -Xmx512m Note: make sure that within your JVM... changes in general, should be within {Liferay} \ext 2.5.1 Setting Up Ext Setting up your Extension Environment is simple Before anything, you will need to change a property file (.properties) within {Liferay} \portal Note that you should never change the values of the default properties files Instead, follow the instructions commented at the top of each properties file, which states that you should instead . Liferay Portal Liferay Portal by Brian Kim Copyright © 2005 bkim @liferay. com This is a tutorial for Liferay Portal. Liferay Portal is. D:cvsroot liferay (I use CVS as a code repository), which I will refer to as {Liferay} . Then download the latest stable Liferay Portal bundle, in particular Liferay