Clases de envoltura Java

Al solicitar que un componente de programa se genere como envoltura Java, EGL produce una clase de envoltura para cada uno de los siguientes elementos:

Las descripciones subsiguientes hacen referencia a las clases de envoltura de un programa determinado como clase de envoltura de programa, clases de envoltura de parámetro, clases de envoltura de matriz dinámica y clases de envoltura de matriz de elementos subestructurada.

EGL genera una clase BeanInfo para cada clase de envoltura de parámetro, clase de envoltura de matriz dinámica o clase de envoltura de matriz de elementos subestructurada. La clase BeanInfo permite utilizar la clase de envoltura relacionada como bean Java compatible con Java. Probablemente, no interaccionará con la clase BeanInfo.

Cuando genera una envoltura, la lista de parámetros del programa llamado no puede incluir parámetros de tipo BLOB, CLOB, STRING, Dictionary, ArrayDictionary o registro no fijo.

Visión general de la utilización de las clases de envoltura

Para utilizar las clases de envoltura para comunicarse con un programa generado con VisualAge Generator, haga lo siguiente en el programa nativo Java:
  • Cree una instancia de una clase (una subclase de CSOPowerServer) para suministrar servicios de middleware, como por ejemplo conversión de datos entre el código nativo Java y un programa generado:
      import com.ibm.javart.v6.cso.*;
    
      public class MyNativeClass 
      {
        /* declarar una variable para middleware */
        CSOPowerServer powerServer = null;
        
        try
        {
      	   powerServer = new CSOLocalPowerServerProxy();
        }
        catch (CSOException exception)
        {
          System.out.println("Error al inicializar el middleware"
            + exception.getMessage());
          System.exit(8);
        }
      }
  • Cree una instancia de una clase de envoltura de programa para hacer lo siguiente:
    • Asignar estructuras de datos, incluidas las matrices dinámicas si las hay
    • Proporcionar acceso a los métodos que, a su vez, acceden al programa generado
    La llamada al constructor incluye el objeto de middleware:
      myProgram = new MyprogramWrapper(powerServer);
  • Declare las variables que se basan en las clases de envoltura de parámetro:
      Mypart  myParm = myProgram.getMyParm();
      Mypart2 myParm2 = myProgram.getMyParm2(); 
    Si el programa contiene parámetros que son matrices dinámicas, declare variables adicionales cada una de las cuales se base en una clase de envoltura de matriz dinámica:
      myRecArrayVar myParm3 = myProgram.getMyParm3();

    Para obtener detalles acerca de cómo interactuar con matrices dinámicas, consulte el apartado Clases de envoltura de matriz dinámica.

  • En la mayoría de los casos, (como en el paso anterior), utilizará las variables de parámetro para hacer referencia y cambiar la memoria asignada en el objeto de envoltura de programa
  • Defina un ID de usuario y contraseña, pero solamente en estos casos:
    • La envoltura Java accede a un programa basado en iSeries mediante iSeries Toolbox para Java; o bien
    • El programa generado se ejecuta en una región CICS para z/OS que autentica el acceso remoto.

    El ID de usuario y la contraseña no se utilizan para el acceso a bases de datos.

    El ID de usuario y la contraseña se establecen y revisan mediante la variable callOptions del objeto programa, como en este ejemplo:
      myProgram.callOptions.setUserID("myID");
      myProgram.callOptions.setPassword("myWord");
      myUserID = myProgram.callOptions.getUserID();
      myPassword = myProgram.callOptions.getPassword();
  • Acceda al programa generado, en la mayoría de los casos invocando el método execute del objeto de envoltura de programa:
      myProgram.execute();  
  • Utilice el objeto de middleware para establecer el control de transacción de base de datos, pero sólo en la siguiente situación:
    • El objeto de envoltura de programa accede a un programa generado en CICS para z/OS o accede a un programa COBOL basado en iSeries mediante IBM Toolbox para Java. En el segundo caso, el valor remoteComType para la llamada es JAVA400.
    • En el componente de opciones de enlace utilizado para generar las clases de envoltura, ha especificado que la unidad de trabajo de base de datos está bajo el control del cliente (en este caso, la envoltura); para obtener detalles, consulte la referencia a luwControl en elemento callLink.
    Si la unidad de trabajo de base de datos está bajo el control del cliente, el proceso incluye la utilización de métodos de compromiso y retrotracción del objeto de middleware:
      powerServer.commit();
      powerServer.rollback();
  • Cierre el objeto de middleware y permita la recogida de basura:
      if (powerServer != null)
      {
        try
        {
          powerServer.close();
          powerServer = null;
        }
    
        catch(CSOException error)
        {
          System.out.println("Error al cerrar el middleware"
            + error.getMessage());
          System.exit(8);
        }
      }

