Siminov Framework - Connect - Android RESTful 框架

Siminov 框架

4.73/5 (9投票s)

2015年1月28日

Apache

11分钟阅读

19606

Siminov Android Connect 是一个基于 Android 的 RESTful 框架，它允许您无缝地使用支持您数据的 RESTful Web 服务，这些服务支持多种表示媒体类型，并抽象了客户端-服务器通信的底层细节。

引言

使用支持您数据的 RESTful Web 服务，这些服务支持多种表示媒体类型，并抽象了客户端-服务器通信的底层细节，如果没有一个好的工具集，这并不是一件容易的事情。它是一个强大而灵活的工具集，可以轻松地使用 RESTful 服务。

表征状态转移

REST 代表表征状态转移。（有时也拼写为“ReST”）。它依赖于一个无状态、客户端-服务器、可缓存的通信协议，并且几乎在所有情况下，都使用 HTTP 协议。

REST 是一种设计网络应用程序的架构风格。其理念是，不是使用 CORBA、RPC 或 SOAP 等复杂机制在机器之间进行连接，而是使用简单的 HTTP 来实现机器之间的调用。

在很多方面，基于 HTTP 的万维网本身可以被视为一种基于 REST 的架构。RESTful 应用程序使用 HTTP 请求来发布数据（创建和/或更新）、读取数据（例如，执行查询）和删除数据。因此，REST 在所有四个 CRUD（创建/读取/更新/删除）操作中都使用 HTTP。

Siminov Connect 是一个轻量级、全面、开源的 REST 框架，适用于 Android 平台。它减轻了在 Android 中构建和使用 RESTful API 所涉及的工作量。它支持主要的 Internet 传输、数据格式和服务描述标准，如 HTTP 和 HTTPS、SMTP、XML 和 JSON。

您需要的所有功能

易于配置

应用程序描述符：应用程序描述符是连接应用程序与 Siminov 框架的组件。它提供了关于应用程序的基本信息，定义了应用程序的行为。

					<!-- Design Of ApplicationDescriptor.si.xml -->

<siminov>

    <!-- General Application Description Properties -->

        <!-- Mandatory Field -->
    <property name="name">application_name</property>   

        <!-- Optional Field -->
    <property name="description">application_description</property>

        <!-- Mandatory Field (Default is 0.0) -->
    <property name="version">application_version</property>



    <!-- Database Descriptors Used By Application (zero-to-many) -->    
        <!-- Optional Fields -->
    <database-descriptors>
        <database-descriptor>full_path_of_database_descriptor_file</database-descriptor>
    </database-descriptors>


    <!-- Service Descriptors Used By Application (zero-to-many) -->
    <service-descriptors>

            <!-- Service Descriptor -->
        <service-descriptor>full_path_of_service_descriptor</service-descriptor>

    </service-descriptors>



    <!-- Sync Descriptors Used By Application (zero-to-many) -->
    <sync-descriptors>

			<!-- Sync Descriptor -->
        <sync-descriptor>full_path_of_sync_descriptor</sync-descriptor>

    </sync-descriptors>


    <!-- Notification Descriptor -->
    <notification-descriptor>

            <!-- Optional Field -->
        <property name="name_of_property">value_of_property</property>

    </notification-descriptor>



    <!-- Library Descriptors Used By Application (zero-to-many) -->
        <!-- Optional Fields -->
    <library-descriptors>
        <library-descriptor>full_path_of_library_descriptor_file</library-descriptor>   
    </librar-descriptors>


    <!-- Event Handlers Implemented By Application (zero-to-many) -->

        <!-- Optional Fields -->
    <event-handlers>
        <event-handler>full_class_path_of_event_handler_(ISiminovHandler/IDatabaseHandler)</event-handler>
    </event-handlers>

</siminov>

服务描述符：服务描述符定义了您的 RESTful Web 服务 API 的结构。

						<!-- Design Of ServiceDescriptor.si.xml -->


