svnno****@sourc*****
svnno****@sourc*****
2007年 5月 25日 (金) 18:26:28 JST
Revision: 158
http://svn.sourceforge.jp/cgi-bin/viewcvs.cgi?root=pal&view=rev&rev=158
Author: shinsuke
Date: 2007-05-25 18:26:27 +0900 (Fri, 25 May 2007)
Log Message:
-----------
added portlet development for portlet api.
Modified Paths:
--------------
pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/navigation.xml
Added Paths:
-----------
pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/guide-api-based-portlet.xml
-------------- next part --------------
Added: pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/guide-api-based-portlet.xml
===================================================================
--- pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/guide-api-based-portlet.xml 2007-05-25 03:34:31 UTC (rev 157)
+++ pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/guide-api-based-portlet.xml 2007-05-25 09:26:27 UTC (rev 158)
@@ -0,0 +1,411 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+<document>
+ <properties>
+ <title>PALポータル ポートレット開発者ガイド</title>
+ <subtitle>ポートレット API を用いたポートレット開発方法</subtitle>
+ <authors>
+ <person name="菅谷信介" email="shins****@yahoo*****"/>
+ </authors>
+ </properties>
+ <body>
+ <section name="ポートレット作成の準備">
+ <p>
+ここでは、JSR 168 のポートレット API を利用して、JSR 168 に準拠したポートレットの作成を説明します。
+HelloWorld的なポートレットを作成して、作成したものを PALポータルに配備します。
+</p>
+ <p>
+今回、作成するポートレットは、入力フォームを持ち、値を入力すると、その入力された値を表示するポートレットです。
+開発するにあたり、javac や ant などで説明を進めると、依存関係の解決などを行わなければならないので、簡単にするために、maven 2 でビルドするプロジェクトを作成します。
+</p>
+ <p>
+まずは、ディレクトリを作成します。
+<source><![CDATA[
+$ cd
+$ mkdir -p Projects/helloworld
+$ cd Projects/helloworld/
+]]></source>
+この helloworld ポートレットプロジェクトでは、次のファイルを作成します。
+<source><![CDATA[
+ pom.xml
+ src/main/webapp/WEB-INF/portlet.xml
+ src/main/webapp/WEB-INF/web.xml
+ src/main/webapp/WEB-INF/view/helloworld.jsp
+ src/main/java/com/marevol/portlet/helloworld/resources/HelloWorldResources_ja.properties
+ src/main/java/com/marevol/portlet/helloworld/resources/HelloWorldResources.properties
+ src/main/java/com/marevol/portlet/helloworld/HelloWorldPortlet.java
+]]></source>
+pom.xml は、Maven 2 のプロジェクトファイルです。
+そして、それ以外のファイルが、ポートレットを構築・実行する上で必要になるファイルになります。
+</p>
+ </section>
+ <section name="Maven 2 用ファイル (pom.xml)">
+ <p>
+それでは、順に構成ファイルについてみていきましょう。
+</p>
+ <p>
+まずは、プロジェクトを Maven 2 で利用できるようにするための pom.xml です。
+このファイルについては、通常の Maven 2 プロジェクトと同様に作成しています。
+ですので、ポートレット用に特殊な設定などはしていません。
+</p>
+ <p>
+ポートレット用にビルドするために、依存関係に portlet-api を指定しておけば、ポートレットを作成することができます。
+今回の helloworld ポートレットでは、ビューに JSP を利用して、JSTL を利用しているので、それに必要な依存関係を追加します。
+もし、独自にポートレットを作成する場合には、必要なライブラリがあれば、追加してください。
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>jp.sf.pal.sample</groupId>
+ <artifactId>helloworld</artifactId>
+ <version>1.0</version>
+ <packaging>war</packaging>
+ <name>Helloworld Portlet</name>
+ <build>
+ <finalName>helloworld</finalName>
+ </build>
+ <dependencies>
+ <dependency>
+ <groupId>portlet-api</groupId>
+ <artifactId>portlet-api</artifactId>
+ <version>1.0</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>jstl</groupId>
+ <artifactId>jstl</artifactId>
+ <version>1.1.2</version>
+ </dependency>
+ <dependency>
+ <groupId>taglibs</groupId>
+ <artifactId>standard</artifactId>
+ <version>1.1.2</version>
+ </dependency>
+ <dependency>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ <version>1.0.4</version>
+ </dependency>
+ </dependencies>
+</project>
+]]></source>
+</p>
+ </section>
+ <section name="ポートレットの構成ファイル">
+ <p>
+この節で説明するものが、ポートレットを作成する上で必要になってくるファイルです。
+基本的には、Servlet Specification 2.3, SRV.9 で定義されている Web アプリケーションの構成と同じで、サーブレット、JSP、HTMLページ、クラスなどのファイルを含み、それらに加えて、ポートレットのクラスファイルとポートレット配備記述子 (portlet.xml) を含みます。
+ですので、通常通りに、Java で Web アプリケーションを作成し、portlet.xml を追加する点だけが異なります。
+ポートレットアプリケーションについては、JSR 168 の PLT.19 で定義されています。
+</p>
+ <p>
+まず、portlet.xml について、説明します。
+portlet.xml は、ポートレットのリソースについて定義しています。
+ですので、ポートレットの構成情報などがいろいろと記述されています。
+portlet.xml のスキーマなどの詳細の情報は、JSR 168 の PLT.21.5 や PLT.21.6 を参照してください。
+</p>
+ <p>
+portlet.xml では、ルートノードに portlet-app 要素があり、その下に portlet 要素を複数定義できます。
+１つのポートレットの定義が１つの portlet 要素に対応しているので、portlet.xml に portlet 要素を複数記述することで、複数のポートレットを定義することもできます。
+</p>
+ <p>
+次に、portlet 要素の下にある要素について説明します。
+portlet-name 要素は、ポートレットの名前になります。
+これは、このポートレットアプリケーション内でユニークな値である必要があります。
+display-name 要素と、次の description 要素は、ポートレットに関する簡単な名前と説明になります。
+これらの値は、たとえば、ポータルサーバーのポートレット管理ツールなどで表示される値になります。
+そのツール上で日本語の名前を出したいような場合には、xml:lang 属性を追加して、記述します。
+たとえば、日本語であれば、xml:lang="ja" として、属性を追加します。
+portlet.xml では、display-name と description については、xml:lang 属性を用いて、複数定義することができます。
+</p>
+ <p>
+portlet-class 要素は、実行するポートレットのクラス指定します。
+</p>
+ <p>
+expiration-cache 要素は、キャッシュの有効期限を秒単位で指定します。
+-1 は無期限を意味します。
+</p>
+ <p>
+supports 要素では、サポートする MIME タイプやポートレットモードを指定しています。
+</p>
+ <p>
+supported-locale 要素は、サポートしているロケールを記述します。
+</p>
+ <p>
+resource-bundle 要素では、ポートレットで利用するリソースバンドルを指定します。
+指定したリソースバンドルは、PortletConfig#getResourceBundle() で取得することができます。
+</p>
+ <p>
+portlet-info 要素では、ポートレットで表示されるタイトルなどを指定しています。
+タイトルを国際化するためには、resource-bundle
+要素で指定したリソースバンドル内に記述する必要があります。
+</p>
+ <p>
+src/main/webapp/WEB-INF/portlet.xml は以下のとおりです。
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<portlet-app id="helloworld" version="1.0">
+ <portlet id="HelloWorld">
+ <portlet-name>HelloWorld</portlet-name>
+ <display-name>Hello World</display-name>
+ <display-name xml:lang="ja">ハローワールド</display-name>
+ <description>HelloWorld is a portlet for testing</description>
+ <description xml:lang="ja">HelloWorld はテスト用ポートレットです</description>
+ <portlet-class>com.marevol.portlet.helloworld.HelloWorldPortlet</portlet-class>
+ <expiration-cache>-1</expiration-cache>
+ <supports>
+ <mime-type>text/html</mime-type>
+ <portlet-mode>VIEW</portlet-mode>
+ </supports>
+ <supported-locale>en</supported-locale>
+ <supported-locale>ja</supported-locale>
+ <resource-bundle>com.marevol.portlet.helloworld.resources.HelloWorldResources</resource-bundle>
+ <portlet-info>
+ <title>Hello World</title>
+ <short-title>This is a portlet for testing</short-title>
+ <keywords>Hello,Test</keywords>
+ </portlet-info>
+ </portlet>
+</portlet-app>
+]]></source>
+</p>
+ <p>
+web.xml は、通常の Web アプリケーションと同様に、Web アプリケーションのリソースなどを指定しています。
+今回は、特に指定することもないので、display-name と description 要素にこのポートレットについてを記述するだけになっています。
+src/main/webapp/WEB-INF/web.xml は以下のようになります。
+<source><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
+<web-app>
+ <display-name>HelloWorld Portlet</display-name>
+ <description>HelloWorld Portlet</description>
+</web-app>
+]]></source>
+</p>
+ <p>
+HelloWorldPortlet は、portlet.xml で portlet-class 要素で指定したポートレットのクラスです。
+ポートレットにアクセスすると、このクラスが呼ばれ、必要な処理を実行します。
+ポートレットは、 javax.portlet.Portlet インターフェース実装したクラスになります。
+今回は、そのインターフェースを実装した javax.portlet.GenericPortlet を継承して作成します。
+</p>
+ <p>
+この HelloWorldPortlet は、init, doView, processAction３つのメソッドを持っています。
+まず、init はその名の通り、ポートレットの初期化を行います。
+たとえば、portlet.xml で値を与えている場合などには、ここで取得するのが適切です。
+今回は、特に何もすることがないため、スーパークラスに渡しているだけにしています。
+</p>
+ <p>
+次に doView と processAction ですが、Portlet インターフェースには、processAction と render メソッドが定義されています。
+つまり、ポートレットの処理は、アクションの処理と表示の処理が完全に分かれていて、processAction でアクションの処理を行い、表示などは、render メソッドで行われます。
+GenericPortlet の render メソッドでは、ポートレットのタイトルを設定して、doDispatchメソッドに渡されています。
+そして、GenericPortlet の doDispatch メソッドでポートレットのモードによって、処理を振り分けています。
+たとえば、表示モードでは doView、ポートレットの右上にある編集ボタンを押したときなどになる編集モードの描画処理を行う場合は doEdit などです。
+今回のポートレットでは、表示モードしか扱わないため、doView だけを追加しておきます。
+</p>
+ <p>
+doView メソッドでは、RenderRequest と RenderResponse を利用し、まず、コンテンツタイプを設定してから(コンテンツタイプを指定しないと Exception が投げられます)、与えられた YOUR_NAME_KEY キーの値を取得して、helloworld.jsp に渡す処理をしています。
+</p>
+ <p>
+processAction の引数は、ActionRequest と ActionResponse になります。
+今回、このメソッドでは、helloworld.jsp で送信された値を ActionResponse に渡しています。
+</p>
+ <p>
+ここで、このRender〜やAction〜について説明します。これらは、名前の通り、表示のためのRender〜であり、アクションを処理するためのAction〜です。
+processAction で jsp などからの様々な入力値を処理して、ActionResponse の setRenderParameter で RenderRequest に渡します。
+つまり、jsp からの入力は、doView の RenderRequest で取得できないということになります。
+ですので、doView などでは、本当に表示だけの処理に専念することになります。
+この意味を考えるためには、次のような状況を考えてください。
+ポートレットは、１つのページに複数のポートレットを表示することになります。
+各ポートレットは独立していて、ほとんどの場合、複数の中の 1 つのポートレットだけに入力データなどを送信して処理することになります。
+その対象のポートレットでは、processAction が呼ばれ、doView が呼ばれることになります。
+一方、それ以外のポートレットでは、ページが更新されますが、表示内容はその更新に関係なく、同じ内容を表示する必要があります(たとえば、他のページで一覧を表示し、他のポートレットで処理したらメニューに戻るなどの動作は良くありません)。
+ですので、ページが更新されたとしても、アクションの処理の対象でなければ、表示の内容を維持する必要があるので、アクションに関係なく、Render〜で独立したパラメータを持つことになります。
+こういうことから、processAction の Action〜からデータを取得して処理し、表示用のパラメータを設定して、setRenderParameterなどで、Render〜に渡すという処理の流れになります。
+</p>
+ <p>
+src/main/java/com/marevol/portlet/helloworld/HelloWorldPortlet.java は以下のとおりです。
+<source><![CDATA[
+package com.marevol.portlet.helloworld;
+
+import java.io.IOException;
+
+import javax.portlet.ActionRequest;
+import javax.portlet.ActionResponse;
+import javax.portlet.GenericPortlet;
+import javax.portlet.PortletConfig;
+import javax.portlet.PortletContext;
+import javax.portlet.PortletException;
+import javax.portlet.PortletRequestDispatcher;
+import javax.portlet.RenderRequest;
+import javax.portlet.RenderResponse;
+
+public class HelloWorldPortlet extends GenericPortlet
+{
+ public static final String YOUR_NAME_KEY = "yourName";
+
+ public void init(PortletConfig config) throws PortletException
+ {
+ super.init(config);
+ }
+
+ protected void doView(RenderRequest request, RenderResponse response)
+ throws PortletException, IOException
+ {
+ response.setContentType("text/html");
+
+ PortletContext context = getPortletContext();
+
+ String yourName = request.getParameter(YOUR_NAME_KEY);
+ if (yourName == null)
+ {
+ yourName = "";
+ }
+ request.setAttribute(YOUR_NAME_KEY, yourName);
+
+ PortletRequestDispatcher rd =
+ context.getRequestDispatcher("/WEB-INF/view/helloworld.jsp");
+ rd.include(request, response);
+ }
+
+ public void processAction(ActionRequest request, ActionResponse response)
+ throws PortletException, IOException
+ {
+ String yourName = request.getParameter(YOUR_NAME_KEY);
+
+ if (yourName != null)
+ {
+ response.setRenderParameter(YOUR_NAME_KEY, yourName);
+ }
+ }
+}
+]]></source>
+</p>
+ <p>
+helloworld.jsp は、今回のポートレットのビューの部分にあたります。
+この JSP ファイルは、HelloWorldPortlet クラスから呼ばれて、実行されます。
+ここでは、入力フォームを表示して、送信ボタンをクリックすると、そのメッセージが表示される処理を実行します。
+</p>
+ <p>
+この helloworld.jsp では、２つのタグライブラリを読み込んでいますが、ポートレットで利用されるのが http://java.sun.com/portlet のタグライブラリです。
+taglib uri=... でこのタブライブラリを宣言し、<portlet:defineObjects/> を記述すると、それ以降で、renderRequest などのパラメータを利用することができるようになります。
+また、このタグライブラリには、<portlet:actionURL /> などの URL を作成するタグもあるので、ビューで JSP を利用するときには、通常、このタブライブラリは使うことになります。
+このタグライブラリに関する詳細は、PLT.22 を参照してください。
+</p>
+ <p>
+fmt のタグライブラリは、一般的な JSTL のものですので、そちらの方のドキュメントなどを参照してください。
+今回は、メッセージを国際化するためだけに利用しています。
+ポートレット用に特別に何かをする必要はありません。
+</p>
+ <p>
+src/main/webapp/WEB-INF/view/helloworld.jsp は以下のとおりです。
+<source><![CDATA[
+<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>
+<%@ taglib uri="http://java.sun.com/jstl/fmt" prefix="fmt" %>
+<fmt:setBundle basename="com.marevol.portlet.helloworld.resources.HelloWorldResources" />
+<portlet:defineObjects/>
+
+<form action="<portlet:actionURL />" method="POST">
+<table border="0">
+ <tr>
+ <td align="center"><fmt:message key="helloworld.lable.Hello"/></td>
+ <td align="center"><%= renderRequest.getAttribute("yourName") %></td>
+ </tr>
+ <tr>
+ <td align="right"><fmt:message key="helloworld.lable.YourName"/></td>
+ <td align="left"><input type="text" name="yourName"/></td>
+ </tr>
+ <tr>
+ <td align="center" colspan="2">
+ <input type="submit" value="<fmt:message key="helloworld.lable.Submit"/>"/>
+ </td>
+ </tr>
+</table>
+</form>
+]]></source>
+ポートレットでは、ポータル上の 1 つのページで、その中の一部のフラグメントとして表示されるため、htmlタグ、headタグや body タグなどは記述する必要はありません。
+</p>
+ <p>
+最後に、HelloWorldResources プロパティファイルについてです。
+今回は、デフォルトのもの (_ja がないもの) と、..._ja.properties の日本語用のものを作成しています。
+このリソースは、portlet.xml と helloworld.jsp で指定して、利用されています。
+</p>
+ <p>
+デフォルトのものと日本語用を比べると、日本語用には、javax.portlet で始まるプロパティが追加されているのがわかります。
+これらは、portlet.xml の portlet-info 要素以下にあったものにそれぞれが対応しています。
+たとえば、ポートレットの上部に表示されるタイトルで日本語のタイトルを表示したいといった場合などは、javax.portlet.title プロパティを portlet.xml の resouce-bundle 要素で指定したプロパティファイルに追加しておけば、このタイトルが表示されます。
+short-title と keywordsも同様に、日本語が表示したい場合には、プロパティファイルに加えておきます(short-title はその名の通り、本来は、短いタイトルです。これはたとえば、携帯電話などで通常より短いタイトルが必要な場合に利用されることになります)。
+</p>
+ <p>
+src/main/java/com/marevol/portlet/helloworld/resources/HelloWorldResources_ja.properties は以下のとおりです。
+<source><![CDATA[
+# portlet info
+javax.portlet.title=\u30CF\u30ED\u30FC\u30EF\u30FC\u30EB\u30C9
+javax.portlet.short-title=\u3053\u308C\u306F\u3001\u300C\u3053\u3093\u306B\
+\u3061\u306F\u300D\u3068\u8A00\u3046\u30DD\u30FC\u30C8\u30EC\u30C3\u30C8\u3067\
+\u3059\u3002
+javax.portlet.keywords=\u30C6\u30B9\u30C8,\u30CF\u30ED\u30FC
+
+# helloworld.jsp
+helloworld.lable.Hello=\u3053\u3093\u306B\u3061\u306F\u3001
+helloworld.lable.YourName=\u540D\u524D:
+helloworld.lable.Submit=\u9001\u4FE1
+]]></source>
+
+src/main/java/com/marevol/portlet/helloworld/resources/HelloWorldResources.properties は以下のとおりです。
+<source><![CDATA[
+# helloworld.jsp
+helloworld.lable.Hello=Hello!
+helloworld.lable.YourName=Your Name:
+helloworld.lable.Submit=Submit
+]]></source>
+</p>
+ </section>
+ <section name="ポートレットのビルド">
+ <p>
+必要なものが一通り用意できたので、次にビルドして、ポートレットアプリケーションの war ファイルを作成します。
+ビルド方法は、非常に簡単です。
+ここでは、Maven 2 を実行できる環境が用意済みであることを想定しています。
+Maven 2 のインストール方法については、<a href="http://maven.apache.org/">http://maven.apache.org/</a> を参照してください。
+<source><![CDATA[
+$ ls
+pom.xml src
+$ mvn install
+[INFO] Scanning for projects...
+[INFO] ----------------------------------------------------------------------------
+[INFO] Building Helloworld Portlet
+[INFO] task-segment: [install]
+[INFO] ----------------------------------------------------------------------------
+.
+.
+.
+]]></source>
+通常の Maven 2 のビルドと同様、mvn install を実行します。
+このことからも、基本的には、普通の Web アプリケーションと同じであることがわかると思います。
+ビルドに成功していると、target ディレクトリの下に helloworld.war が作成されます。
+<source><![CDATA[
+$ ls target/helloworld.war
+target/helloworld.war
+]]></source>
+</p>
+ <p>
+これで、JSR 168 に準拠しているポートレットを作成できたことになります。
+これを、JSR 168 に準拠しているポータルサーバー上に持っていき、そのポータルサーバーの配備手順に従って、配備すれば、動作させることができます。
+</p>
+ </section>
+ <!-- TODO How to Deploy -->
+ </body>
+</document>
Property changes on: pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/guide-api-based-portlet.xml
___________________________________________________________________
Name: svn:eol-style
+ native
Modified: pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/navigation.xml
===================================================================
--- pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/navigation.xml 2007-05-25 03:34:31 UTC (rev 157)
+++ pal-portal/trunk/docs/ja/portlet-developers-guide/xdocs/navigation.xml 2007-05-25 09:26:27 UTC (rev 158)
@@ -28,6 +28,7 @@
<item name="ポートレット開発概要" href="overview.html"/>
</menu>
<menu name="開発方法について">
+ <item name="ポートレット API を用いたポートレット開発方法" href="guide-api-based-portlet.html"/>
<item name="Teeda を用いたポートレット開発方法" href="guide-teeda-based-portlet.html"/>
</menu>
<!--