Liferay6.2：Registering JSON Web Services - 注册JSON WebService

Registering JSON Web Services - 注册JSON WebService

Liferay的开发人员使用名为Service Builder的工具来构建服务。 使用Service Builder构建服务时，所有被启用的远程服务（即service.xml中具有属性remote-service ="true"的实体）都将公开为JSON Web service。 为remote-enabled service创建每个*Service.java接口时，会在该接口的类级别上添加@JSONWebService 注解。 该接口的所有公共方法都会被注册并可用作JSON Web service。

Service.java接口源文件不能直接修改。 如果需要对其方法进行更多控制（例如，如果需要在暴露一些方法时隐藏某些方法），可以配置ServiceImpl类。 当使用@JSONWebService注解对服务实现类(*ServiceImpl)进行修饰时，将忽略service接口，并在其位置使用serviceImpl类进行配置。 换句话说，serviceImpl中的@JSONWebService注解会覆盖service接口中的任何JSON Web service配置。

当启动Liferay Portal时，它会扫描service类以获取注解。 使用@JSONWebService注解修饰的每个类将会被检查，并通过JSON Web services API公开其方法。 如前所述，ServiceImpl配置会在注册期间覆盖Service接口配置。

但是，Liferay Portal不会扫描注解修饰的所有可用类。 相反，它只扫描services。 更确切地说，它扫描在portal(门户网站)的application context中注册的所有类，包括plugin类。也就是扫描BeanLocator可用的所有类。 实际上，portal会扫描在其Spring context中注册的所有类以及其插件的Spring context。 如果使用Service Builder构建插件服务，则service会自动注册到Spring context，并提供给BeanLocator使用。 这也意味着你可以在plugin的Spring context中注册任何对象，portal会扫描它以获取远程服务！ Liferay不强迫使用Service Builder。

现在开始学习如何将plugin的远程服务注册为JSON Web service。Liferay的开发人员使用相同的机制。 这就是为什么Liferay Portal的远程服务(remote service)被公开为JSON Web service的开箱即用的原因。

Registering Plugin JSON Web Services - 注册插件的JSON Web Services

假设你有一个名为SupraSurf的portlet，它有一些服务。 并且决定将它们作为远程服务公开。 在其SurfBoard实体上启用remote-service属性后，你将重建服务。 Service Builder重新生成SurfBoardService接口，并向其添加@JSONWebService 注解。 此注解告诉portal接口的公共方法将作为JSON Web service公开，使它们成为plugin的JSON API的一部分。

默认情况下，portlet服务的扫描是禁用状态。 要启用扫描，你需要在portlet的web.xml文件中添加适当的过滤器定义(filter definition)。 幸运的是，Liferay提供了一种自动添加过滤器的方法。 只需在Liferay IDE中单击Build WSDD按钮，同时在Overview模式下编辑service.xml文件，或者只调用build-wsdd Ant target。 在构建WSDD时，Liferay的Plugins SDK修改了portlet的web.xml，并为插件启用了JSON Web service。 在幕后，Plugins SDK为插件注册了SecureFilter和JSONWebServiceServlet。 你只需为plugin启用一次JSON Web服务即可。

如果你的门户网站服务器未运行，需要先启动。 然后将portlet plugin部署到Liferay。

要从portal获取有关注册plugin服务的一些反馈，请配置portal以记录plugin的信息性消息（即其INFO…消息）。 有关详细信息，请参阅Using Liferay Portal 中有关Liferay日志记录系统的部分。

要测试Liferay的JSON Web service注册过程，请为plugin的service添加一个简单的方法。 编辑*ServiceImpl类并添加以下方法：

public String helloWorld(String worldName) {
    return "Hello world: " + worldName;
}

重建服务并重新部署plugin。 请注意，portal会打印一条消息，如下所示，通知我们已为portlet配置一个action。 这表明服务方法现在已注册为JSON Web Web服务操作。

INFO  [JSONWebServiceActionsManagerImpl:117] Configured 1 actions for\
    /suprasurf-portlet

Liferay Portal自己的service action采用同样的机制注册。 它们默认情况下已经启用，因此无需配置。

接下来，让我们学习如何为远程服务形成映射URL，以便我们可以访问。

Mapping and Naming Conventions - 映射与命名约定

你可以按照以下命名约定形成公开服务的映射URL：

http://[server]:[port]/api/jsonws/[plugin-context-name].[service-class-name]/[service-method-name]

仔细看一下最后三个括号中的条目：

• plugin-context-nameplugin的上下文名称（例如，在我们的示例中为suprasurf-portlet）。 对于portal的服务，应省略plugin-context-name和后续的内容(subsequent period)。
• service-class-name是从service的类名生成的小写，减去Service或ServiceImpl后缀。 例如，将surfboard指定为SurfBoardService类的plugin-context-name。
• service-method-name是从服务的方法名称生成的，方法是将其camel case驼峰式转换为小写，并使用短划线(-)分隔单词。

接下来我们在创建的plugin service和portal service上演示这些命名约定，通过使用命名约定来映射服务方法的URL

