HCL Commerce Developer

El mandato de controlador basado en configuración y la infraestructura de correlación de beans de datos

El mandato de controlador basado en configuración y la infraestructura de correlación de beans de datos permiten la activación de los beans de datos o la ejecución de los mandatos de controlador mediante servicios REST. La infraestructura reduce significativamente la cantidad de código personalizado requerido. Proporciona una forma de describir qué entradas y salidas son necesarias desde un bean de datos o un mandato de controlador a través de un archivo de correlación. Un archivo de correlación representa un bean de datos o un mandato de controlador. Se subdivide en perfiles, lo que permite que varios recursos de REST con propiedades diferentes funcionen en el mismo bean de datos o controlador de mandato. El código personalizado que es necesario para escribir un manejador de recursos para un único recurso de REST puede ser tan simple como una sola línea. La correlación de entrada, tipo conversión, activación, ejecución y respuestas son gestionadas por la infraestructura. Para ayudar a producir un manejador y un archivo de correlación personalizado, se proporciona una herramienta de generador (restClassicSampleGen), lo que reduce aún más el esfuerzo de crear recursos de REST personalizados.

Nota: Esta infraestructura no utiliza el objeto de propiedades de petición (método setRequestProperties) para los mandatos de controlador. Debe definir métodos setter y getter individuales en el mandato controlador. Si necesita utilizar las propiedades de petición, utilice AbstractClassicResourceHandler directamente.
El mandato de controlador basado en configuración y la infraestructura de correlación de beans de datos utilizan los conceptos siguientes:
AbstractConfigBasedClassicHandler
El punto de entrada principal (superclase) del que se amplían todos los manejadores basados en configuración.
El abstracto es una subclase de AbstractClassicResourceHandler, que es la clase base para un manejador de recursos REST.
Dentro hay métodos para activar beans de datos y ejecutar mandatos de controladores.
Bean de datos y modelos de mandato controlador
Internamente, los beans de datos y los comandos de controlador se analizan bajo demanda en modelos, que después la infraestructura utiliza y almacena en la memoria caché.
Configuración del Bean de datos y de las correlaciones de mandato de controlador para REST
Para realizar llamadas REST a los beans y a los mandatos de controlador, se utilizan archivos de configuración de correlación.
Estos archivos de configuración de correlación se dividen en perfiles, que permiten diferentes tipos de llamadas para el mismo bean o mandato. Por ejemplo, para especificar valores de salida diferentes para cada perfil.
Los perfiles se incluyen de forma predeterminada para los servicios de beans de datos de REST y de mandato de controlador, mientras que puede añadir sus propios perfiles a un directorio de extensión de personalización.
Cada archivo de configuración existe para un único bean de datos o mandato de controlador. Describen la correlación de nombres de entrada (de la llamada REST) con el bean de datos correspondiente o el método de tipo setter de mandato controlador. Para cada perfil del archivo, se proporcionan correlaciones de salida. Describen cómo los métodos y las propiedades del tipo de captador del bean de datos o el mandato de controlador deben correlacionarse de nuevo con una entidad de salida REST. Por ejemplo, en formato JSON.
El diagrama siguiente muestra el mandato basado en configuración y la infraestructura de correlación de bean de datos:
mandato de controlador basado en configuración e infraestructura de correlación de beans de datos.
Donde:
  1. Se realiza una llamada REST para acceder a un bean de datos (GET) o a un mandato de controlador (POST).
  2. El bean de datos o el manejador del mandato de controlador intercepta la llamada. Solicita la infraestructura de REST basada en la configuración para establecer las propiedades para el bean de datos o el mandato de controlador, activar y devolver la respuesta.
  3. La infraestructura realiza las tareas siguientes:
    1. Inspecciona el bean de datos o la clase de mandato de controlador para crear su modelo. A continuación, este modelo se almacena en la memoria caché. Se produce un RestException si hay un problema con el modelo.
      Nota: Se tienen en cuenta los métodos Setter que tienen el mismo nombre pero toman parámetros diferentes, por ejemplo, String frente a Long. Se elige el parámetro ideal según el tipo de datos que se ha pasado para el establecedor.
    2. Analiza el perfil de correlación para que pueda determinar cómo correlacionar desde la llamada REST al bean de datos o al mandato de controlador. A continuación, correlacione la respuesta con el formato de HTTP solicitado. Por ejemplo, JSON. A continuación, el perfil de correlación se almacena en la memoria caché. Se produce un RestException si hay un problema con el archivo de correlaciones.
    3. Crea una instancia del bean de datos o del mandato de controlador.
    4. Rellena los métodos de establecedor basándose en el archivo de correlación y los datos que se proporcionan desde la llamada de REST.
    5. Activa el bean de datos o ejecuta el mandato de controlador.
    6. Crea la respuesta mediante el modelo de correlación para determinar qué métodos de respuesta (métodos de tipo getter) se deben llamar en el bean de datos o el mandato de controlador.
  4. Después de recuperar todos los valores, se devuelve la respuesta al manejador principal y, a continuación, se transmite al cliente.