<service-descriptor>

    <!-- General Service Properties -->
        <!-- Mandatory Field -->
    <property name="name">name_of_service</property>

        <!-- Optional Field -->
    <property name="description">description_of_service</property>

        <!-- Optional Field (DEFAULT: HTTP) -->
    <property name="protocol">HTTP|HTTPS</property>

        <!-- Mandatory Field -->
    <property name="instance">address_of_instance</property>

        <!-- Optional Field -->
    <property name="port">port_number</property>

        <!-- Optional Field -->
    <property name="context">context_of_service</property>

    <!-- Requests -->
        <!-- Request -->
    <request>

        <request>

            <!-- General Request Properties -->

                <!-- Mandatory Field -->
            <property name="name">name_of_request</property>

                <!-- Mandatory Field -->
            <property name="type">GET|HEAD|POST|PUT|DELETE|TRACE|OPTIONS|CONNECT|PATCH</property>

                <!-- Mandatory Field -->
            <property name="api">full_request_path</property>

                <!-- Mandatory Field -->
            <property name="handler">handler_of_request</property>

                <!-- Optional Field (DEFAULT: SYNC)-->
            <property name="mode">SYNC|ASYNC</property>



            <!-- Query Parameters -->
                <!-- Query Parameter -->
            <query-parameters>

                <query-parameter>

                    <!-- Mandatory Field -->
                    <property name="name">name_of_query_parameter</property>

                    <!-- Mandatory Field -->
                    <property name="value">value_of_query_parameter</property>

                </query-parameter>

            </query-parameters>


            <!-- Header Parameters -->
                <!-- Header Parameter -->
            <header-parameters>

                <header-parameter>

                    <!-- Mandatory Field -->
                    <property name="name">name_of_header_parameter</property>

                    <!-- Mandatory Field -->
                    <property name="value">value_of_header_parameter</property>

                </header-parameter>

            </header-parameters>


            <!-- Stream of Data Under Request Body -->
                <!-- It is Optional Property -->
            <data-stream>stream_of_data</data-stream>   

        </request>
    </requests>

</service-descriptor>

同步描述符：同步描述符定义了通过服务进行数据同步。

					<!-- Design Of ServiceDescriptor.si.xml -->	
<sync-descriptor>

        <!-- Mandatory Field -->
    <property name="name">name_of_sync_handler</property>

        <!-- Optional Field -->
    <property name="sync_interval">sync_interval_in_millisecond</property>

        <!-- Optional Field -->
            <!-- Default: SCREEN -->
    <property name="type">INTERVAL|SCREEN|INTERVAL-SCREEN</property>

    <!-- Service Descriptors -->
        <!-- Service Descriptor -->
    <service-descriptors>

        <service-descriptor>name_of_service_descriptor.name_of_api</service-descriptor>

    </service-descriptors>

</sync-descriptor>

库描述符：库描述符定义了库的属性。

					<!-- Design Of LibraryDescriptor.si.xml -->


<library-descriptor>

    <!-- General Properties Of Library -->

    <!-- Mandatory Field -->
    <property name="name">name_of_library</property>

    <!-- Optional Field -->
    <property name="description">description_of_library</property>



    <!-- Database Mappings Needed Under This Library Descriptor -->

    <!-- Optional Field -->
        <!-- Database Mappings -->
    <database-mapping-descriptors>
        <database-mapping-descriptor>name_of_database_descriptor.full_path_of_database_mapping_descriptor_file</database-mapping-descriptor>
    </database-mapping-descriptors>


    <!-- Service Descriptors -->

    <!-- Optional Field -->
        <!-- Service Descriptor -->
    <service-descriptors>
        <service-descriptor>full_path_of_service-descriptor_file</service-descriptor>
    </service-descriptors>


    <!-- Sync Descriptors -->

    <!-- Optional Field -->
        <!-- Sync Descriptor -->
    <sync-descriptors>
        <sync-descriptor>full_path_of_sync_descriptor_file</sync-descriptor>
    </sync-descriptors>


</library-descriptor>

推送通知

所有平台都提供推送通知，但形式和实现方式不同。它在一个统一的 API 包和架构上，为所有平台提供了一种独特且通用的实现。
同步

将您的应用数据与服务数据同步是一项艰巨的任务。它允许应用程序在后台自动检查更新。您可以通过多种方式同步您的应用数据。
- 时间间隔
- 屏幕点击
- 时间间隔 + 屏幕点击
数据库填充
由于它构建在 Siminov Core 之上，它提供了与数据库相关的所有功能。您可以轻松地将您的核心数据对象映射到数据库。