La clase de envoltura de programa

la clase de envoltura de programa incluye una variable de instancia privada para cada parámetro del programa generado. Si el parámetro es un registro o un formulario, la variable hace referencia a una instancia de la clase de envoltura de parámetro relacionada. Si el parámetro es un elemento de datos, la variable tiene un tipo primitivo Java.

Al final de esta página de la ayuda figura una tabla que describe las conversiones entre EGL y los tipos Java.

Un objeto de envoltura de programa incluye los siguientes métodos públicos:
  • Métodos get y set para cada parámetro, donde el formato del nombre es el siguiente:
      finalidadnombreParámetro()
    finalidad
    La palabra get o set
    nombreParámetro
    Nombre del elemento de datos, registro o formulario; la primera letra es mayúscula, y el aspecto de las demás letras está determinado por el convenio de denominación descrito en el apartado Convenios de denominación de las clases de envoltura Java
  • Un método execute para llamar al programa; este método se utiliza si los datos que se pasarán como argumentos en la llamada están en la memoria asignada al objeto de envoltura de programa
En lugar de asignar valores a las variables de instancia, puede hacer lo siguiente:
  • Asigne memoria a los objetos de envoltura de parámetro, objetos de envoltura de matriz dinámica y tipos primitivos
  • Asigne valores a la memoria que ha asignado
  • Pase esos valores al programa invocando el método call del objeto de envoltura de programa en lugar de invocar el método execute
El objeto de envoltura de programa también incluye la variable callOptions, que tiene las siguientes finalidades:
  • Si ha generado la envoltura Java para que las opciones de enlace de la llamada se establezcan durante la generación, la variable callOptions contendrá la información de enlace. Para obtener detalles acerca de cuándo se establecen las opciones de enlace, consulte remoteBind en el elemento callLink.
  • Si ha generado la envoltura Java para que las opciones de enlace de la llamada se establezcan durante la ejecución, la variable callOptions contendrá el nombre del archivo de propiedades de enlace. El nombre del archivo es LO.properties, donde LO es el nombre del componente de opciones de enlace utilizado para la generación.
  • En cualquier caso, la variable callOptions proporciona los siguientes métodos para establecer u obtener un ID de usuario y contraseña:
      setPassword(contraseña)
      setUserid(IDusuario) 
      getPassword()
      getUserid()
    El ID de usuario y contraseña se utilizan al establecer la propiedad remoteComType del elemento callLink en uno de los siguientes valores:
    • CICSECI
    • CICSJ2C
    • JAVA400
Finalmente, considere la siguiente situación: el código nativo Java requiere notificación cuando se efectúa un cambio en un parámetro de tipo primitivo. Para hacer posible esta notificación, el código nativo se registra como escuchador invocando el método addPropertyChangeListener del objeto de envoltura de programa. En este caso, cualquiera de las siguientes situaciones desencadena el evento PropertyChange que hace que el código nativo reciba la notificación durante la ejecución:
  • El código nativo invoca un método set en un parámetro de tipo primitivo
  • El código generado devuelve datos cambiados a un parámetro de tipo primitivo

El evento PropertyChange se describe en la especificación JavaBean de Sun Microsystems, Inc.

El conjunto de clases de envoltura de parámetro

