Red Hatエンジニアリングの佐藤匡剛です。昨年12月の赤帽エンジニアAdvent Calendarの記事で、Camel 3へのマイグレーションガイドの紹介記事を年明けに書くと宣言していましたが、ようやく書きました。
今回紹介する本家のガイドは、こちらです。
Apache Camel 2.x to 3.0 Migration Guide - Apache Camel
このガイドは長いので、このブログでは2つの記事(camel-core編、コンポーネント編)に分けてお送りします。コンポーネント編はこちらです。
今回は、camel-core編です。
- Javaのバージョン
- ランタイム/プラットフォーム
- camel-coreのモジュール化
- CamelContext
- Message API
- ルート/エンドポイント
- その他のAPI
- EIP
- テスト
- 管理/監視
- カスタムコンポーネント/言語
- 言語
- Camel Mavenプラグイン
- 既知の問題
- 最後に
Javaのバージョン
Camel 3が正式にサポートするのはJava 11です。当面はJava 8もベストエフォートでサポートを続けますが、いずれどこかの段階でドロップされます。
JAXB
Java 11でJAXBを使うには、Maven dependencyの明示的な追加が必要です。XML DSLでJAXBを使っていたり、camel-jaxbコンポーネントを使っている場合は、これらのdependencyをpom.xmlに追加します。
<dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>2.3.1</version> </dependency> <dependency> <groupId>com.sun.xml.bind</groupId> <artifactId>jaxb-core</artifactId> <version>2.3.0.1</version> </dependency> <dependency> <groupId>com.sun.xml.bind</groupId> <artifactId>jaxb-impl</artifactId> <version>2.3.2</version> </dependency>
ランタイム/プラットフォーム
Spring Boot StarterのGroup ID変更
Spring Boot StarterのMaven groupIdがorg.apache.camelからorg.apache.camel.springbootに変更されました。
Camel 2.x:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-component-starter</artifactId> </dependency>
Camel 3.0:
<dependency> <groupId>org.apache.camel.springboot</groupId> <artifactId>camel-component-starter</artifactId> </dependency>
Mainクラス
CamelのMainクラス(Camelアプリケーションをスタンドアロンで実行するためのユーティリティクラス)が含まれるJARが、camel-coreからcamel-mainに変わりました。Mainクラスを使っている方は、camel-mainのpom.xmlへの追加が必要です。
camel-coreのモジュール化
camel-core
Camel 3の大きな変更の1つがcamel-coreのモジュール化です。camel-coreは、以下のJARに細分化されました。後方互換性のために、これらを1つにまとめたcamel-coreは引き続き提供されていますが、マイクロサービス化のためにアプリケーションをスリムダウンしたい方は必要なdependencyだけをピックアップして使えます。
- camel-api
- camel-base
- camel-caffeine-lrucache
- camel-cloud
- camel-core
- camel-jaxp
- camel-main
- camel-management-api
- camel-management
- camel-support
- camel-util
- camel-util-json
コアコンポーネント
さらに、camel-coreに含まれていた下記のコアコンポーネントも、通常のコンポーネントと同様に外だしされました。それぞれ、使いたいコンポーネントをピックアップして使う形になります。
- camel-attachments
- camel-bean
- camel-browse
- camel-controlbus
- camel-dataformat
- camel-dataset
- camel-direct
- camel-directvm
- camel-file
- camel-language
- camel-log
- camel-mock
- camel-ref
- camel-rest
- camel-saga
- camel-scheduler
- camel-seda
- camel-stub
- camel-timer
- camel-validator
- camel-vm
- camel-xpath
- camel-xslt
- camel-xslt-saxon
- camel-zip-deflater
CamelContext
複数CamelContextの非サポート
元々アプリケーションのデプロイメント毎に複数のCamelContextを定義する方法は、推奨されてもおらず100%完全な実装でもなかったのですが、Camel 3ではデプロイメント毎に1つのCamelContextのみサポート、ということが明示化されました。
それに伴い、複数のCamelContextを扱うために提供されていたAPIはごっそり削除されました。@EndpointInject、@Produce、@ConsumeなどのCamelアノテーションにあったcontext属性は削除されました。
Mainクラスの複数CamelContext非サポート
camel-core、camel-spring、camel-cdiのMainクラスでも、同様に1つのCamelContextのみ対応するための変更が加えられています。具体的には、getCamelContextMap()メソッドが削除され、getCamelContext()メソッドだけになりました。
CamelContextのグローバルオプション
Camel 2.xでdeprecatedだったCamelContextのgetProperties()は削除されました。代わりに、getGlobalOptions()を使います。
Java:
context.getGlobalOptions().put("CamelJacksonEnableTypeConverter", "true"); context.getGlobalOptions().put("CamelJacksonTypeConverterToPojo", "true");
XML:
<globalOptions> <globalOption key="CamelJacksonEnableTypeConverter" value="true"/> <globalOption key="CamelJacksonTypeConverterToPojo" value="true"/> </globalOptions>
ExtendedCamelContext
CamelContextのAPIが一般ユーザ向けに整理され、高度なユースケース向けのAPIやSPIはExtendedCamelContextに移されました。ExtendedCamelContextには以下のようにしてアクセスします。
ExtendedCamelContext ecc = context.adapt(ExtendedCamelContext.class);
ModelCamelContext
ModelCamelContextにあったloadRouteDefinitions()とloadRestDefinitions()のメソッドは、他のメソッドと名前を揃えるためにaddRouteDefinitions()とaddRestDefinitions()になりました。ローダ関連のメソッドはModelHelperユーティリティクラスに見つかります。
ModelCamelContextにアクセスしたいときは、以下のようにします。
ModelCamelContext mcc = camelContext.adapt(ModelCamelContext.class);
CatalogCamelContext
CamelContextに定義されていたカタログ関連のメソッドは、CatalogCamelContextインタフェースに移動しました。以下のようにして使います。
CatalogCamelContext ccc = context.adapt(CatalogCamelContext.class);
CamelContextによるルートの制御
CamelContextにあったstartRoute()、stopRoute()、suspendRoute()、resumeRoute()、getRouteStatus()とその他関連するメソッドはRouteControllerクラスに移されました。以下のようにアクセスします。
context.getRouteController().startRoute("myRoute");
Message API
MessageのgetOut()
MessageクラスのhasOut()、getOut()メソッドはdeprecateになりました。代わりにシンプルにgetMessage()を使います。メッセージのINとOUTというコンセプトは廃止になりました。これらは、JBIやSOAPといった古い仕様から採用されたものですが、実際はそれほど有用でなかったためです。
それに伴い、他の部分でもIN、OUTのコンセプトに基づいた要素は削除されています。Beanパラメータバインディングの@OutHeadersアノテーションは削除され、代わりに@Headersを使います。
MessageのFault API
MessageクラスのFault APIも削除されました。SOAPのFaultメッセージにしか使われていなかったためです。handleFaultオプションも削除されています。
SOAPを扱うcamel-cxf、camel-spring-wsコンポーネントでは、それぞれ独自にFaultメッセージを実装していて、handleFaultの有効化をコンポーネント/エンドポイントのオプションとして設定する必要があります。
MessageのAttachments API
javax.activationのAttachments APIは、Messageクラスからcamel-attachmentsのorg.apache.camel.attachment.AttachmentMessageクラスに移動しました。
使い方は、以下のとおりです。
AttachmentMessage am = exchange.getMessage(AttachmentMessage.class); am.addAttachment("myAtt", new DataHandler(...));
ルート/エンドポイント
consumer.プレフィクスの付いたエンドポイントオプションの削除
consumer.プレフィクスの付いたエンドポイントオプションは廃止されました。今後は、consumer.プレフィクスを付けずにそのままオプションを指定します。
例)consumer.delay=5000 → delay=5000
POJOアノテーション
@Consume、@Produce、@EndpointInjectのref属性は削除されました。代わりに、value属性にrefコンポーネントを使い、以下のようにします(valueは省略可能なことに注意)。
@Consume("ref:myName")
上記にuri属性を使うこともできますが、uri属性自体もdeprecatedになっていて、代わりにvalue属性を使う必要があります。そのため、全般に、@Consume(uri = "jms:cheese")ではなく@Consume("jms:cheese")を使います。
複数インプットのあるルート
Camel 2.xでは、実はルートは2つ以上のインプットを持つことが(部分的に)できたのですが、ほとんど使われていませんでした。Camel 3では、この機能を削除し、明示的に1つのルートで1つのインプットしか受け付けないようにしました。
ルートポリシー
org.apache.camel.support.RoutePolicySupportクラスはcamel-supportに移りました。メソッドstartConsumer()、stopConsumer()の戻り値はbooleanからvoidに変更されました(元々trueしか返していなかったため)。
org.apache.camel.impl.ThrottlingInflightRoutePolicyクラスはorg.apache.camel.throttling.ThrottlingInflightRoutePolicyにパッケージが変わりました。
XML DSLのマイグレーション
XML DSLのタグに細かな修正が入っています。
- カスタムロードバランサーEIPのタグが
<custom>から<customLoadBalancer>に変更された - XML Securityデータフォーマットで
<secureXML>タグのkeyOrTrustStoreParametersId属性がkeyOrTrustStoreParametersRefに名前変更された <zipFile>データフォーマットが<zipfile>に名前変更された
その他の変更
RestEndpointクラスのbindingMode向けのgetter/setterメソッドは、camel-apiのorg.apache.camel.spi.RestConfiguration.RestBindingMode型を使う形に変更されました。setterメソッドに関しては、String型を使うバージョンも残されてます。RouteBuilderクラスのincludeRoutes()メソッドは削除されました。このメソッドはCamel 2.xの頃からdeprecatedでした。
その他のAPI
非推奨API、コンポーネントの削除
Camel 2.xで既にdeprecatedになっていたAPIやコンポーネントは、Camel 3で全部削除されました。
検査例外 vs 非検査例外
Camelのほとんどの例外クラスは非検査例外(RuntimeExceptionのサブクラス)になりました。
また、ServiceおよびSuspendableServiceのライフサイクルメソッドstart()、stop()、suspend()、resume()も検査例外を投げないようになりました。
FactoryFinderクラスのAPIは、検査例外FactoryNotFoundExceptionやClassNotFoundException等をスローする代わりに、Optional型を返すように変更されました。
HelperとSupport
HelperおよびSupportのクラスの変更は以下の通りです。
org.apache.camel.util.AsyncProcessorHelper(camel-core) →org.apache.camel.support.AsyncProcessorHelper(camel-support)org.apache.camel.util.AsyncProcessorConverterHelper(camel-core) →org.apache.camel.support.AsyncProcessorConverterHelper(camel-support)org.apache.camel.util.CamelContextHelper(camel-core) →org.apache.camel.support.CamelContextHelper(camel-support)org.apache.camel.util.EndpointHelper(camel-core) →org.apache.camel.support.EndpointHelper(camel-support)org.apache.camel.util.EventHelper(camel-core) →org.apache.camel.support.EventHelper(camel-support)org.apache.camel.util.ExchangeHelper(camel-core) →org.apache.camel.support.ExchangeHelper(camel-support)org.apache.camel.util.GZIPHelper(camel-core) →org.apache.camel.support.GZIPHelper(camel-support)org.apache.camel.util.JsonSchemaHelper(camel-core) →org.apache.camel.support.JsonSchemaHelper(camel-support)org.apache.camel.util.MessageHelper(camel-core) →org.apache.camel.support.MessageHelper(camel-support)org.apache.camel.util.ObjectHelper(camel-core) →org.apache.camel.support.ObjectHelper(camel-support) &org.apache.camel.util.ObjectHelper(camel-util)- camel-apiに依存したメソッドはcamel-supportに、それ以外はcamel-utilに移動
org.apache.camel.util.PlatformHelper(camel-core) →org.apache.camel.support.PlatformHelper(camel-support)org.apache.camel.util.PredicateAssertHelper(camel-core) →org.apache.camel.support.PredicateAssertHelper(camel-support)org.apache.camel.util.ResolverHelper(camel-core) →org.apache.camel.support.ResolverHelper(camel-support)org.apache.camel.util.ResourceHelper(camel-core) →org.apache.camel.support.ResourceHelper(camel-support)org.apache.camel.spi.RestProducerFactoryHelper(camel-core) →org.apache.camel.support.RestProducerFactoryHelper(camel-support)org.apache.camel.util.ServiceHelper(camel-core) →org.apache.camel.support.service.ServiceHelper(camel-api)org.apache.camel.util.UnitOfWorkHelper(camel-core) →org.apache.camel.support.UnitOfWorkHelper(camel-support)org.apache.camel.processor.loadbalancer.SimpleLoadBalancerSupportは削除されました。代わりにorg.apache.camel.processor.loadbalancer.LoadBalancerSupportを使います。
冪等リポジトリ
冪等リポジトリ(IdempotentRepository)クラスも以下のように場所が移動しています。
org.apache.camel.processor.idempotent.FileIdempotentRepository(camel-core) →org.apache.camel.support.processor.idempotent.FileIdempotentRepository(camel-support)org.apache.camel.processor.idempotent.MemoryIdempotentRepository(camel-core) →org.apache.camel.support.processor.idempotent.MemoryIdempotentRepository(camel-support)
アグリゲーション
XsltAggregationStrategyクラスは以下のように場所が移動しています。
org.apache.camel.builder.XsltAggregationStrategy(camel-core) →org.apache.camel.component.xslt.XsltAggregationStrategy(camel-xslt)
org.apache.camel.builder.AggregationStrategiesクラスのxslt()メソッドは削除されました。代わりにcamel-xsltのXsltAggregationStrategyを直接使います。
Aggregate EIPのgroupExchanges()オプションを使った場合でも、アウトプットがExchange.GROUPED_EXCHANGEに格納されることはなくなりました。これは、既にCamel 2.13以降deprecatedになっていた挙動でした。
JSSE
org.apache.camel.util.jsseパッケージのクラスは、org.apache.camel.support.jsseパッケージに移りました。
フォールバック型コンバータ
@FallbackConverterは削除されました。代わりに@Converter(fallback = true)を使います。さらに、@Converter(generateLoader = true)とすることでCamelが型コンバータをより高速にロードするためのコードを自動生成できるようになりました。
レジストリ
SimpleRegistryクラスがorg.apache.camel.implパッケージからorg.apache.camel.supportパッケージに移動しました。ただし、今後はorg.apache.camel.support.DefaultRegistryを代わりに使うべきです。さらに、SimpleRegistryまたはDefaultRegistryにエントリを追加するのに、put()メソッドでなくbind()メソッドを使ってください。
CompositeRegistry、PropertyPlaceholderDelegateRegistryクラスは共に削除されました。代わりにDefaultRegistryを使います。
アノテーション
アノテーション関連の細かな変更は以下のとおりです。
org.apache.camel.Constantアノテーションは削除されました。代わりに@Simpleを使います。org.apache.camel.InvokeOnHeader/org.apache.camel.InvokeOnHeaders→org.apache.camel.spi.InvokeOnHeader/org.apache.camel.spi.InvokeOnHeaders
その他の変更
その他、細かな修正を列挙します。(まだ未分類な変更項目が多いので、後で別のセクションに振り分けるかもしれません。)
breadcrumbの使用はデフォルトで
trueからfalseに変更されました。CamelContextがまだ起動していない段階で、ProducerTemplateやConsumerTemplateを使おうとすると失敗するようになりました。org.apache.camel.implパッケージにあったクラスの大部分は、camel-baseのorg.apache.camel.impl.engineパッケージに移されました。org.apache.camel.util.jndi.JNDIContext(camel-core) →org.apache.camel.support.jndi.JNDIContext(camel-support)org.apache.camel.ThreadPoolRejectedPolicy→org.apache.camel.util.concurrent.ThreadPoolRejectedPolicyorg.apache.camel.processor.validation.PredicateValidationException→org.apache.camel.support.processor.validation.PredicateValidationExceptionorg.apache.camel.util.toolbox.AggregationStrategies→org.apache.camel.builder.AggregationStrategiesorg.apache.camel.processor.aggregate.AggregationStrategy→org.apache.camel.AggregationStrategyorg.apache.camel.management.JmxSystemPropertyKeys→org.apache.camel.api.management.JmxSystemPropertyKeysorg.apache.camel.builder.xml.XPathBuilder→org.apache.camel.language.xpath.XPathBuilder(camel-xpath)org.apache.camel.builder.xml.InvalidXPathExpression→org.apache.camel.language.xpath.InvalidXPathException(camel-xpath)org.apache.camel.converter.stream.OutputStreamBuilder→org.apache.camel.support.builder.OutputStreamBuildercamel-coreのAPI全般にわたって次のtypoを直しました:
chiper→cipherReloadStrategySupport、FileWatcherReloadStrategyクラスは削除されました。MessageHistoryFactoryインタフェースにメッセージをフィルタまたはコピーするオプションが追加され、APIに細かな変更がありました。TypeConverterAwareインタフェースは削除されました。代わりに、型コンバータメソッドへのパラメータとしてExchangeを使います。Component、DataFormatインタフェースは、Serviceインタフェースを継承するようになりました。コンポーネントやデータフォーマットにもそれらのライフサイクルを管理するサービスコントラクトがあるためです。デフォルトのベースクラスは既にそれらのインタフェースを実装しています。コンポーネント共通の
resolvePropertyPlaceholdersオプションは削除されました。プロパティプレースホルダーの機能はCamel Main、Camel Spring Boot等で既にサポートされています。
EIP
XML DSLの<setHeader>、<setProperty>
<setHeader>のheaderName属性、<setProperty>のpropertyName属性は、単にnameに名前変更しました。
Camel 2.x:
<setHeader headerName="foo"><simple>Hello ${body}</simple></setHeader>
Camel 3.0:
<setHeader name="foo"><simple>Hello ${body}</simple></setHeader>
XML DSLの<aggregate>
Aggregate EIPで、相関サイズ/タイムアウト(correlation size/timeout)を表現する条件式(expression)のタグ名が変更されました。XML上の名前衝突を避けるための措置です。
Camel 2.x:
<completionSize> <header>mySize</header> </completionSize>
Camel 3.0:
<completionSizeExpression> <header>mySize</header> </completionSizeExpression>
<completionTimeout>も同様に<completionTimeoutExpression>となります。
Hystrix EIP
元々あったHystrix EIPは、より一般的なCircuit Breaker EIPに変更され、他の実装をプラグインできるようになりました。
Java DSL、XML DSLでそれぞれ以下のように書き換える必要があります。
.hysterix()→.circuitBreaker()<hystrix>→<circuitBreaker>
テスト
camel-test
camel-testを使っていて、これまでテスト用のBeanを登録するためにcreateRegistry()メソッドをオーバーライドしてJndiRegistryクラスをインスタンス生成していた場合、このテクニックはもう必要なくなりました。代わりに、CamelContextからRegistry APIを取得してbind()メソッドを使うのが推奨の方法になります。
context.getRegistry().bind("myId", myBean);
adviceWith
adviceWithを使ったテストは以下のように書き換える必要があります。
Camel 2.x:
context.getRouteDefinition("start").adviceWith(camelContext, new AdviceWithRouteBuilder() { ... }
Camel 3.0:
ModelCamelContext mcc = camelContext.adapt(ModelCamelContext.class); RouteReifier.adviceWith(mcc.getRouteDefinition("start"), mcc, new AdviceWithRouteBuilder() { ... }
AdviceWithRouteBuilderとラムダを使うともっと簡単に書けます。
AdviceWithRouteBuilder.adviceWith(context, "myRoute", a -> { a.replaceFromWith("direct:start"); }
管理/監視
トレーシング
Camelルーティングの詳細なログを出力するTracer機能の実装が、書き換えられました。新しいTracerでは、ログは org.apache.camel.Tracingロガー名で出力されます。
JMXでは、 BacklogTracerはデフォルトで無効になりました。有効にするには、CamelContextにbacklogTracing=trueをセットします。
JMXイベント
org.apache.camel.management.eventパッケージにあったすべてのイベントクラスは、org.apache.camel.spi.CamelEventクラス内にサブクラスとして定義されるようになりました。例えば、CamelContextの開始イベントはCamelEvent.CamelContextStartedEventになります。
EIP、コンポーネント等の参照用JMX APIの削除
EIPやコンポーネント、エンドポイント等を検索し、そのメタ情報を得るためのJMX APIは削除されました。これらのAPIはアプリケーション実行時にはあまり意味がなく、同じ情報は開発時にはcamel-catalogから得られるためです。関連するCamelのKarafコマンドも同様に削除されました。
カスタムコンポーネント/言語
カスタムコンポーネント
カスタムコンポーネントは、今後はcamel-coreではなくcamel-supportのみに依存するように実装すべきです。
DefaultComponent、DefaultEndpointなど、camel-coreにあったカスタムコンポーネントの開発に必要なクラスは、org.apache.camel.implパッケージのからcamel-supportのorg.apache.camel.supportパッケージに移されました。
同様に、camel-coreのorg.apache.camel.util.componentパッケージにあった全てのクラスもcamel-supportのorg.apache.camel.support.componentパッケージに移されました。
カスタム言語
@LaunguageAnnotationアノテーションは、org.apache.camel.languageパッケージからorg.apache.camel.support.languageパッケージへ移されました。
言語
Simple言語からのOUT Messageの削除
OUT Messageのコンセプトが廃止されたのに伴い、Simple言語からも${out.body}といった用法が削除されました。
Simple言語の開始/終了トークン
これまでSimple言語の開始/終了を表すトークンを変更できたのですが、誰も使っていなかったので最適化のために廃止されました。今後は、デフォルトの${xxx}または$simple{xxx}のみが使用可能です。
Simple言語のproperty
Camel 2.xでSimple言語のpropertyはdeprecatedになっていましたが、Camel 3では削除されました。代わりにexchangePropertyを使います。
Terser言語 → HL7 Terser言語
Terser言語は、terser → hl7terserに名前変更されました。
アノテーション
言語関連のアノテーションの変更は以下のとおりです。
org.apache.camel.language.XPath→org.apache.camel.language.xpath.XPath(camel-xpath)org.apache.camel.language.Bean→org.apache.camel.language.bean.Bean(camel-bean)org.apache.camel.language.Simple→org.apache.camel.language.simple.Simpleorg.apache.camel.language.SpEL→org.apache.camel.language.spel.SpEL(camel-spring)
Camel Mavenプラグイン
camel-maven-pluginが2つに分割されました。
- camel-maven-plugin
- camel-report-maven-plugin
1つめのcamel-maven-pluginがrunゴールを持っていて、Camelアプリケーションを素早くスタンドアロン実行できるためのものです。
2つめのcamel-report-maven-pluginはvaludate、route-coverageゴールを持っていて、Camelプロジェクトのバリデーションやカバレッジのレポートを出力するためのものです。
既知の問題
内部のルーティングエンジンをリファクタリングした影響で、MDCロギングとbreadcrumb IDの扱いに一定の状況下で問題が見つかっています。この問題は、camel-zipkinコンポーネントにも影響しています。
最後に
本家のガイドは構成がカオスなので、意味のある構成を見つけ出して再構成するのに一番苦労しました。(その分、本家ガイドよりもこちらの方が参照しやすくなっているはず!)もし気が向いたら、本家ガイドにもこの記事の構成を反映させるかもしれません。
次回は、マイグレーションガイドのコンポーネント編を書く予定です。