Saltar al contenido principal
Version: Next (5.0)

awe-107 Servicios

Los servicios son el punto de extensión del lado servidor que se usa cuando las queries o los maintains por sí solos no bastan. En la práctica, el camino habitual es un servicio Java enlazado a través de Services.xml y expuesto mediante una query o un target de maintain.

Ruta rápida​

  1. Define el servicio en global/Services.xml.
  2. Implementa el método Java como un servicio gestionado por Spring.
  3. Devuelve ServiceData con la forma que espera quien lo llama.
  4. Expón el servicio mediante una query o un target de maintain.
  5. Trata las integraciones que no son Java como trabajo avanzado y específico de cada entorno.

Antes de empezar​

Este tutorial asume que ya entiendes:

  • awe-104 para queries y maintains
  • awe-106 para acciones de botón y llamadas al servidor

Si tu caso de uso es un simple CRUD sobre tablas de base de datos, no saltes a un servicio demasiado pronto. Los descriptores de AWE ya cubren mucho. Recurre a los servicios cuando necesites lógica en el servidor, código de integración o un comportamiento que no encaja en una definición simple de query o maintain.

Paso 1: Entender dónde encajan los servicios​

Los servicios pueden respaldar:

  • queries que recuperan datos calculados o externos
  • targets de maintain que necesitan lógica de escritura propia

Flujo general:

screen action -> query or maintain -> service definition -> Java code

El motor de servicios resuelve el servicio configurado y delega en la implementación del tipo correspondiente.

Motor de servicios

Para la referencia exhaustiva del descriptor de servicios, usa la documentación canónica de la API:

Paso 2: Definir un servicio Java en global/Services.xml​

Los servicios Java son el camino normal para la lógica propia del lado servidor en una aplicación AWE.

<service id="MyJavaService">
  <java classname="com.app.services.MyService" method="concat">
    <service-parameter type="STRING" name="text1" />
    <service-parameter type="STRING" name="text2" />
  </java>
</service>

Qué hace esta definición:

  • asigna el id de servicio MyJavaService
  • apunta a la clase com.app.services.MyService
  • llama al método concat
  • mapea dos parámetros STRING llamados text1 y text2

Paso 3: Implementar el servicio Java​

La clase Java debe estar disponible en el classpath de la aplicación y gestionada por Spring.

En AWE, el patrón habitual de un servicio es:

  • extender ServiceConfig
  • devolver ServiceData
  • construir los datos devueltos con la forma que espera la query o el maintain que lo llama

Ejemplo:

MyService.java
package com.app.services;

import com.almis.awe.config.ServiceConfig;
import com.almis.awe.model.dto.DataList;
import com.almis.awe.model.dto.ServiceData;
import com.almis.awe.model.util.data.DataListUtil;
import org.springframework.stereotype.Service;

@Service
public class MyService extends ServiceConfig {

  /**
   * Concatenate two strings and expose the result as label/value.
   *
   * @param text1 First text
   * @param text2 Second text
   * @return Service response
   */
  public ServiceData concat(String text1, String text2) {
    String result = text1 + text2;

    ServiceData serviceData = new ServiceData();
    DataList dataList = new DataList();

    DataListUtil.addColumnWithOneRow(dataList, "label", result);
    DataListUtil.addColumnWithOneRow(dataList, "value", result);

    serviceData.setDataList(dataList);
    return serviceData;
  }
}

Reglas prácticas importantes:

  • el método debe devolver ServiceData
  • los nombres de las columnas devueltas deben coincidir con los que espera la query que lo llama
  • si el servicio alimenta un select, un suggest o un flujo de tipo valor, label y value son los campos de salida habituales

Paso 4: Exponer el servicio mediante una query o un target de maintain​

Query respaldada por un servicio​

Si el servicio devuelve datos a la interfaz, una query suele ser el punto de entrada más limpio.

<query id="MyConcatQuery" service="MyJavaService">
  <field id="label" alias="label" />
  <field id="value" alias="value" />
</query>

Esta query puede consumirla después un criterio, un flujo auxiliar de un grid o cualquier otro componente que espere datos.

Maintain respaldado por un servicio​

Si el servicio realiza una escritura o un efecto secundario, expónlo mediante un target de maintain.

<target name="RunMyService">
  <serve service="MyJavaService" />
</target>

Así el modelo de acciones del cliente sigue siendo coherente: los botones siguen llamando a maintains o queries, y el maintain puede delegar en Java cuando haga falta.

Nota avanzada: integraciones de servicios que no son Java​

Algunas instalaciones de AWE también usan definiciones de servicio para integraciones externas o heredadas, como microservicios o backends en C. Esa configuración es más específica de cada entorno que el camino Java, por lo que este tutorial la trata de forma deliberadamente breve.

Ejemplo de definición de servicio:

<service id="ConcatString">
  <microservice name="alu-microservice" method="POST" endpoint="/data/CctStrDat">
    <service-parameter type="STRING" name="texto1" />
    <service-parameter type="STRING" name="texto2" />
  </microservice>
</service>

Usa la API de definición de servicios como referencia canónica de esas variantes y valida el contrato exacto de la integración con la aplicación o plataforma que estés extendiendo.

Qué hacer a continuación​

  • Vuelve a awe-104 si necesitas revisar dónde encajan los servicios respecto a las queries y los maintains.
  • Vuelve a awe-106 cuando conectes estos servicios con flujos dirigidos por botones.
  • Prefiere primero el camino de servicios Java, salvo que tu proyecto ya tenga un patrón de integración no Java establecido.