对于我们创建的服务方法，URL是这样的：

http://localhost:8080/api/jsonws/suprasurf-portlet.surfboard/hello-world

请注意URL的context名称部分。 对于portal来说，它是相似的。 这是我们想要访问的portal service方法：

@JSONWebService
public interface UserService {
    public com.liferay.portal.model.User getUserById(long userId) {...}

这是portal service方法的URL：

http://localhost:8080/api/jsonws/user-service/get-user-by-id

每种服务方法都绑定到一种HTTP方法类型。 名称以get，is或has开头的任何方法都假定为只读方法，默认情况下映射为GET HTTP方法。 所有其他方法都映射为POST HTTP方法。

你可能已经注意到，plugin services是通过portal context访问的。以这种方式发送的request可以利用认证凭证(authentication credentials ) ，该认证与用户的当前门户session相关联。

接下来，我们将学习如何列出门户网站提供的JSON Web service。

Listing Available JSON Web Services - 列出可用的JSON Web Service

要查看已注册和可供使用的服务方法，请将浏览器打开到以下地址：

http://localhost:8080/api/jsonws

API页面列出了portal的已注册和公开的服务方法。要获取每个方法的详细信息，请单击方法名称。你将看到该方法的完整签名，其所有参数以及可抛出的Exception列表。有关远程服务方法的其他信息，你可以在Liferay Portal的Javadocs中查找该方法。使用浏览器中的简单表单，你甚至可以调用服务方法。在开发portlet服务时，这对于测试来说非常方便。

这个API页面也列出了plugin的远程服务。如果已部署了启用远程服务的多个plugin，请单击API页面上的Context Path选择器。此选择器列出了所有可用的plugin context path（包括portal的路径）。选择plugin的context path或portal的context path，以列出context path中可用的所有远程服务。

如前文所述所述，你可以使用*ServiceImpl类中的@JSONWebService注解来控制注册。这将覆盖接口中定义的任何配置。你还可以在方法级别使用注解控制方法的可见性。

让我们来了解如何忽略特定方法。

Ignoring a Method - 忽略特定方法

要使方法不作为服务公开，请使用以下选项修饰该方法：

@JSONWebService(mode = JSONWebServiceMode.IGNORE)

使用此注解的方法不会成为JSON Web Service API中的一部分。

接下来学习如何定义自定义HTTP方法名称和URL名称。

HTTP Method Name and URL - HTTP 方法与URL

在方法级别，你可以定义HTTP方法名称和URL名称。 只需使用这样的注解：

@JSONWebService(value = "add-board-wow", method = "PUT")
public boolean addBoard(

在此例中，plugin的服务方法addBoard映射到URL方法名称add-board-wow。 它的完整URL现在是http// localhost:8080/api/jsonws/suprasurf-portlet.surfboard/add-board-wow，可以使用HTTP PUT方法访问。

如果JSON Web Service注解中的URL方法名称以斜杠字符(/)开头，则仅使用方法名称来形成服务URL; 类名被忽略：

@JSONWebService("/add-something-very-specific")
public boolean addBoard(

同样，您可以通过在类级别注解中设置值来更改URL的类名称部分：

@JSONWebService("sbs")
public class SurfBoardServiceImpl extends SurfBoardServiceBaseImpl {

这会将所有服务的方法映射到URL类名称sbs，不再是默认的类名surfboard。

接下来，我们将向您展示一种不同的方式来公开服务方法，即手动注册。

Manual Registration Mode - 手动注册

假设你想要公开大多数服务方法的同时隐藏一些特定方法（即黑名单方法）。 或者想要明确指定那些要公开的方法（白名单方法）。 这也可以通过在类级别注释上指定手动模式来实现。 然后，你只需注解那些你想要公开的方法。

@JSONWebService(mode = JSONWebServiceMode.MANUAL)
public class SurfBoardServiceImpl extends SurfBoardServiceBaseImpl{
    ...
    @JSONWebService
    public boolean addBoard(

现在只有addBoard方法和使用@JSONWebService修饰的任何其他方法将成为JSON Web Service API的一部分; 此服务的所有其他方法将从API中排除。

注意：Liferay的JSON Web service 的对外访问默认是需要权限验证的，这与local service不同，调用本地服务都是在portlet UI中，已经进行过权限验证。而远程访问为了安全性的考虑，需要在远程服务方法中集成Liferay的权限认证，可参考Security and Permissions 。也可以将权限认证关闭，在*Service类级别上有@AccessControlled注解修饰，与@JSONWebService 类似，此注解也可以在ServiceImpl 中进行重新声明覆盖，以下是@AccessControlled的默认声明

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.TYPE})
public @interface AccessControlled {
	public boolean guestAccessEnabled() default false;
	public boolean hostAllowedValidationEnabled() default true;
}

我们可以覆盖为：

@AccessControlled(guestAccessEnabled = true, hostAllowedValidationEnabled = false)
@JSONWebService(value = "cneerp-json-webservice")
public class CneCommonProblemServiceImpl extends CneCommonProblemServiceBaseImpl {}