Una clase de envoltura de parámetro se produce para cada registro declarado como parámetro en el programa generado. En el caso más común, una clase de envoltura de parámetro se utiliza sólo para declarar una variable que hace referencia al parámetro, como en el ejemplo siguiente:
  Mypart myRecWrapperObject = myProgram.getMyrecord();

En este caso, se utiliza la memoria asignada por el objeto de envoltura de programa.

También puede utilizar la clase de envoltura de parámetro para declarar memoria, que es necesario si invoca al método call (en lugar de al método execute) del objeto programa.

La clase de envoltura de parámetro incluye un conjunto de variables de instancia privada, como las siguientes:
  • Una variable de un tipo primitivo Java para cada de los elementos de estructura de bajo nivel del parámetro, pero sólo para los elementos de estructura que no sean matrices ni estén dentro de una matriz subestructurada
  • Una matriz de tipo primitivo Java para cada elemento de estructura EGL que sea una matriz no subestructurada
  • Un objeto de una clase de matriz interna para cada matriz subestructurada que no esté dentro de una matriz subestructurada; la clase interna puede tener clases internas anidadas para representar matrices subestructuradas subordinadas
La clase de envoltura de parámetro incluye varios métodos públicos:
  • Un conjunto de métodos get y set permite obtener y establecer cada variable de instancia. El formato de cada nombre de método es el siguiente:
      finalidadnombreEE()
    finalidad
    La palabra get o set.
    nombreEE
    Nombre del elemento de estructura. La primera letra es mayúscula, y el aspecto de las demás letras está determinado por el convenio de denominación descrito en el apartado Convenios de denominación de las clases de envoltura Java.
    Nota: Los elementos de estructura que declare como rellenadores se incluirán en la llamada de programa; pero las clase de envoltura de matriz no incluyen métodos get y set públicos para dichos elementos de estructura.
  • El método equals permite determinar si los valores almacenados en otro objeto de la misma clase son idénticos a los valores almacenados en el objeto de envoltura de parámetro. El método devuelve true sólo si las clases y valores son idénticos.
  • El método addPropertyChangeListener se invoca si el programa requiere notificación de un cambio en una variable de un tipo primitivo Java.
  • Un segundo conjunto de métodos get y set permite obtener y establecer los indicadores de nulo de cada elemento de estructura de un parámetro de registro SQL. El formato de cada uno de estos nombres de método es el siguiente:
      finalidadnombreEENullIndicator()
    finalidad
    La palabra get o set.
    nombreEE
    Nombre del elemento de estructura. La primera letra es mayúscula, y el aspecto de las demás letras está determinado por el convenio de denominación descrito en el apartado Convenios de denominación de las clases de envoltura Java.

El conjunto de clases de envoltura de matriz de elementos subestructurada

Una clase de envoltura de matriz de elementos subestructurada es una clase interna de una clase de parámetro y representa una matriz subestructurada del parámetro relacionado. La clase de envoltura de matriz de elementos subestructurada incluye un conjunto de variables de instancia privada que hacen referencia a los elementos de estructura que se encuentran en la propia matriz y debajo de ella:
  • Una variable de un tipo primitivo Java para cada de los elementos de estructura de bajo nivel de la matriz, pero sólo para los elementos de estructura que no sean matrices ni estén dentro de una matriz subestructurada
  • Una matriz de tipo primitivo Java para cada elemento de estructura EGL que sea una matriz no subestructurada
  • Un objeto de una clase de envoltura de matriz de elementos subestructurada interna para cada matriz subestructurada que no esté dentro de una matriz subestructurada; la clase interna puede tener clases internas anidadas para representar matrices subestructuradas subordinadas
La clase de envoltura de matriz de elementos subestructurada incluye los siguientes métodos:
  • Un conjunto de métodos get y set para cada variable de instancia.
    Nota: Los elementos de estructura que declare como rellenadores se utilizarán en la llamada de programa; pero las clase de envoltura de matriz de elementos subestructurada no incluyen métodos get y set públicos para dichos elementos de estructura.
  • El método equals permite determinar si los valores almacenados en otro objeto de la misma clase son idénticos a los valores almacenados en el objeto de envoltura de matriz de elementos subestructurada. El método devuelve true sólo si las clases y valores son idénticos.
  • El método addPropertyChangeListener se invoca si el programa requiere notificación de un cambio en una variable de un tipo primitivo Java.
