15 プラグイン

15.1 プラグインの作成とインストール

プラグインの作成

Grailsプラグインの新規作成は、以下のコマンドを実行するだけであり、とても簡単です:

grails create-plugin [PLUGIN NAME]

Make sure the plugin name does not contain more than one capital in a row, or it won't work. Camel case is fine, though.

The only plugins included in a new plugin project are Tomcat and Release. Hibernate is not included by default.

新規プラグインプロジェクトには、TomcatプラグインとReleaseプラグインが含められています。Hibernateプラグインはデフォルトの状態では含められていません。

Grailsプラグインの構成が「通常のGrailsプロジェクト」と同じであることには利点が多くあります。例えば、以下を実行することでテストが実行できます。

grails run-app

Plugin projects don't provide an index.gsp by default since most plugins don't need it. So, if you try to view the plugin running in a browser right after creating it, you will receive a page not found error. You can easily create a grails-app/views/index.gsp for your plugin if you'd like.

プラグインプロジェクトは、index.gspをデフォルトでは提供しません。なぜならほとんどのプラグインでは必要ないからです。なので、プラグイン起動後にブラウザで確認しようとすると「ページが見つかりません」というエラーになるでしょう。もちろん、もしそうしたければプラグインプロジェクト中にgrails-app/views/index.gspを作成しても全く問題ありません。

class ExampleGrailsPlugin {
   def version = "0.1"
   …
}

このようなクラスがプラグインディレクトリのルートに存在しなければなりません。このプラグインクラスは、プラグインのバージョン情報や他のメタデータを定義しています。さらに、プラグイン拡張ポイントへの様々なフックを定義することができます(簡易にカバー)。

さらに、いくつかの特別なプロパティを使って、プラグインの追加情報を提供することもできます。

• title - このプラグインを説明する短い一文。
• version - このプラグインのバージョン。例えば「0.1」「0.2-SNAPSHOT」「1.1.4」などの有効な値。
• grailsVersion - プラグインがサポートするGrailsのバージョンを、バージョン範囲で指定する。例えば「1.2 > *」(これは「1.2以上」であることを示す)
• author - プラグインの開発者名
• authorEmail - プラグイン開発者に連絡するためのe-mailアドレス
• description - 複数行に渡るプラグイン機能のフル説明
• documentation - プラグインのドキュメントへのURL

class QuartzGrailsPlugin {
    def version = "0.1"
    def grailsVersion = "1.1 > *"
    def author = "Sergey Nebolsin"
    def authorEmail = "nebolsin@gmail.com"
    def title = "Quartz Plugin"
    def description = '''\
The Quartz plugin allows your Grails application to schedule jobs\
to be executed using a specified interval or cron expression. The\
underlying system uses the Quartz Enterprise Job Scheduler configured\
via Spring, but is made simpler by the coding by convention paradigm.\
'''
    def documentation = "http://grails.org/plugin/quartz"
   …
}

Installing Local Plugins

To make your plugin available for use in a Grails application run the maven-install command:

grails maven-install

This will install the plugin into your local Maven cache. Then to use the plugin within an application declare a dependency on the plugin in your grails-app/conf/BuildConfig.groovy file:

compile 

アーテファクト除外についての留意事項

前述のように、create-pluginコマンドはプラグインプロジェクトとして一連のファイルを作成し、Grailsアプリケーションとして実行することもできますが、パッケージ化したときにこれら全てのファイルが含められるわけではありません。以下は、生成されるけれども、package-pluginコマンドで生成されるzipファイルには含まれないアーテファクトのリストです。

