From 7d18fee5c5e87854206f53a3be60ceaf69bdf515 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=AB=E6=81=92?= Date: Thu, 10 Oct 2019 14:58:31 +0800 Subject: [PATCH] ark samples --- .gitignore | 9 + Formatter.xml | 278 ++++++++++++++++++ HEADER | 14 + LICENSE | 201 +++++++++++++ README.md | 18 ++ README_EN.md | 25 ++ check_format.sh | 12 + pom.xml | 143 +++++++++ sample-ark-plugin/README.md | 109 +++++++ sample-ark-plugin/README_EN.md | 116 ++++++++ sample-ark-plugin/common/pom.xml | 15 + .../ark/sample/SampleClassNotExported.java | 29 ++ .../sample/common/SampleClassExported.java | 30 ++ .../main/resources/Sample_Resource_Exported | 0 .../resources/Sample_Resource_Not_Exported | 0 sample-ark-plugin/plugin/pom.xml | 80 +++++ .../activator/SamplePluginActivator.java | 42 +++ .../sample/facade/SamplePluginService.java | 29 ++ .../sample/impl/SamplePluginServiceImpl.java | 32 ++ sample-ark-plugin/pom.xml | 23 ++ sample-ark-springboot/README.md | 170 +++++++++++ sample-ark-springboot/README_EN.md | 206 +++++++++++++ .../conf/ark/bootstrap.properties | 1 + sample-ark-springboot/pom.xml | 86 ++++++ .../sofa/ark/sample/facade/SampleService.java | 31 ++ .../ark/sample/impl/SampleServiceImpl.java | 29 ++ .../SpringbootDemoApplication.java | 36 +++ .../resources/META-INF/spring/service.xml | 8 + .../src/main/resources/application.properties | 0 .../sofa/ark/sample/IntegrationTest.java | 43 +++ .../com/alipay/sofa/ark/sample/JUnitTest.java | 38 +++ .../alipay/sofa/ark/sample/TestNGTest.java | 42 +++ 32 files changed, 1895 insertions(+) create mode 100644 .gitignore create mode 100644 Formatter.xml create mode 100644 HEADER create mode 100644 LICENSE create mode 100644 README.md create mode 100644 README_EN.md create mode 100644 check_format.sh create mode 100644 pom.xml create mode 100644 sample-ark-plugin/README.md create mode 100644 sample-ark-plugin/README_EN.md create mode 100644 sample-ark-plugin/common/pom.xml create mode 100644 sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/SampleClassNotExported.java create mode 100644 sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/common/SampleClassExported.java create mode 100644 sample-ark-plugin/common/src/main/resources/Sample_Resource_Exported create mode 100644 sample-ark-plugin/common/src/main/resources/Sample_Resource_Not_Exported create mode 100644 sample-ark-plugin/plugin/pom.xml create mode 100644 sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/activator/SamplePluginActivator.java create mode 100644 sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/facade/SamplePluginService.java create mode 100644 sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/impl/SamplePluginServiceImpl.java create mode 100644 sample-ark-plugin/pom.xml create mode 100644 sample-ark-springboot/README.md create mode 100644 sample-ark-springboot/README_EN.md create mode 100644 sample-ark-springboot/conf/ark/bootstrap.properties create mode 100644 sample-ark-springboot/pom.xml create mode 100644 sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/facade/SampleService.java create mode 100644 sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/impl/SampleServiceImpl.java create mode 100644 sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/springbootdemo/SpringbootDemoApplication.java create mode 100644 sample-ark-springboot/src/main/resources/META-INF/spring/service.xml create mode 100644 sample-ark-springboot/src/main/resources/application.properties create mode 100644 sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/IntegrationTest.java create mode 100644 sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/JUnitTest.java create mode 100644 sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/TestNGTest.java diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..96a49b2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,9 @@ +target/ +*.iml +.idea/ +pom.xml.bak +.DS_Store +.settings +.classpath +*.log +logs/ \ No newline at end of file diff --git a/Formatter.xml b/Formatter.xml new file mode 100644 index 0000000..1dc9054 --- /dev/null +++ b/Formatter.xml @@ -0,0 +1,278 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/HEADER b/HEADER new file mode 100644 index 0000000..1745cfe --- /dev/null +++ b/HEADER @@ -0,0 +1,14 @@ +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You 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. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..b0ff390 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2018 Ant Financial Services Group Co., Ltd. + + 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. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..b70742f --- /dev/null +++ b/README.md @@ -0,0 +1,18 @@ +# 工程用例 + +SOFAArk 提供了两个样例工程来演示 `Ark Plugin` 和 `Ark 包` 的使用；样例工程目录组织如下： + +``` +. +│ +├── sample-ark-plugin +│ +└── sample-springboot-ark + +``` + +## sample-ark-plugin +该工程演示如何使用官方提供的 `Maven` 插件 `sofa-ark-plugin-maven-plugin` 来构建一个标准的 `Ark Plugin`，详细可参考 [README](./sample-ark-plugin/README.md) + +## sample-springboot-ark +该工程演示如何使用官方提供的 `Maven` 插件 `sofa-ark-maven-plugin` 将一个普通的 Spring Boot 应用打包成一个 `Ark 包`；需要注意的是，因为该工程依赖另一个用例工程 [`sample-ark-plugin`](./sample-ark-plugin/README.md) 打包出来的 `Ark Plugin`, 请务必提前安装该 `Ark Plugin` 至本地 maven 仓库；详细请参考 [README](./sample-springboot-ark/README.md) diff --git a/README_EN.md b/README_EN.md new file mode 100644 index 0000000..a18c318 --- /dev/null +++ b/README_EN.md @@ -0,0 +1,25 @@ +# SOFAArk Samples + +There are two samples totally. The sofa-ark-samples directory shows as following: + +``` +. +│ +├── sample-ark-plugin +│ +└── sample-springboot-ark + +``` + +## sample-ark-plugin +This sample project shows how to build an ark-plugin. It shows the +usage of the maven plugin `sofa-ark-plugin-maven-plugin`. Details +please refer to [README](./sample-ark-plugin/README_EN.md) + +## sample-springboot-ark +This sample project shows how to build an `executable-ark-jar` based +on a springboot project. It shows the usage of the maven plugin +`sofa-ark-maven-plugin`. As it depends on the ark-plugin generated by +the project of [`sample-ark-plugin`](./sample-ark-plugin/README_EN.md), please +ensure the sample-ark-plugin installed in your local maven repository +before run this project. Details please refer to [README](./sample-springboot-ark/README_EN.md) diff --git a/check_format.sh b/check_format.sh new file mode 100644 index 0000000..3ec7137 --- /dev/null +++ b/check_format.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +BASEDIR=$(dirname $0) + +cd ${BASEDIR} + +# make sure git has no un commit files +if [ -n "$(git status --untracked-files=no --porcelain)" ]; then + echo "Please commit your change before run this shell, un commit files:" + git status --untracked-files=no --porcelain + exit -1 +fi \ No newline at end of file diff --git a/pom.xml b/pom.xml new file mode 100644 index 0000000..be64494 --- /dev/null +++ b/pom.xml @@ -0,0 +1,143 @@ + + + 4.0.0 + + com.alipay.sofa + sofa-ark-samples + pom + 1.0-SNAPSHOT + + sample-ark-plugin + sample-ark-springboot + + + + 2.1.0.RELEASE + 0.6.0 + UTF-8 + + + + + + + + + com.alipay.sofa + sofa-ark-spi + ${ark.version} + + + + com.alipay.sofa + sofa-ark-springboot-starter + ${ark.version} + + + + com.alipay.sofa + web-ark-plugin + ${ark.version} + + + + + com.alipay.sofa + sample-ark-plugin + ${project.version} + + + + com.alipay.sofa + sample-ark-plugin-common + ${project.version} + + + + + org.springframework.boot + spring-boot-dependencies + ${spring.boot.version} + pom + import + + + + + + + + default + + true + + + + + true + + ark-snapshot + https://oss.sonatype.org/content/repositories/snapshots + + + + + + true + + ark-snapshot + https://oss.sonatype.org/content/repositories/snapshots + + + + + + + + + com.mycila + license-maven-plugin + + + generate-sources + + remove + format + + + + + true +
${user.dir}/HEADER
+ + **/src/main/java/** + **/src/test/java/** + + true + + SLASHSTAR_STYLE + + + + + + com.googlecode.maven-java-formatter-plugin + maven-java-formatter-plugin + + + + format + + + + + ${user.dir}/Formatter.xml + ${project.encoding} + + + + + + \ No newline at end of file diff --git a/sample-ark-plugin/README.md b/sample-ark-plugin/README.md new file mode 100644 index 0000000..ae21973 --- /dev/null +++ b/sample-ark-plugin/README.md @@ -0,0 +1,109 @@ +## 简介 +该样例工程演示了如何借助 `maven` 插件将一个普通的 Java 工程打包成标准格式规范的 `Ark Plugin` + +## 背景 +现实开发中，常常会遇到依赖包冲突的情况；假设我们开发了一个类库 `sample-lib` , 业务应用在引入使用时，可能存在跟已有的依赖发生冲突的情况；通常这个时候，我们会希望自己的类库能够和业务其他依赖进行隔离，互不协商双方依赖包版本。 `Ark Plugin` 正是基于这种需求背景下的实践产物； `Ark Plugin` 运行在 `Ark Container` 之上，由容器负责加载启动，任何一个 `Ark Plugin` 由独立的 ClassLoader 加载，从而做到相互隔离。`Ark Plugin` 存在四个概念： +* 导入类：插件启动时，优先委托给导出该类的插件负责加载，如果加载不到，才会尝试从本插件内部加载； + +* 导出类：其他插件如果导入了该类，优先从本插件加载； + +* 导入资源：插件在查找资源时，优先委托给导出该资源的插件负责加载，如果加载不到，才会尝试从本插件内部加载； + +* 导出资源：其他插件如果导入了该资源，优先从本插件加载； + + +**[详细请参考插件规范](https://alipay.github.io/sofastack.github.io/docs/ark-plugin.html#插件规范)** + + +## 工具 +官方提供了 `Maven` 插件 - `sofa-ark-plugin-maven-plugin` ，只需要简单的配置项，即可将普通的 Java 工程打包成标准格式规范的 `Ark Plugin` ，插件坐标为: + +```xml + + com.alipay.sofa + sofa-ark-plugin-maven-plugin + 1.0.0-SNAPSHOT + +``` + +**[详细请参考插件配置文档](https://alipay.github.io/sofastack.github.io/docs/ark-plugin.html#完整配置模板)** + +## 入门 +基于该用例工程，我们一步步描述如何构建一个 `Ark Plugin` + +### 创建标准 Maven 工程 +该用例工程是一个标准的 Maven 工程，一共包含两个模块： +* common 模块：包含了插件导出类 + +* plugin 模块：包含了 `com.alipay.sofa.ark.spi.service.PluginActivator` 接口实现类和一个插件服务类，插件打包工具 `sofa-ark-plugin-maven-plugin` 即配置在该模块的 `pom.xml` 中； + +### 配置打包插件 +在 plugin 模块的 `pom.xml` 中按如下配置打包插件： + +```xml + + + + com.alipay.sofa + sofa-ark-plugin-maven-plugin + ${project.version} + + + default-cli + + ark-plugin + + + + + + com.alipay.sofa.ark.sample.activator.SamplePluginActivator + + + + + + com.alipay.sofa.ark.sample.common + + + + + com.alipay.sofa.ark.sample.facade.SamplePluginService + + + + + ../target + + + + + + + + +``` + +在用例工程中，我们只配置了一部分配置项，这已经足够生成一个可用的 `Ark Plugin`，各配置项含义如下： +* activator: Ark 容器启动插件的入口类，最多只能配置一个；通常来说，在插件的 `activator` 会执行一些初始化操作，比如发布插件服务；在本样例工程中，即发布了插件服务。 + +* 导出包：包级别的导出类配置，插件中所有以导出包名为前缀的类，包括插件的三方依赖包，都会被导出； + +* 导出类：精确类名的导出类配置，导出具体的类； + +* outputDirectory： `mvn package` 打包后，输出的 ark plugin 文件存放目录； + +需要指出的是，在用例工程中，我们只导出了工程创建的类；实际在使用时，也可以把工程依赖的三方包也导出去。 + +### 打包、安装、发布、引入 +和普通的工程操作类似，使用 `mvn package` , `mvn install` , `mvn deploy` 即可完成插件包的安装和发布；需要注意的是，默认发布的 `Ark Plugin` 其 Maven 坐标会增加 `classifier=ark-plugin` ；例如在该样例工程中，如果需要使用该 ark plugin，必须如下配置依赖： + +```xml + + com.alipay.sofa + sample-ark-plugin + ark-plugin + 1.0.0-SNAPSHOT + +``` + diff --git a/sample-ark-plugin/README_EN.md b/sample-ark-plugin/README_EN.md new file mode 100644 index 0000000..f11426c --- /dev/null +++ b/sample-ark-plugin/README_EN.md @@ -0,0 +1,116 @@ +# How to build an ark-plugin +## Introduction +This sample project shows how to build an `ark-plugin` +based on a normal java project with the tool of `sofa-ark-plugin-maven-plugin` + +## Background +Assuming such a situation, you develop a lib, however, some dependency +conflict occurs when imported to the consumer project. To avoid this +problem, you would hope to isolate your lib with the consumer project. +`Ark-Plugin` employs the mechanism of classloader isolation. It runs on +`Ark-Container`, any `ark-plugin` would be loaded by an independent classloader. + +There are four concepts about `ark-plugin`: + ++ Exported Class: classes contained in `ark-plugin`，loaded by ark-plugin-classloader, +but can be resolved by other `ark-plugin` (if it imports) or consumer project. + ++ Imported Class: if a `ark-plugin` configures this item, it prefers to resolve class +from other `ark-plugin` which exports corresponding class. + ++ Exported Resource: resources contained in `ark-plugin`，loaded by ark-plugin-classloader, +but can be found by other `ark-plugin` (if it imports) or consumer project. + ++ Imported Resource: if a `ark-plugin` configures this item, it prefers to find resource +from other `ark-plugin` which exports corresponding resource. + +## Tools +The `Maven plugin` of `sofa-ark-plugin-maven-plugin` is provided to build a +standard `ark-plugin`, and just needs some simple configurations. Details please +refer to [doc](https://www.sofastack.tech/sofa-boot/docs/sofa-ark-ark-plugin?lang=en) + +## Step by Step +### Create a Maven Project +This sample project is a standard maven project, it contains two modules: + ++ common module: contains some classes exported. ++ plugin module: contains `plugin activator` and `plugin service`. + +One thing should be pointed out that dependencies imported by project also can be exported. + +### Configure sofa-ark-plugin-maven-plugin +The maven plugin of `sofa-ark-plugin-maven-plugin` is configured in the `pom.xml` of plugin +module, it configures as follows: + +``` java + + + default-cli + + + + ark-plugin + + + + + + com.alipay.sofa.ark.sample.activator.SamplePluginActivator + + + + + + com.alipay.sofa.ark.sample.common + + + + + com.alipay.sofa.ark.sample.facade.SamplePluginService + + + + + Sample_Resource_Exported + + + + + + ../target + + + + +``` +The configured items are explained as follows: ++ `activator`: startup entry of `ark-plugin` when running on `ark-container`; generally speaking, +`ark-plugin service` would be published in the entry, similar to what [`SamplePluginActivator`](./plugin/src/main/java/com/alipay/sofa/ark/sample/activator/SamplePluginActivator.java) does. ++ `exported pacakges`: the package of `com.alipay.sofa.ark.sample.common` is exported, any class +whose name start with `com.alipay.sofa.ark.sample.common` would be exported. ++ `exported classes`: the single class `com.alipay.sofa.ark.sample.facade.SamplePluginService` is +exported. ++ `exported resource`: the resource `Sample_Resource_Exported` is exported. ++ `outputDirectory`: specify destination where ark-plugin would be saved when execute +the maven command of `mvn package` + +### package/install/deploy ++ package: execute `mvn package`, the ark-plugin file generated would be saved to the configured +value of `outputDirectory`. ++ install: execute `mvn install`, the ark-plugin would be installed local maven repository, its maven +location would bring a classifier of `ark-plugin`. ++ deploy: execute `mvn deploy`, just as usual practice. + +### import +As what mentioned above, the maven location of ark-plugin would bring with a classifier +of `ark-plugin`, so, to import the ark-plugin generated by this sample project, you +should add the following dependency in your consumer project: + +``` + + com.alipay.sofa + sample-ark-plugin + ark-plugin + 1.0.0-SNAPSHOT + +``` diff --git a/sample-ark-plugin/common/pom.xml b/sample-ark-plugin/common/pom.xml new file mode 100644 index 0000000..e45024c --- /dev/null +++ b/sample-ark-plugin/common/pom.xml @@ -0,0 +1,15 @@ + + + + sample-ark-plugin + com.alipay.sofa + 1.0-SNAPSHOT + + 4.0.0 + + sample-ark-plugin-common + + + \ No newline at end of file diff --git a/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/SampleClassNotExported.java b/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/SampleClassNotExported.java new file mode 100644 index 0000000..db09e00 --- /dev/null +++ b/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/SampleClassNotExported.java @@ -0,0 +1,29 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample; + +/** + * @author: guolei.sgl (guolei.sgl@antfin.com) 2019/10/10 2:30 PM + * @since: + **/ +public class SampleClassNotExported { + public static void hello() { + System.out.println("Hello, I'm a sample class 'NOT' exported by ark-plugin."); + System.out.println(String.format("I'm loaded by %s", + SampleClassNotExported.class.getClassLoader())); + } +} diff --git a/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/common/SampleClassExported.java b/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/common/SampleClassExported.java new file mode 100644 index 0000000..db7acf2 --- /dev/null +++ b/sample-ark-plugin/common/src/main/java/com/alipay/sofa/ark/sample/common/SampleClassExported.java @@ -0,0 +1,30 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.common; + +/** + * @author: guolei.sgl (guolei.sgl@antfin.com) 2019/10/10 2:31 PM + * @since: + **/ +public class SampleClassExported { + + public static void hello() { + System.out.println("Hello, I'm a sample class exported by ark-plugin."); + System.out.println(String.format("I'm loaded by %s", + SampleClassExported.class.getClassLoader())); + } +} diff --git a/sample-ark-plugin/common/src/main/resources/Sample_Resource_Exported b/sample-ark-plugin/common/src/main/resources/Sample_Resource_Exported new file mode 100644 index 0000000..e69de29 diff --git a/sample-ark-plugin/common/src/main/resources/Sample_Resource_Not_Exported b/sample-ark-plugin/common/src/main/resources/Sample_Resource_Not_Exported new file mode 100644 index 0000000..e69de29 diff --git a/sample-ark-plugin/plugin/pom.xml b/sample-ark-plugin/plugin/pom.xml new file mode 100644 index 0000000..61b7213 --- /dev/null +++ b/sample-ark-plugin/plugin/pom.xml @@ -0,0 +1,80 @@ + + + + sample-ark-plugin + com.alipay.sofa + 1.0-SNAPSHOT + + 4.0.0 + + sample-ark-plugin-plugin + + + + + com.alipay.sofa + sample-ark-plugin-common + ${project.version} + + + + com.alipay.sofa + sofa-ark-spi + 0.6.0 + + + + + + + com.alipay.sofa + sofa-ark-plugin-maven-plugin + 0.6.0 + + + default-cli + + ark-plugin + + + + + + com.alipay.sofa.ark.sample.activator.SamplePluginActivator + + + + + + com.alipay.sofa.ark.sample.common + + + + + com.alipay.sofa.ark.sample.facade.SamplePluginService + + + + + Sample_Resource_Exported + + + + + ../target + + + + com.alipay.sofa:sample-ark-plugin-common:1.0-SNAPSHOT + + + + + + + + + + \ No newline at end of file diff --git a/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/activator/SamplePluginActivator.java b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/activator/SamplePluginActivator.java new file mode 100644 index 0000000..d471384 --- /dev/null +++ b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/activator/SamplePluginActivator.java @@ -0,0 +1,42 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.activator; + +import com.alipay.sofa.ark.exception.ArkRuntimeException; +import com.alipay.sofa.ark.sample.facade.SamplePluginService; +import com.alipay.sofa.ark.sample.impl.SamplePluginServiceImpl; +import com.alipay.sofa.ark.spi.model.PluginContext; +import com.alipay.sofa.ark.spi.service.PluginActivator; + +/** + * A sample ark-plugin activator + * + * @author qilong.zql + * @since 0.1.0 + */ +public class SamplePluginActivator implements PluginActivator { + + public void start(PluginContext context) throws ArkRuntimeException { + System.out.println("starting in sample ark plugin activator"); + context.publishService(SamplePluginService.class, new SamplePluginServiceImpl()); + } + + public void stop(PluginContext context) throws ArkRuntimeException { + System.out.println("stopping in ark plugin activator"); + } + +} \ No newline at end of file diff --git a/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/facade/SamplePluginService.java b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/facade/SamplePluginService.java new file mode 100644 index 0000000..e714281 --- /dev/null +++ b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/facade/SamplePluginService.java @@ -0,0 +1,29 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.facade; + +/** + * A sample plugin service published + * + * @author qilong.zql + * @since 0.1.0 + */ +public interface SamplePluginService { + + String service(); + +} \ No newline at end of file diff --git a/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/impl/SamplePluginServiceImpl.java b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/impl/SamplePluginServiceImpl.java new file mode 100644 index 0000000..87b9afc --- /dev/null +++ b/sample-ark-plugin/plugin/src/main/java/com/alipay/sofa/ark/sample/impl/SamplePluginServiceImpl.java @@ -0,0 +1,32 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.impl; + +import com.alipay.sofa.ark.sample.facade.SamplePluginService; + +/** + * A sample plugin service implementation + * + * @author qilong.zql + * @since 0.1.0 + */ +public class SamplePluginServiceImpl implements SamplePluginService { + @Override + public String service() { + return "I'm a sample plugin service published by ark-plugin"; + } +} \ No newline at end of file diff --git a/sample-ark-plugin/pom.xml b/sample-ark-plugin/pom.xml new file mode 100644 index 0000000..8b52806 --- /dev/null +++ b/sample-ark-plugin/pom.xml @@ -0,0 +1,23 @@ + + + + sofa-ark-samples + com.alipay.sofa + 1.0-SNAPSHOT + + 4.0.0 + + sample-ark-plugin + pom + + + ${user.dir}/.. + + + + common + plugin + + \ No newline at end of file diff --git a/sample-ark-springboot/README.md b/sample-ark-springboot/README.md new file mode 100644 index 0000000..bc6977b --- /dev/null +++ b/sample-ark-springboot/README.md @@ -0,0 +1,170 @@ +## 简介 +该样例工程演示了如何借助 `Maven` 插件将一个 Spring Boot Web 工程打包成标准格式规范的可执行 Ark 包； + +## 工具 +官方提供了 `Maven` 插件 - `sofa-ark-maven-plugin` ，只需要简单的配置项，即可将 Spring Boot Web 工程打包成标准格式规范的可执行 Ark 包，插件坐标为： + +```xml + + com.alipay.sofa + sofa-ark-maven-plugin + ${sofa.ark.version} + +``` + +**[详细请参考插件使用文档](https://alipay.github.io/sofastack.github.io/docs/ark-jar.html)** + + +## 入门 +基于该样例工程，我们一步步描述如何将一个 Spring Boot Web 工程打包成可运行 Ark 包 + +### 创建 SpringBoot Web 工程 +在官网 [https://start.spring.io/](https://start.spring.io/) 下载一个标准的 Spring Boot Web 工程 + +### 配置打包插件 +在工程主 `pom.xml` 中如下配置 `Maven` 插件 `sofa-ark-maven-plugin` : + +```xml + + + + com.alipay.sofa + sofa-ark-maven-plugin + ${sofa.ark.version} + + + default-cli + + + + repackage + + + + + ./target + + + executable-ark + + + + + + +``` + +在该样例工程中，我们只配置了一部分配置项，这已经足够生成一个可用的可执行 `Ark` 包，各配置项含义如下： +* outputDirectory: `mvn package` 打包后，输出的 `Ark` 包文件存放目录； + +* arkClassifier: 指定发布的 `Ark` 包其 `Maven` 坐标包含的 `classifier` 值，默认为空； + +**关于 arkClassifier 配置项需要特别注意下，默认值为空；如果不指定 classifier ，上传到仓库的 Jar 包其实是一个可运行的 Ark 包；如果需要和普通的打包加以区分，需要配置该项值。** + +### 打包、安装、发布 +和普通的工程操作类似，使用 `mvn package` , `mvn install` , `mvn deploy` 即可完成插件包的安装和发布；以 `mvn package` 命令为例，可以看到有三个文件生成： ++ sofa-ark-sample-springboot-ark-1.0.0-SNAPSHOT.jar +> 因为设置了 arkClassifier, 因此这个文件不是 Ark 包，而是普通的模块 Jar 包 + ++ sofa-ark-sample-springboot-ark-1.0.0-SNAPSHOT-ark-biz.jar +> 因为没有设置 bizClassifier, 因此使用默认的 ark-biz 当成 bizClassifier，这个包就是 Biz 包。值得一提的是，因为我们没有配置 attach = true, 所以只是生成了 Biz 包，但是并不会安装到本地仓库或者发布到远程仓库。 + ++ sofa-ark-sample-springboot-ark-1.0.0-SNAPSHOT-executable-ark.jar +> 因为设置了 arkClassifier=executable-ark，可以看到该包就是插件 sofa-ark-maven-plugin 生成的可执行 Ark 包，可以通过 java -jar 启动。 + +### 运行 +为了方便在 Spring Boot/SOFABoot 工程中方便的集成 SOFAArk, 只需要在应用中引入如下依赖即可： + +```xml + + com.alipay.sofa + sofa-ark-springboot-starter + ${sofa.ark.version} + +``` + +值得一提的是，对于普通的 Java 应用，不仅需要添加如下依赖： + +```xml + + com.alipay.sofa + sofa-ark-support-starter + ${sofa.ark.version} + +``` + +还需要在工程 `main` 方法最开始处，执行容器启动，如下： + +```java +public class Application{ + + public static void main(String[] args) { + SofaArkBootstrap.launch(args); + ... + } + +} +``` + +### 运行测试用例 +SOFAArk 提供了 `org.junit.runner.Runner` 的两个实现类，`ArkJUnit4Runner` 和 `ArkBootRunner`，分别用于集成 JUnit4 测试框架和 Spring Test；对于 TestNG 测试框架，提供了注解 `@TestNGOnArk`，对于任何 TestNG 测试用例，只有打有 `@TestNGOnArk` 的测试用例才会跑在 Ark Container 之上，否则普通用例一样。 + +#### ArkJUnit4Runner +`ArkJUnit4Runner` 类似 `JUnit4`，使用注解 `ArkJUnit4Runner`，即可在 SOFAArk 容器之上运行普通的 JUnit4 测试用例；示范代码如下： + +```java +@RunWith(ArkJUnit4Runner.class) +public class UnitTest { + + @Test + public void test() { + Assert.assertTrue(true); + } + +} +``` + +`ArkJUnit4Runner` 和 `JUnit4` 使用基本完全一致，`JUnit4` 测试框架的其他特性都能够完全兼容， + +#### ArkBootRunner +`ArkBootRunner` 类似 `SpringRunner`，参考[文档](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-testing.html)学习 `SpringRunner` 的用法；为了能够在 SOFAArk 容器之上运行 Spring Boot 测试用例，只需要简单使用 `@RunWith(ArkBootRunner.class)` 替代 `@RunWith(SpringRunner.class)` 即可；示范代码如下： + +```java +@RunWith(ArkBootRunner.class) +@SpringBootTest(classes = SpringbootDemoApplication.class) +public class IntegrationTest { + + @Autowired + private SampleService sampleService; + + @Test + public void test() { + Assert.assertTrue("A Sample Service".equals(sampleService.service())); + } + +} +``` + +`ArkBootRunner` 和 `SpringRunner` 使用基本完全一致； + +#### TestNGOnArk +注解 `@TestNGOnArk` 是 SOFAArk 提供给开发者用于标记哪些 TestNG 用例跑在 SOFAArk 之上，哪些只是普通的运行。例如： + +```java +@TestNGOnArk +public class TestNGTest { + + public static final String TEST_CLASSLOADER = "com.alipay.sofa.ark.container.test.TestClassLoader"; + + @Test + public void test() { + ClassLoader tccl = Thread.currentThread().getContextClassLoader(); + ClassLoader loader = this.getClass().getClassLoader(); + Assert.assertTrue(tccl.equals(loader)); + Assert.assertTrue(tccl.getClass().getCanonicalName().equals(TEST_CLASSLOADER)); + } + +} +``` + +上述用例打了 `@TestNGTest`，因此在执行该测试用例时，会先启动 Ark Container。 diff --git a/sample-ark-springboot/README_EN.md b/sample-ark-springboot/README_EN.md new file mode 100644 index 0000000..ea4f8fe --- /dev/null +++ b/sample-ark-springboot/README_EN.md @@ -0,0 +1,206 @@ +# How to build an executable-ark-jar +## Introduction +This sample project shows how to build an executable-ark-jar based on +a springboot project with the tool of `sofa-ark-maven-plugin`. + +## Preparation +As this project depends on the ark-plugin generated by the project of +[`sample-ark-plugin`](../sample-ark-plugin/README_EN.md), please ensure the +sample sample-ark-plugin installed in your local maven repository before run +this project. + +## Tools +The `Maven plugin` of `sofa-ark-maven-plugin` is provided to build a standard +`executable-ark-jar`, and just needs some simple configurations, Details please +refer to [doc](https://alipay.github.io/sofastack.github.io/docs/build-ark.html) + +## Step By Step +### Create a Spring Boot Web Project +Visit [`https://start.spring.io/`](https://start.spring.io/) and generate a standard springboot-web project + +### Import sample-ark-plugin +Add a dependency in main `pom.xml` as follows: +``` + + com.alipay.sofa + sample-ark-plugin + ark-plugin + 1.0.0-SNAPSHOT + +``` + +### Configure sofa-ark-maven-plugin +The maven plugin of sofa-ark-plugin-maven-plugin is configured in main pom.xml, it configures as follows: + +``` +build> + + + com.alipay.sofa + sofa-ark-maven-plugin + + + default-cli + + + + repackage + + + + + ./target + + + executable-ark + + + + com.alipay.sofa.SampleClass1 + com.alipay.sofa.SampleClass2 + + + + + com.alipay.sofa + org.springframework + + + + + META-INF/spring/test1.xml + META-INF/spring/test2.xml + + + + + + + +``` + +The configured items are explained as follows: ++ `outputDirectory`: specify destination where `executable-ark-jar` will be saved, +default saved to ${project.build.directory}. ++ `arkClassifier`: specify classifier in the maven location of `executable-ark-jar`, default none. ++ `denyImportClasses`: all class exported by ark plugin would be resolved by ark biz in default, if configure denyImportClasses, then it would prefer to load them by ark biz itself. ++ `denyImportPackages`: corresponding to denyImportClasses, denyImportPackages is package-level. ++ `denyImportResources`: denyImportResources can prevent resource exported by ark plugin with accurate name to be resolved by ark biz. + +## package/install/deploy ++ package: execute `mvn package`, the `executable-ark-jar` file generated would be saved to the configured +value of `outputDirectory`. ++ install: execute `mvn install`, the `executable-ark-jar` would be installed local maven repository. ++ deploy: execute `mvn deploy`, just as usual practice. + +## run in command line +we support command such as `java -jar executable-ark.jar` to startup application, similar to what this sample +project does, execute command line: `java -jar target/sofa-ark-sample-springboot-ark-1.0.0-SNAPSHOT-executable-ark.jar` +to startup this demo. + +## run in IDE +if you want to run application in IDE, some additional dependency need to be imported. + ++ Spring Boot Project +you should add dependency as follows: + +``` + + com.alipay.sofa + sofa-ark-springboot-starter + 1.0.0-SNAPSHOT + +``` ++ Common Java Project +you should add dependency as follows: + +``` + + com.alipay.sofa + sofa-ark-support-starter + 1.0.0-SNAPSHOT + +``` + +besides, you should add `SofaArkBootstrap.launch(args);` in `Main` Class of Application, do as follows: + +```java +public class Application{ + + public static void main(String[] args) { + SofaArkBootstrap.launch(args); + } + +} +``` + +## How to run test cases +Considering to integrate with [JUnit4 FrameWork](https://github.com/junit-team/junit4/wiki/getting-started) and [SpringBoot Test](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-testing.html), SOFAArk provides two implementations of runners for using with `@RunWith` include: + ++ `ArkJUnit4Runner` + ++ `ArkBootRunner` + +However, integration with [TestNG Framework](https://github.com/cbeust/testng/wiki) is different. SOFAArk provides an annotation `@TestNGOnArk`, when a test class is annotated with this annotation, it represents that it would be executed on ark container . Now, we would show how to run test case in `JUnit4 FrameWork`, `TestNG FrameWork` and `Spring Boot`; + +### Run test case in JUnit4 FrameWork +`ArkJUnit4Runner` is similar to `JUnit4`, the latter is the default implementation of runner in JUnit4 Framework; In other words, if you want run normal junit4 test case in SOFAArk container, you should use `@RunWith(ArkJUnit4Runner.class)` instead of the default one. Code as what the following shows: + +```java +@RunWith(ArkJUnit4Runner.class) +public class UnitTest { + + @Test + public void test() { + Assert.assertTrue(true); + } + +} +``` + +If you want use other features of JUnit4 Framework, such as `@Before`, it's not a problem, just do as before. + +### Run test case in TestNG FrameWork +The annotation `@TestNGOnArk` is used to represent that some test class would be executed on ark container. e.g. + +```java +@TestNGOnArk +public class TestNGTest { + + public static final String TEST_CLASSLOADER = "com.alipay.sofa.ark.container.test.TestClassLoader"; + + @Test + public void test() { + ClassLoader tccl = Thread.currentThread().getContextClassLoader(); + ClassLoader loader = this.getClass().getClassLoader(); + Assert.assertTrue(tccl.equals(loader)); + Assert.assertTrue(tccl.getClass().getCanonicalName().equals(TEST_CLASSLOADER)); + } + +} +``` + +It's very convenient to use it, if you want run a test class on ark container, just annotate it with `@TestNGOnArk`. + +### Run test case in SpringBoot Test +`ArkBootRunner` is similar to `SpringRunner`, you can visit [this site](https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-testing.html) for usage of the latter one. For running SpringBoot test case in SOFAArk container, just use `@RunWith(ArkBootRunner.class)` instead of `@RunWith(SpringRunner.class)`. Code as what the following shows: + +```java +@RunWith(ArkBootRunner.class) +@SpringBootTest(classes = SpringbootDemoApplication.class) +public class IntegrationTest { + + @Autowired + private SampleService sampleService; + + @Test + public void test() { + Assert.assertTrue("A Sample Service".equals(sampleService.service())); + } + +} +``` + +If you want use other features of SpringBoot Test, just do as before. diff --git a/sample-ark-springboot/conf/ark/bootstrap.properties b/sample-ark-springboot/conf/ark/bootstrap.properties new file mode 100644 index 0000000..f7ec555 --- /dev/null +++ b/sample-ark-springboot/conf/ark/bootstrap.properties @@ -0,0 +1 @@ +logging.path=./logs \ No newline at end of file diff --git a/sample-ark-springboot/pom.xml b/sample-ark-springboot/pom.xml new file mode 100644 index 0000000..261f029 --- /dev/null +++ b/sample-ark-springboot/pom.xml @@ -0,0 +1,86 @@ + + + + sofa-ark-samples + com.alipay.sofa + 1.0-SNAPSHOT + + 4.0.0 + + sample-ark-springboot + + + + + org.springframework.boot + spring-boot-starter-web + + + + com.alipay.sofa + web-ark-plugin + + + + com.alipay.sofa + sofa-ark-springboot-starter + + + + + org.springframework.boot + spring-boot-starter-test + test + + + + org.springframework.boot + spring-boot-test + test + + + + + junit + junit + test + + + + + org.testng + testng + 6.14.3 + test + + + + + + + + com.alipay.sofa + sofa-ark-maven-plugin + ${ark.version} + + + + + repackage + + + + + ./target + + + executable-ark + + + + + + + \ No newline at end of file diff --git a/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/facade/SampleService.java b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/facade/SampleService.java new file mode 100644 index 0000000..d3cbfdd --- /dev/null +++ b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/facade/SampleService.java @@ -0,0 +1,31 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.facade; + +/** + * @author qilong.zql + * @since 0.1.0 + */ +public interface SampleService { + + /** + * a simple facade + * @return + */ + String service(); + +} \ No newline at end of file diff --git a/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/impl/SampleServiceImpl.java b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/impl/SampleServiceImpl.java new file mode 100644 index 0000000..a64f314 --- /dev/null +++ b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/impl/SampleServiceImpl.java @@ -0,0 +1,29 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.impl; + +import com.alipay.sofa.ark.sample.facade.SampleService; + +/** + * @author qilong.zql + * @since 0.1.0 + */ +public class SampleServiceImpl implements SampleService { + public String service() { + return "A Sample Service"; + } +} \ No newline at end of file diff --git a/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/springbootdemo/SpringbootDemoApplication.java b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/springbootdemo/SpringbootDemoApplication.java new file mode 100644 index 0000000..fa9fa29 --- /dev/null +++ b/sample-ark-springboot/src/main/java/com/alipay/sofa/ark/sample/springbootdemo/SpringbootDemoApplication.java @@ -0,0 +1,36 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample.springbootdemo; + +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.context.annotation.ImportResource; + +/** + * A sample spring boot web project repackage as ark fat jar. + * + * @author qilong.zql + * @since 0.1.0 + */ +@ImportResource({ "classpath*:META-INF/spring/service.xml" }) +@SpringBootApplication +public class SpringbootDemoApplication { + + public static void main(String[] args) { + SpringApplication.run(SpringbootDemoApplication.class, args); + } +} \ No newline at end of file diff --git a/sample-ark-springboot/src/main/resources/META-INF/spring/service.xml b/sample-ark-springboot/src/main/resources/META-INF/spring/service.xml new file mode 100644 index 0000000..64a38cf --- /dev/null +++ b/sample-ark-springboot/src/main/resources/META-INF/spring/service.xml @@ -0,0 +1,8 @@ + + + + + + \ No newline at end of file diff --git a/sample-ark-springboot/src/main/resources/application.properties b/sample-ark-springboot/src/main/resources/application.properties new file mode 100644 index 0000000..e69de29 diff --git a/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/IntegrationTest.java b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/IntegrationTest.java new file mode 100644 index 0000000..13a8e9f --- /dev/null +++ b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/IntegrationTest.java @@ -0,0 +1,43 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample; + +import com.alipay.sofa.ark.sample.facade.SampleService; +import com.alipay.sofa.ark.sample.springbootdemo.SpringbootDemoApplication; +import com.alipay.sofa.ark.springboot.runner.ArkBootRunner; +import org.junit.Assert; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; + +/** + * @author qilong.zql 18/3/31-下午4:14 + */ +@RunWith(ArkBootRunner.class) +@SpringBootTest(classes = SpringbootDemoApplication.class) +public class IntegrationTest { + + @Autowired + private SampleService sampleService; + + @Test + public void test() { + Assert.assertTrue("A Sample Service".equals(sampleService.service())); + } + +} \ No newline at end of file diff --git a/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/JUnitTest.java b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/JUnitTest.java new file mode 100644 index 0000000..c3577a3 --- /dev/null +++ b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/JUnitTest.java @@ -0,0 +1,38 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample; + +import com.alipay.sofa.ark.support.runner.ArkJUnit4Runner; +import org.junit.Assert; +import org.junit.Test; +import org.junit.runner.RunWith; + +/** + * A JUnitTest Demo + * + * @author qilong.zql + * @since 0.1.0 + */ +@RunWith(ArkJUnit4Runner.class) +public class JUnitTest { + + @Test + public void test() { + Assert.assertTrue(true); + } + +} \ No newline at end of file diff --git a/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/TestNGTest.java b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/TestNGTest.java new file mode 100644 index 0000000..49cd159 --- /dev/null +++ b/sample-ark-springboot/src/test/java/com/alipay/sofa/ark/sample/TestNGTest.java @@ -0,0 +1,42 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You 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. + */ +package com.alipay.sofa.ark.sample; + +import com.alipay.sofa.ark.support.listener.TestNGOnArk; +import org.testng.Assert; +import org.testng.annotations.Test; + +/** + * A TestNGTest Demo + * + * @author qilong.zql + * @since 0.3.0 + */ +@TestNGOnArk +public class TestNGTest { + + public static final String TEST_CLASSLOADER = "com.alipay.sofa.ark.container.test.TestClassLoader"; + + @Test + public void test() { + ClassLoader tccl = Thread.currentThread().getContextClassLoader(); + ClassLoader loader = this.getClass().getClassLoader(); + Assert.assertTrue(tccl.equals(loader)); + Assert.assertTrue(TEST_CLASSLOADER.equals(tccl.getClass().getCanonicalName())); + } + +} \ No newline at end of file