事件通知器

它提供了事件通知器，该通知器会基于特定操作触发。使用这些通知器，您可以根据触发的事件轻松采取行动。

同步事件：ISyncEvents 与同步操作相关联。

public interface ISyncEvents {
	
	public void onStart(ISyncRequest syncRequest);
	
	public void onQueue(ISyncRequest syncRequest);
	
	public void onFinish(ISyncRequest syncRequest);
	
	public void onTerminate(ISyncRequest syncRequest);
}

通知事件：INotificationEvents 包含与通知相关的事件。

public interface INotificationEvents {
	
	public void onRegistration(IRegistration registration);
	
	public void onUnregistration(IRegistration registration);
	
	public void onNotification(IMessage message);
	
	public void onError(NotificationException notificationException);
	
}

Service

服务是处理和处理任何 Web 服务请求的客户端通信组件。它在后台执行长时间运行的操作。服务是一组处理特定 Web 服务的请求。

应用程序通常包含多个松散耦合的服务。通常，应用程序中的一个服务被指定用于为特定的 Web 服务执行给定的任务。每个服务都可以启动另一个服务以执行不同的操作。

由于状态发生变化，服务可能会收到多个回调方法——无论是框架正在创建它、停止它、恢复它还是销毁它——并且每个回调都为您提供了执行适合该状态更改的特定工作的机会。例如，当服务停止时，它应该释放任何大型对象，例如网络或数据库连接。

当服务恢复时，您可以重新获取必要的资源并恢复被中断的服务。所有这些状态转换都是服务生命周期的一部分。

让我们讨论一下如何构建和使用服务的基础知识，包括对服务生命周期如何工作的完整讨论，以便您可以正确管理各种服务状态之间的转换。
- 创建服务
  
  要创建服务，您必须创建 Service 的子类（或其现有子类）。在您的子类中，您需要实现框架在服务在其生命周期的各个状态之间转换时调用的回调方法，例如服务正在启动、停止、恢复或销毁时。
  
  最重要的两个回调方法是
  - onStart：这是创建服务时调用的第一个方法。OnStart 始终被重写，以执行服务可能需要的任何启动初始化，例如
    - 初始化变量
    - 将静态数据绑定到服务
    - 将相关屏幕绑定到服务
    OnStart 完成后，如果服务处于 ASYNC 模式，Connect 将调用 OnServiceQueue，否则调用 OnServiceRequestInvoke。
  - onRequestFinish(ConnectionResponse)：在 Web 服务 API 执行后调用此方法。
    还有几个其他生命周期回调方法，您应该使用它们来处理服务转换更改。所有生命周期回调方法稍后将在“管理服务生命周期”部分中讨论。
- 创建服务描述符
  
  使用服务描述符，您可以描述您的 RESTful Web 服务 API 的结构。要声明您的服务描述符，您必须在应用程序的 assets 文件夹中创建一个服务描述符文件，并在应用程序描述符中添加该文件。
```
<service-descriptors>

        
    <service-descriptor>full_path_of_service_descriptor</service-descriptor>

</service-descriptors>
```
- 启动服务
  
  您可以通过创建服务的实例并调用 invoke() API 来启动服务。您还可以使用下面的 Resource API 向服务传递其他资源
  - addResource(您的资源的键，您的资源)
    使用此 API，您可以为您的服务添加其他资源。
  - containResource(您的资源的键)
    使用此 API，您可以检查服务中是否存在该资源。
  示例
```
LiquorBrand liquorBrand = new LiquorBrand();
liquorBrand.addResource(key_of_your_resource, your_resource);
liquorBrand.invoke();
```
- 关闭服务
  
  您可以通过调用其 terminate() 方法来关闭服务。
  
  注意
  
  在大多数情况下，您不应显式地使用这些方法来完成服务。如以下关于服务生命周期的部分所述，框架为您管理服务的生命周期，因此您无需终止自己的服务。调用这些方法可能会对预期的用户体验产生负面影响，并且应仅在您绝对不希望用户返回到此服务实例时使用。
- 服务执行类型
  
  在服务描述符中，您可以定义服务执行的模式。服务有两种执行方式