• grails-app/conf/BootStrap.groovy
• grails-app/conf/BuildConfig.groovy (dependencies.groovyの生成には使用される)
• grails-app/conf/Config.groovy
• grails-app/conf/DataSource.groovy (これと他の任意の*DataSource.groovy)
• grails-app/conf/UrlMappings.groovy
• grails-app/conf/spring/resources.groovy
• /web-app/WEB-INF配下のすべて
• /web-app/plugins/**配下のすべて
• /test/** 配下のすべて
• **/.svn/** と **/CVS/**配下のSCM管理ファイル

アーテファクトをWEB-INFに含める必要がある場合には、プラグインインストール時に実行されるスクリプトである_Install.groovyスクリプト(後述)を使用することがお勧めです。なお、除外対象アーティファクトであるUrlMappings.groovyは除外されますが、UrlMappings情報は「MyPluginUrlMappings.groovy」などの異なる名前にしておけば、含めることができます。

Customizing the plugin contents

You can specify what to exclude in addition to the default excludes by adding elements to the pluginExcludes descriptor property (described below). In addition, there are two ways to configure the contents of the plugin ZIP or JAR file.

One is to create an event handler for the CreatePluginArchiveStart event, which is fired after all of the plugin files have been copied to the staging directory. By adding an event handler you can add, modify, or delete files as needed. Add the handler to _Events.groovy in the scripts directory, for example

eventCreatePluginArchiveStart = { stagingDir ->
   // update staging directory contents here
}

You can customize the location of the staging directory with the grails.project.plugin.staging.dir attribute in BuildConfig.groovy or as as system property.

Note that there is also a CreatePluginArchiveEnd event which is fired after the ZIP or JAR is packaged.

You can also do this work in a Closure in BuildConfig.groovy with the property grails.plugin.resources which is analogous to the grails.war.resources property, e.g.

grails.plugin.resources = { stagingDir ->
   // update staging directory contents here
}

プラグイン位置の指定

アプリケーションは、ファイルシステム上の任意の場所にあるプラグインをロードできますし、インストールしていないプラグインをロードすることさえも可能です。そのためには、アプリケーションのgrails-app/conf/BuildConfig.groovy設定ファイルに、パッケージされていないプラグインのディレクトリを以下のように指定します:

// Useful to test plugins you are developing.
grails.plugin.location.shiro =
        "/home/dilbert/dev/plugins/grails-shiro"
// Useful for modular applications where all plugins and
// applications are in the same directory.
grails.plugin.location.'grails-ui' = "../grails-grails-ui"

// 開発中のプラグインをテストするのに便利。
grails.plugin.location.shiro =
        "/home/dilbert/dev/plugins/grails-shiro"
// すべてのプラグインとアプリケーションを同じディレクトリに置き、
// モジュール化するのに便利。
grails.plugin.location.'grails-ui' = "../grails-grails-ui"

これが特に便利なのは、以下の2つの場合です:

• 開発中のプラグインを、パッケージ化とインストールをスキップして、実アプリケーションにすぐに組み込んでテストしたいとき。
• アプリケーションが複数のプラグイン群に分割されており、それらすべてが同じ「スーパープロジェクト」ディレクトリ配下にある場合。

The Artifactory repository for Grails now includes all the dependencies for published plugins. So, if you are using inline plugins that have dependencies, it is necessary to do a secondary resolve because these dependencies might not be in the repository. Therefore, you should set legacyResolve to true in your BuildConfig.groovy if you are using inline plugins with dependencies.

15.2 プラグインリポジトリ

プラグインをGrailsセントラルリポジトリに公開する

grails list-plugins

このコマンドはセントラルリポジトリのすべてのプラグインを一覧表示します。あなたのプラグインをplugin-infoコマンドで表示することもできます:

grails plugin-info [plugin-name]

これで説明や著者名、その他のプラグイン情報などを表示させることができます。

もしGrailsプラグインを開発して、セントラルリポジトリでホスティングしたい場合、アカウント入手の手順はこのWikiページにあります。

Grailsプラグインリポジトリにアクセス権を持っていれば、リリースプラグインを grails-app/conf/BuildConfig.groovy ファイルの依存管理'build'スコープに定義してインストールします。

grails.project.dependency.resolution = {
    …
    plugins {
        build ':release:3.0.0'
    }
}

And execute the publish-plugin command to release your plugin:

grails publish-plugin

This will automatically publish the plugin to the central repository. If the command is successful, it will immediately be available on the plugin portal at http://grails.org/plugin/<pluginName>. You can find out more about the Release plugin and its other features in its user guide.

追加リポジトリの設定

Grailsにおけるリポジトリの設定手順は、Grailsのバージョンによって異なっています。Grails 1.2以前の情報についてはGrails 1.2のドキュメンテーションを参照ください。以降の節は、Grails 1.3以降について記述しています。

Grails 1.3以上では、下位層に隠されているIvyがプラグインの依存性を解決します。プラグインリポジトリを追加定義する仕組みは、 JAR依存性を定義する方法とほぼ同じです。例えば、Grailsプラグインを含むリモートMavenリポジトリを定義するには、 grails-app/conf/BuildConfig.groovy中で以下のように記述します:

repositories {
    mavenRepo "http://repository.codehaus.org"
    // ...or with a name
    mavenRepo name: "myRepo",
              root: "http://myserver:8081/artifactory/plugins-snapshots-local"
}

grailsRepoメソッドを使ってSVNベースのGrailsリポジトリ(例えばhttp://plugins.grails.orgでホストされているリポジトリ)を定義することもできます:

repositories {
    grailsRepo "http://myserver/mygrailsrepo"
    // ...or with a name
    grailsRepo "http://myserver/svn/grails-plugins", "mySvnRepo" 
}

repositories {
    grailsCentral()
}

repositoriesの項目で列挙した順にプラグインは解決されます。なので以下ではGrailsセントラルリポジトリが最後に検索されます:

repositories {
    grailsRepo "http://myserver/mygrailsrepo"
    grailsCentral()
}

前述の例ではHTTPを使用していましたが、プラグイン解決に任意のIvyリゾルバを使用することもできます。以下はSSHリゾルバを使用する例です:

def sshResolver = new SshResolver(user:"myuser", host:"myhost.com")
sshResolver.addArtifactPattern(
        "/path/to/repo/grails-[artifact]/tags/" +
        "LATEST_RELEASE/grails-[artifact]-[revision].[ext]")
sshResolver.latestStrategy =
        new org.apache.ivy.plugins.latest.LatestTimeStrategy()
sshResolver.changingPattern = ".*SNAPSHOT"
sshResolver.setCheckmodified(true)

上記の例では、プラグインZIPファイルを解決する方法をIvyに伝えるため、アーテファクトのパターンを指定しています。Ivyパターンのより詳しい説明は、Ivyユーザガイドの関連するセクションを参照下さい。

Maven互換リポジトリへの公開

In general it is recommended for Grails 1.3 and above to use standard Maven-style repositories to self host plugins. The benefits of doing so include the ability for existing tooling and repository managers to interpret the structure of a Maven repository.

You use the Release plugin to publish a plugin to a Maven repository. Please refer to the section of the Maven deployment user guide on the subject.

15.3 プラグイン構造を理解する

すでに述べてきているように、プラグインは基本的にはプラグインディスクリプタが付随した通常のGrailsアプリケーションです。しかしながら、インストールされるときにはプラグインの構造は少し異なってきます。例えば、以下のプラグイン構造を見てみましょう:

+ grails-app
     + controllers
     + domain
     + taglib
     etc.
 + lib
 + src
     + java
     + groovy
 + web-app
     + js
     + css

プラグインがインストールされたときには、grails-appディレクトリの内容はplugins/example-1.0/grails-appに入ります。これらはメインアプリのソースツリーにはインストールされません。プラグインはプロジェクト本体側のソースツリーには決して干渉しないのです。

静的リソースの処理は、少しだけ異なってきます。プラグインをあたかもアプケーションのように開発する際、すべての静的リソースはweb-appディレクトリに入ります。静的リソースをアプリケーションからリンクすることもできます。以下の例ではJavaScriptソースをリンクしています:

<g:resource dir="js" file="mycode.js" />

プラグインを開発モード(development mode)で実行するときは、このようなリソースへのリンクは/js/mycode.jsなどに解決されます。しかし、プラグインがアプリケーションにインストールされたときは、パスは自動的に/plugin/example-0.1/js/mycode.jsのように自動的に変換され、Grailsはリソースを正しく扱うことができます。

プラグイン開発モードと、プラグインがアプリケーションにインストールされている場合のいずれにおいても、plugin.jsの正しいパスを見付けるのに、そのためのpluginContextPath変数を使用できます。

スタンドアローン実行中かアプリケーションにインストールされているかによって、pluginContextPath変数は空文字列もしくは/plugins/exampleのいずれかに実行時に評価されます。

プラグインが提供する、libやsrc/javaやsrc/groovyディレクトリ配下にあるJavaやGroovyコードは、実行時に利用できるようにメインプロジェクトのweb-app/WEB-INF/classesディレクトリ配下にコンパイルされます。

15.4 基本アーティファクトの提供

新たにスクリプトを追加する

プラグインのscriptディレクトリ配下に関連するGantスクリプトを置くことで、プラグインは新しいスクリプトを追加することができます:

+ MyPlugin.groovy
   + scripts     <-- additional scripts here
   + grails-app
        + controllers
        + services
        + etc.
    + lib

+ MyPlugin.groovy
   + scripts     <-- ここにスクリプトを追加する
   + grails-app
        + controllers
        + services
        + etc.
    + lib

Grails-appアーテファクト(Controller, Tag Library, Service, 他)の追加

grails-app配下のツリーに関連するファイルを置いておくことで、プラグインは新しいアーテファクトを追加することができます。プラグインはインストールされた場所から読み込まれるのであって、メインアプリのツリー中にコピーされるわけではないことに留意して下さい。

+ ExamplePlugin.groovy
   + scripts
   + grails-app
        + controllers  <-- コントローラを追加するのはここ。
        + services <-- サービスを追加するのはここ。
        + etc.  <-- 他も同様。
    + lib

ビューとテンプレートの提供、そしてビューの解決

プラグインがコントローラを提供するときは、レンダリングされるデフォルトのビューを提供しても構いません。これはアプリケーションをプラグインに分割するのに優れた方法です。

Grailsのビュー解決機構は、最初にプラグインがインストールされた親アプリケーション中のビューを探し、見付からなければプラグイン自身のビューを探してみます。これが意味するのは、アプリケーションのgrails-app/viewsディレクトリ中に対応するGSPを定義しておくことで、プラグインが提供するビューを上書きすることができるということです。

例えば、「アマゾン」プラグインが提供するBookControllerを考えてみて下さい。もしlistアクションが実行されたなら、Grailsは最初にgrails-app/views/book/list.gspを検索し、それに失敗した場合にプラグインディレクトリから相対的に同じ位置にあるビューを検索します。

しかしながら、同じくプラグインが提供するテンプレートをビューが使用しているときには、以下の構文が必要になります:

<g:render template="fooTemplate" plugin="amazon"/>

plugin属性でテンプレートがあるプラグインの名前を指定することに注意下さい。もしこれがなければ、Grailsはアプリケーション相対でテンプレートを探します。

アーテファクトを除外する

デフォルトでは、Grailsはプラグインのパッケージングの過程で以下のファイルを除外します:

• grails-app/conf/BootStrap.groovy
• grails-app/conf/BuildConfig.groovy (この情報はdependencies.groovyの生成に用いられるが、BuildConfig自体は含められない)
• grails-app/conf/Config.groovy
• grails-app/conf/DataSource.groovy (その他の*DataSource.groovyも同様)
• grails-app/conf/UrlMappings.groovy
• grails-app/conf/spring/resources.groovy
• /web-app/WEB-INF中のすべて
• /web-app/plugins/**中のすべて
• /test/**中のすべて
• **/.svn/**と**/CVS/**中のSCMが管理するファイル

もしプラグインがweb-app/WEB-INFディレクトリ配下のファイルを必要とするなら、プラグインディレクトリのscripts/_Install.groovyGantスクリプトを修正し、それらのアーテファクトをターゲットのプロジェクトのディレクトリツリーにコピーするようにすることをお勧めします。

加えて、名前衝突を避けるため、デフォルトではUrlMappings.groovyファイルは除外されていますが、「UrlMapping」が含まれる異なる名前のUrlMappings定義を追加するのは構いません。例えば、grails-app/conf/BlogUrlMappings.groovyなどの名前にしておくと良いでしょう。

除外リストはpluginExcludesプロパティで拡張することができます:

// resources that are excluded from plugin packaging
def pluginExcludes = [
    "grails-app/views/error.gsp"
]

// プラグインのパッケージングからは除外するリソース
def pluginExcludes = [
    "grails-app/views/error.gsp"
]

この指定は、デモやテスト用リソースとしてプラグインのソースリポジトリには含めたいが、プラグインとしての最終配布物には含めたくない、という場合に有用でしょう。

15.5 規約の評価

Grailsが提供する、規約ベースのランタイム設定を見ていく前に、あなたが理解しておくべきことは、これらのプラグインの規約がどう評価されるか、ということです。どのプラグインも、暗黙のapplication変数を持っていて、これはGrailsApplicationのインスタンスです。

このGrailsApplicationインターフェースは、プロジェクト中の規約を評価するためのメソッドを提供します。また、内部的にあなたのアプリのすべてのアーテファクトクラスへの参照を保存します。

アーテファクトはGrailsClassインターフェースを実装し、コントローラやタグライブラリのようなGrailsのリソースを表現します。例えばすべてのGrailsClassインスタンスを取得するには以下のようにします:

for (grailsClass in application.allClasses) {
    println grailsClass.name
}

GrailsApplicationはいくつかの「マジック」プロパティを持っていて、あなたの興味があるアーテファクトの型を狭めることができます。例えば、コントローラにアクセスするには以下のようにできます:

for (controllerClass in application.controllerClasses) {
    println controllerClass.name
}

• *Classes - 特定のアーテファクト名のすべてのクラスを取り出す。 例えばapplication.controllerClasses。
• get*Class - 特定のアーテファクトの、指定した名前のクラスを取り出す。 例えばapplication.getControllerClass("PersonController")。
• is*Class - もし指定したクラスが指定したアーテファクトタイプであればtrueを返す。 例えば、application.isControllerClass(PersonController)。

GrailsClassインターフェースは、規約に関する評価や処理をさらに容易にするための、以下のような便利なメソッド群を持っています:

• getPropertyValue - そのクラスの指定したプロパティの初期値を取得する。
• hasProperty - もしクラスが指定したプロパティを持っていたらtrueを返す。
• newInstance - このクラスの新しいインスタンスを返す。
• getName - 取得可能であれば、末尾の規約部分を除いた、アプリケーションにおける論理名を返す。
• getShortName - そのクラスのパッケージ接頭辞を除いた短縮名を返す。
• getFullName - 末尾の規約部分と先頭のパッケージ部分を含むクラスのフルネームを返す。
• getPropertyName - クラス名をプロパティ名として返す。
• getLogicalPropertyName - 末尾の規約部分を除き、アプリケーションにおけるクラスの論理プロパティ名を返す。
• getNaturalName - 自然な語句としてのプロパティ名を返す。(例: 'lastName'は'Last Name'になる)
• getPackageName - パッケージ名を返す。

全体のリファレンスについては、javadoc APIを参照してください。

15.6 ビルドイベントのフック

Post-Install設定とアップグレード

Grailsプラグインはpost-install設定を行なったり、アプリケーションの更新プロセス(upgradeコマンドで実行する)に介在することができます。これは2つの特別な名前のスクリプト、_Install.groovyと_Upgrade.groovyスクリプトを、プラグインのscriptsディレクトリ配下に置くことで可能になります。

_Install.groovyはプラグインがインストールされた後に実行され、_Upgrade.groovyコマンドはアプリケーションが upgradeコマンドで更新されるたびに実行されます(プラグインをupgradeコマンドで更新した時ではありません)。

これらのスクリプトは、Gantスクリプトであり、Gantの全機能を使用することができます。標準Gant変数に加えて、pluginBasedir変数があり、プラグインがインストールされているベースディレクトリを指定しています。

例えば、以下の_Install.groovyスクリプトはgrails-appディレクトリ配下に新しいディレクトリを作成し、設定テンプレートをインストールします:

ant.mkdir(dir: "${basedir}/grails-app/jobs")
ant.copy(file: "${pluginBasedir}/src/samples/SamplePluginConfig.groovy",
         todir: "${basedir}/grails-app/conf")

pluginBasedir変数はカスタムスクリプト中では利用できませんが、fooがプラグイン名であるとき、fooPluginDirを使うことができます。

イベントをスクリプトで処理する

コマンドラインスクリプトを実行中のイベントをフックすることもできます。Grailsターゲットとプラグインスクリプトの実行中に発生するイベントがあります。

例えば、状態の変更イベント(「テストがパスしたとき」や「サーバが実行開始」など)や、ファイルやアーテファクトの生成イベントなどにもフックすることができます。

プラグインが必要なイベントをlistenするために必要なのは、_Events.groovyスクリプトを提供することだけです。より詳しい情報については、イベントをフックするを参照してください。

15.7 ランタイム設定へのフック

Grailsはシステムの異なる部分を利用するために、多くのフックを提供し、規約によって実行時設定を行います。

GrailsのSpring設定にフックする

まず、doWithSpringという名前の、クロージャブロックが代入されたプロパティを提供することで、Grails実行時設定にフックすることができます。例えば以下のコード断片は、 i18nサポートを提供するコアGrailsプラグインに含まれているものです:

import org.springframework.web.servlet.i18n.CookieLocaleResolver
import org.springframework.web.servlet.i18n.LocaleChangeInterceptor
import org.springframework.context.support.ReloadableResourceBundleMessageSource
class I18nGrailsPlugin {
    def version = "0.1"
    def doWithSpring = {
        messageSource(ReloadableResourceBundleMessageSource) {
            basename = "WEB-INF/grails-app/i18n/messages"
        }
        localeChangeInterceptor(LocaleChangeInterceptor) {
            paramName = "lang"
        }
        localeResolver(CookieLocaleResolver)
    }
}

このプラグインは、GrailsのmessageSourceビーンと、Locale解決と切り替えを行う他のいくつかのビーンを設定します。これはSpringビーンビルダのシンタックスを使用します。

web.xml生成への参加

GrailsはWEB-INF/web.xmlファイルをロード時に生成し、プラグインはこのファイルを直接変更することはできませんが、このファイルの生成過程に参加することができます。プラグインはクロージャコードブロックが代入されたdoWithWebDescriptorプロパティを提供することができ、そのコードにはXmlSlurperのGPathResultとしてweb.xmlが渡されます。

servletとservlet-mappingの追加

ControllersPluginにある、以下の例を考えてみてください:

def doWithWebDescriptor = { webXml ->
    def mappingElement = webXml.'servlet-mapping'
    def lastMapping = mappingElement[mappingElement.size() - 1]
    lastMapping + {
        'servlet-mapping' {
            'servlet-name'("grails")
            'url-pattern'("*.dispatch")
        }
    }
}

XmlSlurperの「クロージャとブロックを使ってプログラム的にXMLを修正できる」という機能を使って、ここではプラグインは<servlet-mapping>への参照を取得し、Grailsのサーブレットを追加しています。

filterとfilter-mappingの追加

マッピングを伴うフィルターの追加は少し異なります。順序は重要ではないので、<filter>要素の場所は問題になりません。なのでカスタムフィルタ定義を最後の<context-param>要素のすぐ後に挿入するのが最も簡単です。マッピングに関しては 順序は重要 です。しかし通常の場合、<filter>要素の直後に追加してしまいます:

def doWithWebDescriptor = { webXml ->
    def contextParam = webXml.'context-param'
    contextParam[contextParam.size() - 1] + {
        'filter' {
            'filter-name'('springSecurityFilterChain')
            'filter-class'(DelegatingFilterProxy.name)
        }
    }
    def filter = webXml.'filter'
    filter[filter.size() - 1] + {
        'filter-mapping'{
            'filter-name'('springSecurityFilterChain')
            'url-pattern'('/*')
        }
    }
}

フィルターは、例えばSpringの文字エンコーディングフィルタやSiteMeshフィルタなどの標準Grailsフィルターの後に実行されなければならない場合があります。この場合、以下のようにすることで、フィルタマッピングを標準のフィルタ(正確に言えば、テンプレートのweb.xmlファイルに含まれている任意のもの)のすぐ後に挿入することができます:

def doWithWebDescriptor = { webXml ->
    ...
    // Insert the Spring Security filter after the Spring
    // character encoding filter.
    def filter = webXml.'filter-mapping'.find {
        it.'filter-name'.text() == "charEncodingFilter"
    }
    filter + {
        'filter-mapping'{
            'filter-name'('springSecurityFilterChain')
            'url-pattern'('/*')
        }
    }
}

初期化設定後の実行

ApplicationContextが構築された後で実行時設定を行うことが有用な場合があります。そのためにはdoWithApplicationContextクロージャプロパティを定義します。

class SimplePlugin {
    def name = "simple"
    def version = "1.1"
    def doWithApplicationContext = { appCtx ->
        def sessionFactory = appCtx.sessionFactory
        // do something here with session factory
    }
}

15.8 実行時のダイナミックメソッド追加

基本的な考え方

Grailsプラグインでは、Grails管理下および他のクラスに対して、実行時にダイナミックメソッドを登録することができます。これはdoWithDynamicMethodsクロージャで行ないます。

コントローラやタグライブラリなどのようなGrails管理下のクラスについては、それぞれのコントローラのMetaClassを ExpandoMetaClass の機構でアクセスすることによって、メソッドやコンストラクタなどを追加できます:

class ExamplePlugin {
    def doWithDynamicMethods = { applicationContext ->
        for (controllerClass in application.controllerClasses) {
             controllerClass.metaClass.myNewMethod = {-> println "hello world" }
        }
    }
}

この場合、暗黙のapplicationオブジェクトを使い、すべてのコントローラクラスのMetaClassの参照を取得し、それぞれのコントローラにmyNewMethodという新規メソッドを追加しています。メソッドを追加したいクラスが予め判っていれば、そのmetaClassプロパティを単純に参照できます。

例えば、swapCaseメソッドをjava.lang.Stringクラスに追加できます:

class ExamplePlugin {
    def doWithDynamicMethods = { applicationContext ->
        String.metaClass.swapCase = {->
             def sb = new StringBuilder()
             delegate.each {
                 sb << (Character.isUpperCase(it as char) ?
                        Character.toLowerCase(it as char) :
                        Character.toUpperCase(it as char))
             }
             sb.toString()
        }
        assert "UpAndDown" == "uPaNDdOWN".swapCase()
    }
}

アプリケーションコンテキストとの相互作用

doWithDynamicMethodsクロージャにはSpringのApplicationContextインスタンスが渡されます。これはその中のオブジェクトとやりとりできるので便利です。例えば、Hibernateと相互作用するメソッドを定義しているなら、SessionFactoryインスタンスとHibernateTemplateを組合せて使うことができます:

import org.springframework.orm.hibernate3.HibernateTemplate
class ExampleHibernatePlugin {
   def doWithDynamicMethods = { applicationContext ->
       for (domainClass in application.domainClasses) {
           domainClass.metaClass.static.load = { Long id->
                def sf = applicationContext.sessionFactory
                def template = new HibernateTemplate(sf)
                template.load(delegate, id)
           }
       }
   }
}

Springコンテナにはオートワイアリング(autowiring)と依存性注入(DI)機能があるので、依存性を実行時に解決するのにアプリケーションコンテキストを使用する、より強力なダイナミックコンストラクタをあなたのオブジェクトに実装することもできます:

class MyConstructorPlugin {
    def doWithDynamicMethods = { applicationContext ->
         for (domainClass in application.domainClasses) {
              domainClass.metaClass.constructor = {->
                  return applicationContext.getBean(domainClass.name)
              }
         }
    }
}

ここでは、デフォルトコンストラクタを、prototypeのSpringビーンをルックアップするようなコンストラクタに実際に置き換えています。

15.9 自動リロードイベントへの参加

リソース変更の監視

リソース変更を監視し、変更された場合に何らかのアクションを実行することが便利なときがあります。この方法を用いて、Grailsではアプリケーションの状態が実行時に変化したときに高度なリローディングを行っています。例えば、ServicesPluginのにあるものを単純化した以下のコード断片を見てください:

class ServicesGrailsPlugin {
    …
    def watchedResources = "file:./grails-app/services/*Service.groovy"
    …
    def onChange = { event ->
        if (event.source) {
            def serviceClass = application.addServiceClass(event.source)
            def serviceName = "${serviceClass.propertyName}"
            def beans = beans {
                "$serviceName"(serviceClass.getClazz()) { bean ->
                    bean.autowire =  true
                }
            }
            if (event.ctx) {
                event.ctx.registerBeanDefinition(
                        serviceName,
                        beans.getBeanDefinition(serviceName))
            }
        }
    }
}

最初にwatchedResources変数を定義していますが、これは監視対象としたいリソースへの参照もしくはパターンを含む、文字列もしくは文字列のリストです。もし監視されるリソースがGroovyファイルを指定しているのであれば、それが変更されたときには自動的にリロードが実行されます。そして、onChangeクロージャが呼び出され、Groovyファイルはその引数であるeventオブジェクト中に設定されます:

eventオブジェクトは多数の有用なプロパティを含んでいます:

• event.source - イベントの発生元。リロードされたClassもしくはSpring Resource。
• event.ctx - Spring ApplicationContextインスタンス
• event.plugin - このリソースを管理しているプラグインオブジェクト(通常this)。
• event.application - GrailsApplicationインスタンス
• event.manager - GrailsPluginManagerインスタンス

何が変更されたかによって異なる適切な変更をするためには、これらのオブジェクトが利用可能です。前述のサービスの例においては、サービスクラスが変更されたとき、新しいサービスビーンがApplicationContextにおいて再登録されます。

他のプラグインに影響を及ぼす

変更に対してリアクションするのに加え、プラグインは他のプラグインに「影響を及ぼす」必要があるときがあります。

サービスとコントローラのプラグインを例にとりましょう。サービスがリロードされた場合、コントローラもリロードしなければ、リロードされたサービスを古いコントローラクラスにオートワイヤ(auto-wire)するときに問題が発生するでしょう。

この問題を回避するために、どのプラグインが他のプラグインに「影響を及ぼす」のかを指定することができます。これが意味するのは、あるプラグインが変更を検出したとき、そのプラグイン自身がリロードされた後に、それが「影響を及ぼしている」プラグインもリロードされるということです。例えば、ServicesGrailsPluginにある以下のコード断片を考えてみましょう:

def influences = ['controllers']

他のプラグインを観察する

変更を観察したい特定のプラグインがあり、そのプラグインが監視するリソースを監視する必要がないなら、「observe」プロパティを使うことができます:

def observe = ["controllers"]

この場合、コントローラが変更されたとき、あなたのプラグインもコントローラプラグインから連鎖したイベントを受け取ります。

ワイルドカードを使えば、すべてのプラグインの変更を監視することも可能です:

def observe = ["*"]

ロギングプラグインはちょうどこのようなことを行なっており、アプリの実行中に変更があった 任意の アーティファクトにlogプロパティを設定し直しています。

15.10 プラグインのロード順を理解する

プラグインの依存性制御

プラグインはしばしば他のプラグインの存在に依存しますが、他のプラグインの存在についての依存性に適応することができます。これは2つのプロパティで行うことができます。1つ目はdependsOnというプロパティですが、Hibernateプラグインにある以下のコード断片を見て下さい:

class HibernateGrailsPlugin {
    def version = "1.0"
    def dependsOn = [dataSource: "1.0",
                     domainClass: "1.0",
                     i18n: "1.0",
                     core: "1.0"]
}

Hibernateプラグインは4つのプラグインに依存しています: dataSource、domainClass、i18nそしてcoreプラグインです。

依存しているプラグインは、Hibernateプラグインの前に読み込まれます。すべての依存プラグインがロードされなければ、プラグインはロードされません。

dependsOnプロパティはバージョン範囲を指定するためのミニ式言語をサポートしています。以下は例です：

def dependsOn = [foo: "* > 1.0"]
def dependsOn = [foo: "1.0 > 1.1"]
def dependsOn = [foo: "1.0 > *"]

ワイルドカード文字が任意のバージョンを表わすために使われます。また、この式のシンタックスは、「-BETA」や「-ALPHA」といった接尾辞を除外します。なので例えば「1.0 > 1.1」は以下のバージョンにマッチします。

• 1.1
• 1.0
• 1.0.1
• 1.0.3-SNAPSHOT
• 1.1-BETA2

ロード順序の制御

dependsOnは、依存性が解決されなければプラグインのロードをあきらめるような「ハード依存性」を確立します。loadAfterとloadBeforeプロパティを使うことで「より弱い依存性」を使うこともできます。

def loadAfter = ['controllers']

ここでは、もしcontrollersプラグインが存在すれば、それがロードされた後に、このプラグインがロードされます。 さもなければ(controllersプラグインが存在しなければ)、このプラグインは単にロードされます。プラグインは他のプラグインの存在に適応します。たとえば、HibernateプラグインはdoWithSpringクロージャで以下を行っています:

if (manager?.hasGrailsPlugin("controllers")) {
    openSessionInViewInterceptor(OpenSessionInViewInterceptor) {
        flushMode = HibernateAccessor.FLUSH_MANUAL
        sessionFactory = sessionFactory
    }
    grailsUrlHandlerMapping.interceptors << openSessionInViewInterceptor
}

ここではHibernateプラグインは、controllersプラグインがロードされてれば、OpenSessionInViewInterceptorだけを登録します。manager変数はGrailsPluginManagerインターフェースのインスタンスであり、他のプラグインと相互作用するためのメソッドを提供しています。

loadBeforeプロパティには、あなたのプラグインの前にロードしておかなければならない1個以上のプラグインを指定します。

def loadBefore = ['rabbitmq']

スコープと環境

制御できるのはプラグインのロード順だけではありません。プラグインがどの環境にロードされるか、あるいはどのスコープ(ビルドの各段階)でロードされるかを指定することもできます。やり方は、それぞれのプロパティをプラグインディスクリプタ中に宣言するだけです。

def environments = ['development', 'test', 'myCustomEnv']
def scopes = [excludes:'war']

この例では、プラグインは「development」と「test」環境のときだけロードされます。また、warフェイズからは除外設定されているので、WARファイル中にはパッケージされません。こうすることで、development-onlyのプラグインは、実運用時にはパッケージされないようにできます。

利用可能なスコープの全てのリストはenum BuildScopeで定義されていますが、以下はその抜粋です:

* test - when running tests
* functional-test - when running functional tests
* run - for run-app and run-war
* war - when packaging the application as a WAR file
* all - plugin applies to all scopes (default)

• test - テスト実行時
• functional-test - ファンクショナルテスト実行時
• run - run-appもしくはrun-war時
• war - アプリケーションがWARファイルにパッケージ化されたとき
• all - 全てのスコープに適用されるプラグイン(デフォルト)

いずれのプロパティにも以下のうち1つを設定することができます。

• a string - 1つ含む
• a list - 含められるべき環境もしくはスコープのリスト
• a map - 全ての制御。キーは'includes'か'excludes'で、バリューは文字列もしくはリスト

例えば、

def environments = "test"

という指定の場合、テスト環境のみでプラグインが含められます。これに対して

def environments = ["development", "test"]

はdevelopment と test環境の両方を含みます。最後に

def environments = [includes: ["development", "test"]]

も同様の意味です。

15.11 アーテファクトAPI

これまでの説明で、Grailsにはアーテファクトという概念があることが理解できたと思います。アーテファクトは特別なクラス型であり、通常のGroovyやJavaクラスとは異なるやり方で処理されます。例えば、プロパティやメソッドを追加することで拡張できます。アーテファクトの例は、ドメインクラスやコントローラです。気づいていなかったかもしれませんが、Grailsはアプリケーションやプラグイン開発者が、アーテファクトのための下位層のインフラストラクチャにアクセスすることを許しています。これが意味するのは、どんなアーテファクトが利用可能であるかを調べたり、あるいはそれらを拡張したりすることができるということです。また、あなた独自のカスタムアーテファクト型を追加することさえも可能です。

15.11.1 使用可能なアーテファクトの検索

プラグイン開発者からすると、アプリケーションにおいて、どのドメインクラス・コントローラや他のアーテファクトが利用可能かが分かる、ということが重要かもしれません。 例えば、Searchableプラグインは、インデックス化すべきであることを指定するsearchableプロパティをチェックするために、どんなドメインクラスが存在しているかをまず知る必要があります。では、どんなふうにチェックできるのでしょう？ 答えはgrailsApplicationオブジェクトとGrailsApplicationのインスタンスにあります。これらはコントローラとGSP中では自動的に利用可能となり、他の任意の場所で注入しておくことができます。

grailsApplicationオブジェクトは、アーテファクトを検索するためのいくつかの重要なプロパティとメソッドを保持しています。

for (cls in grailsApplication.<artefactType>Classes) {
    …
}

この場合、artefactTypeは、プロパティ名中でアーテファクト型を指定する形式であり、Grailsコアでは以下が指定できます:

• domain
• controller
• tagLib
• service
• codec
• bootstrap
• urlMappings

例えば、繰り返し処理をすべてのドメインクラスについてしたいならば、以下を使います:

for (cls in grailsApplication.domainClasses) {
    …
}

URLマッピングの場合なら以下です:

for (cls in grailsApplication.urlMappingsClasses) {
    …
}

これらのプロパティが返すのはクラス(java.lang.Class)のインスタンスではないことに留意する必要があります。そうではなく、これらはGrailsClassのインスタンスであり、下位のClass型用のものも含め、以下のような便利なプロパティやメソッドが利用可能です。

• shortName - パッケージ部分を除いたアーテファクトのクラス名(Class.simpleNameと等価)
• logicalPropertyName - プロパティ中で用いられる名アーテファクトの名前から型接尾辞を除いたもの。MyGreatControllerは「myGreat」になる。
• isAbstract() - アーテファクトクラスがabstractかどうかを表すブーリアン値
• getPropertyValue(name) - 指定したプロパティ値を、staticか非staticかどうかに関わらず返す。もしプロパティが「static transactional = true」のように初期化されて宣言されていたときにも動作する。

アーテファクトAPIで、クラスを名前で取得したり、指定したクラスがアーテファクトかどうかを判断したりすることができます:

• get<type>Class(String name)
• is<type>Class(Class clazz)

最初のメソッドは、指定した名前、たとえば「MyGreatController」からGrailsClassインスタンスを取得します。二番目のメソッドは、クラスが特定のアーテファクトの型かどうかを判断します。例えば、grailsApplication.isControllerClass(org.example.MyGreatController)とすることで、MyGreatControllerがコントローラかどうかをチェックすることができます。

15.11.2 アーテファクト型の追加

プラグインでは、どんな実装が利用できるかわかり、自動リロードの過程に組込むことができるような、自分自身のアーテファクトを簡単に提供することができます。そのためにやるべきことは、ArtefactHandlerの実装を生成し、メインのプラグインクラス中に登録しておくことだけです:

class MyGrailsPlugin {
    def artefacts = [ org.somewhere.MyArtefactHandler ]
    …
}

リストartefactsは、ハンドラクラス(上述)もしくはハンドラの一連のインスタンスを保持することができます。

それでは、アーテファクトハンドラは、どのようなものでしょうか？ここでは単にArtefactHandlerインターフェースを実装するものということにしておきます。利便のため、extendsすればすぐ使えるスケルトン実装ArtefactHandlerAdapterも用意されています。

ハンドラそれ自身に加えて、新しいアーテファクトは、GrailsClassをimplementsする対応するラッパークラスを必要とします。こちらもAbstractInjectableGrailsClassなどのスケルトン実装が利用可能です。これはあなたのアーテファクトを、コントローラやサービスのようにオートワイヤ可能なSpringビーンにしてくれるので特に便利でしょう。

ハンドラとラッパーの動作を理解するのにベストなやり方は、Quartz pluginのコードを読んでみることです:

• GrailsJobClass
• DefaultGrailsJobClass
• JobArtefactHandler

他の例としては、Shiroプラグインがあり、こちらはrealmアーテファクトを追加します。

15.12 バイナリープラグイン

• Mavenリポジトリで通常のJARファイルで配布可能。
• バイナリプラグインは他のJARと同じように依存管理が行える。
• ソースコードを公開しない商用プラグインが可能
• 通常のJARになることによって、IDE等の環境で扱いやすくなる

パッケージング

Packaging

grails package-plugin --binary

• コントローラ、ドメイン等のGrailsのアーテファクトクラス
• I18nメッセージファイル
• GSPビュー、レイアウト、テンプレート

def packaging = "binary"

バイナリプラグイン使用方法

Using Binary Plugins

dependencies {
    compile "mycompany:myplugin:0.1"
}

Since binary plugins are packaged as JAR files, they are declared as dependencies in the dependencies block, not in the plugins block as you may be naturally inclined to do. The plugins block is used for declaring traditional source plugins packaged as zip files

バイナリプラグインは依存定義をdependenciesブロックに記述します。pluginsブロックは今までのソースコードがzipされたプラグインで使用します。