En la mayoría de los casos, el nombre de la clase de envoltura de matriz de elementos subestructurada de mayor nivel de una clase de envoltura de parámetro tiene el siguiente formato:
  nombreClaseParámetro.nombreClaseMatriz
Observe el siguiente registro, por ejemplo:
  Record CompanyPart type basicRecord
  10 Departments CHAR(20)[5];
     20 CountryCode CHAR(10);
     20 FunctionCode CHAR(10)[3];
        30 FunctionCategory CHAR(4);
        30 FunctionDetail CHAR(6);
  end

Si el parámetro Company se basa en CompanyPart, se utilizará la serie CompanyPart.Departments como el nombre de la clase interna.

Una clase interna de una clase interna amplía la utilización de una sintaxis con puntos. En este ejemplo, se utiliza el símbolo CompanyPart.Departments.Functioncode como el nombre de la clase interna de Departments.

Para obtener más detalles acerca de cómo denominar las clases de envoltura de matriz de elementos subestructurada, consulte el apartado Salida de la generación de envoltura Java.

Clases de envoltura de matriz dinámica

Una clase de envoltura de matriz dinámica se produce para cada matriz dinámica declarada como parámetro en el programa generado. Observe la siguiente firma de programa EGL:
  Program myProgram(intParms int[], recParms MyRec[])

El nombre de las clases de envoltura de matriz dinámica es IntParmsArray y MyRecArray.

Una clase de envoltura de matriz dinámica se utiliza para declarar una variable que hace referencia a la matriz dinámica, como en los ejemplos siguientes:
  IntParmsArray myIntArrayVar = myProgram.getIntParms();
  MyRecArray    myRecArrayVar = myProgram.getRecParms();

Después de declarar las variables para cada matriz dinámica, puede añadir elementos:

  // la adición a una matriz de tipos primitivos Java 
  // es un proceso de un solo paso
  myIntArrayVar.add(new Integer(5));

  // la adición a una matriz de registros o formularios 
  // requiere varios pasos; en este caso, 
  // empiece por asignar un objeto de registro nuevo
  MyRec myLocalRec = (MyRec)myRecArrayVar.makeNewElement();
  
  // los pasos para asignar valores no se muestran 
  // en este ejemplo, pero, después de asignar valores, 
  // añada el registro a la matriz
  myRecArrayVar.add(myLocalRec);

  // a continuación, ejecute el programa
  myProgram.execute();

  // cuando el programa efectúe el retorno, puede determinar 
  // el número de elementos de la matriz
  int myIntArrayVarSize = myIntArrayVar.size();

  // obtener el primer elemento de la matriz de enteros 
  // y convertirlo temporalmente a un objeto Integer
  Integer firstIntElement = (Integer)myIntArrayVar.get(0);

  // obtener el segundo elemento de la matriz de registros
  // y convertirlo temporalmente a un objeto MyRec
  MyRec secondRecElement = (MyRec)myRecArrayVar.get(1);

Como indica el ejemplo, EGL proporciona varios métodos para manipular las variables que haya declarado.