```
<service-descriptor>
	<requests>
		<request>
			<property name="mode">SYNC|ASYNC</property>
		</request>
	</requests>
</service-descriptor>
```
  - 前台服务
    
    前台服务是用户主动感知到的服务，因此不是系统在内存不足时需要终止的服务。前台服务必须为状态栏提供一个通知，该通知放在“正在进行”标题下，这意味着除非服务停止或从前台移除，否则通知无法被取消。
  - 后台服务
    
    后台服务是在没有用户交互的情况下运行的服务，它提供了一个简单的结构，用于在单个后台线程上运行操作。这使得您可以处理长时间运行的操作而不会影响用户界面的响应能力。此外，它也不受大多数用户界面生命周期事件的影响，因此在会关闭 ASYNC 服务的情况下它会继续运行。
    
    要请求您的服务在后台运行，您必须将服务描述符模式属性配置为 ASYNC。
- 管理服务生命周期
  
  服务是 Connect Framework 的基本构建块，它们可以存在于多种不同的状态中。服务生命周期从实例化开始，到销毁结束，并包含许多中间状态。当服务状态发生变化时，会调用相应的生命周期事件方法，通知服务即将发生的状态变化，并允许它执行代码以适应该变化。
  
  在生命周期回调方法中，您可以声明当服务上发生任何事件时，您的服务如何表现。
  - 概述
    
    服务是 Siminov Connect 特有的一个不寻常的编程概念。服务生命周期被实现为应用程序在服务的整个生命周期中调用的一组方法。这些方法允许开发人员实现满足其应用程序的状态和资源管理需求所需的功能。
    
    应用程序开发人员分析每个服务的需求，以确定服务生命周期提供的哪些方法需要实现，这一点至关重要。未能这样做可能导致应用程序不稳定、数据不一致。
  - 生命周期
    
    服务生命周期包含一组在 Service 类中公开的方法，这些方法为开发人员提供了一个资源管理框架。该框架允许开发人员满足应用程序中每个服务的独特状态管理需求，并妥善处理资源管理。
    
    服务状态服务状态可分为 4 个主要组，如下所示
    - 活动或运行：如果服务正在执行或处理，则认为服务是活动或正在运行的。
    - 暂停：当设备进入睡眠状态或没有网络通信时，服务将被视为暂停。暂停的服务仍然存活，即它们保持所有状态和成员信息，并保持与应用程序的连接。
    - 停止：当服务完成其进程或被终止时，服务被视为已停止。
    - 恢复：在生命周期中处于暂停到停止状态的任何服务都有可能被应用程序从内存中移除。
    生命周期方法作为开发人员，您可以通过在服务中重写这些方法来处理状态更改。但需要注意的是，所有生命周期方法都可能在 UI 线程/非 UI 线程上调用，并且可能会阻止 OS 执行下一项 UI 工作，例如隐藏当前屏幕、显示新屏幕等。因此，这些方法中的代码应尽可能简短，以使应用程序感觉性能良好。任何长时间运行的任务都应在 ASYNC 服务模式下执行。
    - onStart()：这是创建服务时调用的第一个方法。OnStart 始终被重写，以执行服务可能需要的任何启动初始化，例如
      - 初始化变量
      - 将静态数据绑定到服务
      - 将相关屏幕绑定到服务
      OnStart 完成后，如果服务处于 ASYNC 模式，Connect 将调用 OnServiceQueue，否则调用 OnServiceRequestInvoke。
    - onQueue()：当服务被放入执行队列时调用此方法。
    - onPause()：当没有网络时调用此方法。如果需要，服务应重写此方法来
      - 提交未保存的更改到持久数据
      - 销毁或清理消耗资源的其它对象
      - 显示任何相关的警报或对话框
    - onResume()：当服务准备好开始执行时，Connect 调用此方法。服务应重写此方法来执行任务，例如
      - 显示任何相关的警报或对话框
      - 连接外部事件处理程序
      - 监听 GPS 更新
    - onFinish()：这是在服务实例被销毁并完全从内存中移除之前调用的最后一个方法。服务被销毁后不会再调用任何生命周期方法。
    - onRequestInvoke(ConnectionRequest)：在服务调用 Web 服务 API 之前调用此方法。
    - onRequestFinish(ConnectionResponse)：在 Web 服务 API 执行后调用此方法。
    - onTerminate(SiminovException)：当服务执行过程中发生任何异常时调用此方法。调用此方法后，服务将被终止并从内存中释放。