Puntos de entrada de la infraestructura

Una llamada REST todavía requiere la creación de un manejador, basado en Apache Wink/JAX-RS. El manejador es relativamente pequeño. Normalmente es necesario para poder definir las anotaciones para que Apache Wink pueda entender cómo realizar la llamada REST al manejador y proporcionar la información solicitada. El código que se contiene en el manejador es normalmente una línea de código, que consta del punto de entrada en el manejador clásico basado en configuración. De forma predeterminada están disponibles los siguientes puntos de entrada:
  1. public Response executeConfigBasedBeanWithContext(String beanClassName, String profileName, String responseFormat, Map<String, Object> paramOverrideMap)

    Este método configura la solicitud de inicio {@link BusinessContextService}, luego delega a {@link #executeConfigBasedBean(String, String, String, Map)} y finalmente finaliza la solicitud BCS.

    Los parámetros siguientes están disponibles de forma predeterminada:
    nombreClaseBean
    El nombre de clase de bean de datos.
    profileName
    El nombre de perfil para el bean de datos en la configuración.
    responseFormat
    El formato de respuesta que se utiliza para generar el resultado.
    paramOverrideMap
    Define los parámetros que desea añadir o sustituir del objeto de solicitud que está asociado a este manejador.
    Normalmente se utiliza si hay parámetros de vía de acceso o datos de entidad que desea incluir cuando correlaciona los parámetros de consulta con la entrada del mandato.
    La clave debe ser una cadena. El valor puede ser cualquier objeto de tipo.
    El valor puede ser nulo.
  2. public JSONObject executeConfigBasedBean(String beanClassName, String profileName, String responseFormat, Map<String, Object> paramOverrideMap) throws Exception

    Este método procesa una solicitud de bean de datos mediante las correlaciones de perfil basadas en configuración. Presupone que el llamante trata con el {@link BusinessContextService}.

    Los parámetros de entrada se completan automáticamente basándose en los parámetros de vía de acceso especificados en el URL, seguidos de los parámetros de consulta.

    Se puede proporcionar un mapa de alteración temporal para inyectar más parámetros o sustituir los parámetros preexistentes.

    Los parámetros siguientes están disponibles de forma predeterminada:
    nombreClaseBean
    El nombre de clase de bean de datos.
    profileName
    El nombre de perfil para el bean de datos en la configuración.
    responseFormat
    El formato de respuesta que se utiliza para generar el resultado.
    paramOverrideMap
    Define los parámetros que desea añadir o sustituir del objeto de solicitud que está asociado a este manejador.
    Normalmente se utiliza si hay parámetros de vía de acceso o datos de entidad que desea incluir cuando correlaciona los parámetros de consulta con la entrada del mandato.
    La clave debe ser una cadena. El valor puede ser cualquier objeto de tipo.
    El valor puede ser nulo.
  3. public Response executeConfigBasedCommandWithContext(String commandInterfaceName, String profileName, String responseFormat, String storeId, Map<String, Object> paramOverrideMap)

    Este método configura la solicitud de inicio {@link BusinessContextService}, luego delega a * {@link #executeControllerCommand(String, String, TypedProperty, String)} y finalmente finaliza la solicitud BCS.

    Los parámetros siguientes están disponibles de forma predeterminada:
    commandInterfaceName
    El nombre de la interfaz de mandatos de controlador.
    profileName
    El nombre de perfil para el mandato de controlador en la configuración.
    responseFormat
    El formato de respuesta que se utiliza para generar el resultado.
    paramOverrideMap
    Define los parámetros que desea añadir o sustituir del objeto de solicitud que está asociado a este manejador.
    Normalmente se utiliza si hay parámetros de vía de acceso o datos de entidad que desea incluir cuando correlaciona los parámetros de consulta con la entrada del mandato.
    La clave debe ser una cadena. El valor puede ser cualquier objeto de tipo.
    El valor puede ser nulo.
  4. public JSONObject executeConfigBasedCommand(String pCmdInterfaceName, String profileName, String responseFormat, String storeId, Map<String, Object> paramOverrideMap) throws Exception

    Este método procesa una solicitud de mandato de controlador mediante las correlaciones de perfil basadas en configuración. Presupone que el llamante trata con el {@link BusinessContextService}.

    Los parámetros de entrada se completan automáticamente basándose en los parámetros de vía de acceso especificados en el URL, seguidos de los parámetros que se encuentran en el cuerpo de la solicitud.

    Se puede proporcionar un mapa de alteración temporal para inyectar más parámetros o sustituir los parámetros preexistentes.

    Aunque el ID de tienda se especifica en la llamada de método, no se incluye automáticamente en la lista de parámetros que se proporcionan para rellenar los setters del mandato. Debe añadirlo explícitamente al mapa de alteración temporal o hacer que se incluya con los parámetros de vía de acceso URL o el cuerpo de solicitud.

    pCmdInterfaceName
    El nombre de la interfaz de mandatos de controlador.
    profileName
    El nombre de perfil para el mandato de controlador en la configuración.
    responseFormat
    El formato de respuesta que se utiliza para generar el resultado.
    storeId
    El ID de la tienda.
    paramOverrideMap
    Define los parámetros que desea añadir o sustituir del objeto de solicitud que está asociado a este manejador.
    Normalmente se utiliza si hay parámetros de vía de acceso o datos de entidad que desea incluir cuando correlaciona los parámetros de consulta con la entrada del mandato.
    La clave debe ser una cadena. El valor puede ser cualquier objeto de tipo.
    El valor puede ser nulo.

Archivos de correlaciones

Los puntos incorporados y de extensión se componen de cuatro directorios:
Rest.war/WebContent/WEB-INF/config/beanMapping
Reservado para uso interno de HCL. Contiene los perfiles de bean de datos predeterminados.
Rest.war/WebContent/WEB-INF/config/beanMapping-ext
Se utiliza para publicar beans de datos nuevos y ampliar los beans de datos predeterminados.
Rest.war/WebContent/WEB-INF/config/commandMapping
Reservado para uso interno de HCL. Contiene los perfiles de mandatos de controlador predeterminados.
Rest.war/WebContent/WEB-INF/config/commandMapping-ext
Se utiliza para publicar mandatos de controlador nuevos y para ampliar los mandatos de controlador existentes.
Los archivos de configuración se nombran después del nombre completo del bean de datos o del mandato de controlador que exponen. Los perfiles de los directorios de extensión tienen prioridad sobre los de los directorios predeterminados. Esto le permite alterar los perfiles predeterminados. Sin embargo, el método preferido es subclasificar un bean de datos o crear una nueva interfaz de comando de controlador que extienda otra, y referirse al perfil original en su propio perfil.

Crear archivos de correlación

Puede crear los archivos de correlaciones XML, ya sea usando el programa de utilidad restClassicSampleGen, o manualmente.

Para obtener más información sobre el uso, consulte Creación de servicios REST utilizando el mandato de controlador basado en configuración y la infraestructura de correlación de beans de datos.

Archivo de correlación de beans de datos de ejemplo

El siguiente fragmento de código es un archivo de correlación de beans de datos de ejemplo para un perfil de ejemplo. Las entradas de método de salida pueden anidarse para permitir la recuperación de datos anidados a partir del resultado de otro método:
  • com.ibm.commerce.common.beans.StoreDataBean.xml

<?xml version="1.0" encoding="UTF-8"?>
<bean>
   <profiles>
      <profile name="IBM_Store_Summary">
         <inputs>
            <input methodName="setStoreId" inputName="storeId"/>
            <input methodName="setStoreRelationshipTypeName" inputName="storeRelationshipTypeName"/>
            <input methodName="setJspStoreDir" inputName="jspStoreDir"/>
         </inputs>
         <outputs>
            <output methodName="getStoreLevel" outputName="storeLevel"/>
            <output methodName="getFilePath" outputName="filePath"/>
            <output methodName="getJspPath" outputName="jspPath"/>
            <output methodName="getJspStoreDirFilePath" outputName="jspStoreDirFilePath"/>
            <output methodName="getJspStoreDir" outputName="jspStoreDir"/>
            <output methodName="getStoreLevel" outputName="storeLevel"/>
            <output methodName="getStoreType" outputName="storeType"/>
            <output methodName="getDirectory" outputName="directory"/>
            <output methodName="getRelatedStoresByStoreRelationshipTypeName" outputName="relatedStores"/>
            <output methodName="getStoreEntityDescriptionDataBean" outputName="storeEntityDescription">
               <output methodName="getDisplayName" outputName="displayName"/>
            </output>
         </outputs>
      </profile>
      <profile name="IBM_Store_DisplayName">
         <inputs>
            <input methodName="setStoreId" inputName="storeId"/>
            <input methodName="setStoreRelationshipTypeName" inputName="storeRelationshipTypeName"/>
            <input methodName="setJspStoreDir" inputName="jspStoreDir"/>
         </inputs>
         <outputs listName="resultList" >
            <output methodName="getStoreEntityDescriptionDataBean" outputName="storeEntityDescription">
               <output methodName="getDisplayName" outputName="displayName"/>
            </output>
         </outputs>
      </profile>
   </profiles>
</bean>

Archivo de correlación de mandatos de controlador de ejemplo

El siguiente fragmento de código es un ejemplo de archivo de correlación de mandato de controlador para un perfil de ejemplo:
  • com.ibm.commerce.catalogmanagement.commands.CatalogEntryUpdateCmd.xml

<?xml version="1.0" encoding="UTF-8"?>
<command>
   <inputs>
      <input inputName="auxdescription1" methodName="setAuxdescription1"/>
      <input inputName="auxdescription2" methodName="setAuxdescription2"/>
      <input inputName="catentryId" methodName="setCatentryId"/>
   </inputs>
   <profiles>
      <profile name="sample">
         <outputs>
            <output methodName="getCatentryId" outputName="catentryId"/>
         </outputs>
      </profile>
   </profiles>
</command>

Estructura de archivos de correlación

Los archivos de correlación utilizan la estructura siguiente:
Bean o mandato
El elemento raíz del archivo de configuración.
inputs
Lista de entradas para el bean de datos o el mandato de controlador. Las entradas se fusionan entre el valor predeterminado y la versión de extensión del archivo.
profiles
Lista de perfiles que se exponen como salida del bean de datos o del mandato de controlador.
entrada
Elemento que representa una entrada a un bean de datos o a un mandato de controlador.
methodName
El nombre del método al que se debe llamar en el bean de datos o el mandato de controlador para establecer la propiedad de entrada. Por ejemplo: setCatalogId.
inputName
El nombre de la entrada que se lee de la solicitud.
required
Especifica si la entrada es obligatoria (true o false). Las entradas obligatorias que faltan causan errores de solicitud.
perfil
Un perfil representa un subconjunto de los campos de salida de un bean de datos o de un comando de controlador que están expuestos. Diferentes perfiles tienen nombres diferentes. Todos los perfiles predeterminados tienen un nombre con el prefijo IBM_.
name
El nombre del perfil.
outputs
Una lista de salidas para el perfil.
outputs
Rodea una lista de elementos de salida.
Nombre de lista
Atributo opcional que le permite envolver la respuesta REST con una matriz del nombre proporcionado. Normalmente se utiliza en perfiles predeterminados con un nombre de resultList para llamadas REST que devuelven un único objeto para crear coherencia con las llamadas REST de tipo lista que devuelven una matriz resultList.
salida
Una salida representa un campo que ha completado la respuesta.
methodName
El nombre del método al que se debe llamar en el bean de datos o el mandato de controlador para obtener el valor de salida. El método debe devolver un tipo simple, como un número, un valor booleano, una fecha o una cadena. De lo contrario, debe ser un paso hacia una salida anidada. Si no lo hace, se producirá una excepción.
outputName
El nombre de la salida tal como aparece en la respuesta JSON o XML.
lista de otros nodos de salida
Las salidas pueden ser más detalladas en las relaciones de bean de datos para obtener propiedades de sus objetos incrustados.
ampliar
Identifica un perfil que amplía el perfil actual. Todas las entradas y salidas del perfil se añaden al perfil actual. Normalmente se utiliza para la personalización.
profileName
El nombre del perfil.
profileClass
El nombre de clase totalmente calificado que contiene el perfil que se va a ampliar. El valor predeterminado es el mismo nombre que la clase que representa el perfil actual. Habilita una extensión para ampliar un perfil predeterminado.