Método de la clase de matriz dinámica Finalidad
add(int, Objeto) Insertar un objeto en la posición especificada por int y desplazar el elemento actual y los sucesivos hacia la derecha.
add(Objeto) Añadir un objeto al final de la matriz dinámica.
addAll(ListaMatrices) Añadir un objeto ArrayList al final de la matriz dinámica.
get() Recuperar el objeto ArrayList que contiene todos los elementos de la matriz.
get(int) Recuperar el elemento que está en la posición especificada por int
makeNewElement() Asignar un elemento nuevo del tipo específico de la matriz y recuperarlo sin añadirlo a la matriz dinámica.
maxSize() Recuperar un entero que indica el número máximo (pero no real) de elementos de la matriz dinámica.
remove(int) Eliminar el elemento que está en la posición especificada por int
set(ArrayList) Utilizar el objeto ArrayList especificado como sustitución de la matriz dinámica.
set(int, Objeto) Utilizar el objeto especificado como sustitución del elemento que está en la posición especificada por int
size() Recuperar el número de elementos que se encuentran en la matriz dinámica.
En los siguientes casos, entre otros, se producen excepciones:
  • Si especifica un índice no válido en el método get o set
  • Si intenta añadir (o establecer) un elemento que pertenece a una clase incompatible con la clase de cada uno de los elementos de la matriz
  • Si intenta añadir elementos a una matriz dinámica cuando el tamaño máximo de la matriz no puede dar soporte al aumento; y si el método addAll falla por esta razón, el método no añade elementos

Convenios de denominación de las clases de envoltura Java

EGL crea los nombres de acuerdo con estas normas:
  • Si el nombre está todo en mayúsculas, debe especificarlo todo en minúsculas.
  • Si el nombre es una palabra clave, especifique un subrayado delante
  • Si el nombre incluye un guión o un subrayado, elimine ese carácter y especifique la letra siguiente en mayúsculas
  • Si el nombre incluye un signo de dólar ($), un signo de arroba (@) o un signo de almohadilla (#), sustituya cada uno de esos caracteres por un doble subrayado (__) y coloque un subrayado (_) delante del nombre.
  • Si el nombre de utiliza como nombre de clase, especifique la primera letra en mayúscula.
Las clases de envoltura de matriz dinámica están sujetas a las siguientes normas:
  • En la mayoría de los casos, el nombre de una clase se basa en el nombre de la declaración de componente (elemento de datos, formulario o registro) que es la base de cada uno de los elementos de la matriz. Por ejemplo, si un componente de registro se denomina MyRec y la declaración de matriz es recParms myRec[], la clase de envoltura de matriz dinámica relacionada se denominará MyRecArray.
  • Si la matriz se basa en una declaración de elemento que no tiene ninguna declaración de componente relacionada, el nombre de la clase de matriz dinámica se basa en el nombre de la matriz. Por ejemplo, si la declaración de matriz es intParms int[], la clase de envoltura de matriz dinámica relacionada se denominará IntParmsArray.

Referencias cruzadas de tipos de datos

La tabla siguiente indica la relación entre los tipos primitivos EGL del programa generado y los tipos de datos Java de la envoltura generada.

Tipo primitivo EGL Longitud en caracteres o dígitos Longitud en bytes Decimales Tipo de datos Java Precisión máxima en Java
CHAR 1-32767 2-32766 NA String NA
DBCHAR 1-16383 1-32767 NA String NA
MBCHAR 1-32767 1-32767 NA String NA
UNICODE 1-16383 2-32766 NA String NA
HEX 2-75534 1-32767 NA byte[] NA
BIN, SMALLINT 4 2 0 short 4
BIN, INT 9 4 0 int 9
BIN, BIGINT 18 8 0 long 18
BIN 4 2 >0 float 4
BIN 9 4 >0 double 15
BIN 18 8 >0 double 15
DECIMAL, PACF 1-3 1-2 0 short 4
DECIMAL, PACF 4-9 3-5 0 int 9
DECIMAL, PACF 10-18 6-10 0 long 18
DECIMAL, PACF 1-5 1-3 >0 float 6
DECIMAL, PACF 7-18 4-10 >0 double 15
NUM, NUMC 1-4 1-4 0 short 4
NUM, NUMC 5-9 5-9 0 int 9
NUM, NUMC 10-18 10-18 0 long 18
NUM, NUMC 1-6 1-6 >0 float 6
NUM, NUMC 7-18 7-18 >0 double 15

Tareas relacionadas
Generar envolturas Java

Comentarios
(C) Copyright IBM Corporation 2000, 2005. Reservados todos los derechos.