- 请求
  - GET：用于检索数据。
  - HEAD：用于检索响应标头中编写的元信息，而无需传输整个内容。
  - POST：用于请求服务器接受请求中包含的实体作为 URI 标识的 Web 资源的新的子资源。
  - PUT：用于请求将包含的实体存储在提供的 URI 下。
  - DELETE：删除指定的资源。
  - TRACE：回显接收到的请求，以便客户端可以看到中间服务器对请求进行了哪些（如果有）更改或添加。
  - OPTIONS：返回服务器支持的指定 URL 的 HTTP 方法。
  - CONNECT：将请求连接转换为透明的 TCP/IP 隧道，通常是为了通过未加密的 HTTP 代理促进 SSL 加密通信 (HTTPS)。
  - PATCH：用于对资源进行部分修改。
- 引用资源
  
  在创建服务描述符时，有时您希望在运行时引用资源。您可以通过以下方式在运行时从描述符中引用资源。
  - 资源 {@resource 资源密钥}
    将资源作为参数传递给请求本身。
    示例
```
<request>

    <property name="name">DELETE-LIQUOR</property>
    <property name="type">DELETE</property>
    <property name="api">delete-liquor</property>
    <property name="handler">siminov.connect.sample.services.DeleteLiquor</property>
    <property name="mode">ASYNC</property>

    <header-parameters>
        <header-parameter name="Accept">application/xml</header-parameter>
        <header-parameter name="Content-Type">application/xml</header-parameter>
        <header-parameter name="name">{@resource LIQUOR_NAME}</header-parameter>
    </header-parameters>

</request>



Liquor liquor = new Liquor();
liquor.addResource('LIQUOR_NAME', name_of_liquor);
```
  - 引用 {@refer 引用资源完整路径-引用资源的参数}
    
    调用引用的资源位置以获取属性值。
```
<request>

    <property name="name">DELETE-LIQUOR</property>
    <property name="type">DELETE</property>
    <property name="api">delete-liquor</property>
    <property name="handler">siminov.connect.sample.services.DeleteLiquor</property>
    <property name="mode">ASYNC</property>

    <header-parameters>
        <header-parameter name="Accept">application/xml</header-parameter>
        <header-parameter name="Content-Type">application/xml</header-parameter>
        <header-parameter name="name">{@refer siminov.connect.sample.Refer.getLiquorName}</header-parameter>
    </header-parameters>

</request>
```
  - 自引用资源 {@self 包含的属性名称}
    
    从服务描述符本身获取自引用资源。
```
<request>

    <property name="name">DELETE-LIQUOR</property>
    <property name="type">DELETE</property>
    <property name="api">delete-liquor</property>
    <property name="handler">siminov.connect.sample.services.DeleteLiquor</property>
    <property name="mode">ASYNC</property>

    <header-parameters>
        <header-parameter name="Accept">application/xml</header-parameter>
        <header-parameter name="Content-Type">application/xml</header-parameter>
        <header-parameter name="name">{@self name}</header-parameter>
    </header-parameters>

</request>
```

许可证

 [SIMINOV FRAMEWORK]
 Copyright [2015] [Siminov Software Solution|support@siminov.com]

 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

	https://apache.ac.cn/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.

结论

如果您正在寻找一个轻量级、易于使用且简单的 Restful 客户端框架，那么 Siminov Connect 是您的理想选择。它不仅可以处理您的服务器通信，还允许您定期同步应用数据。

它还为您的应用程序提供了通用的推送通知和数据库填充处理方式。

Siminov Framework - Connect - Android RESTful 框架

引言

表征状态转移

您需要的所有功能

易于配置

推送通知

同步

数据库填充

事件通知器

Service

创建服务

创建服务描述符

启动服务

addResource(您的资源的键，您的资源)

containResource(您的资源的键)

关闭服务

注意

服务执行类型

前台服务

后台服务

管理服务生命周期

概述

生命周期

请求

引用资源

资源 {@resource 资源密钥}

引用 {@refer 引用资源完整路径-引用资源的参数}

自引用资源 {@self 包含的属性名称}

许可证

结论