Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.
Se usó la API de Cloud Translation para traducir esta página.
Switch to English

Espacios de nombres administrados

Resumen

Introducción

Los espacios de nombres administrados se utilizan en el SDK de Weave para proporcionar tanto a los desarrolladores como a los integradores del SDK de Weave una guía y un subtexto anunciados sobre la designación de conjuntos de API particulares dentro del SDK, de modo que puedan planificar y predecir su ruta de migración entre las versiones de Weave SDK y, potencialmente administrar varias API de Weave simultáneas para un módulo determinado.

Designacion

Los espacios de nombres administrados se pueden administrar como una de cuatro designaciones:

Desarrollo

Cualquier espacio de nombres administrado con la designación de Desarrollo es una indicación para los desarrolladores e integradores de que las API que contiene están en desarrollo activo, pueden estar sujetas a cambios y no cuentan con soporte oficial. En general, se desaconseja a los integradores que utilicen estas API a menos que se les indique específicamente que lo hagan.

próximo

Cualquier espacio de nombres administrado con la designación Next es una indicación para los desarrolladores e integradores de que las API que contiene, aunque han completado en gran medida el desarrollo activo, aún pueden estar sujetas a cambios y son compatibles con fines de evaluación temprana. Las API así designadas representan el próximo frente evolutivo en una API de Weave SDK y se convertirán en las API predeterminadas actuales en un ciclo de versiones importante en el futuro inmediato o próximo.

Es posible que exista compatibilidad con versiones anteriores, tanto desde una perspectiva de protocolo API como por cable, pero no está garantizada en las API así designadas.

La designación de espacio de nombres administrado Next proporciona de manera efectiva a los desarrolladores e integradores una vista hacia dónde se dirige el SDK de Weave al insinuar lo que se convertirá en la API predeterminada actual en una versión futura.

La designación del espacio de nombres administrado Siguiente es opcional, de modo que un espacio de nombres administrado puede pasar a través de un ciclo de vida sin usarlo (consulte Ciclo de vida del espacio de nombres administrado ).

Actual

Cualquier espacio de nombres administrado con la designación Actual o cualquier espacio de nombres no administrado (es decir, que carece de una designación de espacio de nombres administrado) representa la API admitida oficial, predeterminada y actual para esa parte o módulo del SDK de Weave. Si bien aún puede haber mejoras continuas en dichas API, los cambios serán en gran medida incrementales y se debe mantener la compatibilidad con versiones anteriores, tanto API como por cable.

La designación del espacio de nombres administrado actual es opcional, de modo que un espacio de nombres administrado puede pasar por un ciclo de vida sin usarlo (consulte Ciclo de vida del espacio de nombres administrado ). De hecho, cualquier espacio de nombres no administrado es implícitamente actual.

Legado

Cualquier espacio de nombres administrado con la designación Legacy es una indicación para los desarrolladores e integradores de que las API que contiene han quedado obsoletas y se han reemplazado por una API nueva y actual. Estas API representan lo que antes era la API actual.

Las API así designadas desaparecerán por completo en la próxima versión importante de Weave SDK; en consecuencia, los desarrolladores e integradores deben establecer planes para la migración fuera de estas API si pretenden permanecer a la vanguardia de las versiones de Weave SDK.

Ciclo de vida del espacio de nombres administrado

La siguiente figura ilustra el ciclo de vida de un espacio de nombres administrado a medida que pasa de Desarrollo y, potencialmente, a Heredado:

.-------------.      .- - - .      .- - - - -.      .--------.
| Development | -.->   Next   -.->   Current   ---> | Legacy |
'-------------'  |   '- - - '  |   ' - - - - '      '--------'
                 |             |
                 '-------------'

Si se emplea, el ciclo de vida del espacio de nombres administrado comienza con la designación de Desarrollo.

Cuando se completa el desarrollo y el código está listo para evaluación e integración, la designación migra a Siguiente o Actual. Alternativamente, la designación puede eliminarse por completo y dejar de emplearse el espacio de nombres administrado, lo que hace que la designación sea implícitamente Actual.

Si el código va a convivir y aún no suplanta al código actual, entonces la designación debería migrar a Siguiente. Si el código sustituirá al código actual, la designación debería migrar a Current.

Usando la designación Siguiente, después de que el código haya pasado por el número deseado de ciclos de publicación y evaluación, la designación migra a Actual o, nuevamente, la Designación puede eliminarse por completo.

Con la designación actual, si el código debe ser reemplazado por un código nuevo pero aún debe mantenerse durante varios ciclos de lanzamiento, la designación migra a Legacy.

De la designación Legacy, el código finalmente se elimina del Weave SDK por completo.

Usar espacios de nombres administrados

Los usuarios de Weave SDK pueden interactuar con espacios de nombres administrados ya sea como desarrolladores , extendiendo y manteniendo el código existente, o como integradores , integrando Weave en su propia aplicación, plataforma y código de sistema. Las siguientes dos secciones detallan las recomendaciones para tratar con los espacios de nombres administrados por Weave desde esas dos perspectivas.

Uso de espacios de nombres administrados como desarrollador

Un enfoque clave del desarrollador de Weave SDK es mejorar y desarrollar nuevas API y funcionalidades de Weave SDK y, en muchos casos, al mismo tiempo admite las implementaciones de API y funcionalidades existentes.

Cuando no es posible satisfacer ambas áreas de enfoque de manera compatible con versiones anteriores dentro de la misma API, los espacios de nombres administrados proporcionan un mecanismo para administrar estas API en paralelo, de una manera que no interrumpe las implementaciones de API y funcionalidad existentes.

Como ejemplo práctico, suponga un perfil de Weave, Mercury, que existe actualmente bajo la siguiente jerarquía de espacio de nombres no administrada:

namespace nl {
namespace Weave {
namespace Profiles {
namespace Mercury {

// ...

}; // namespace Mercury
}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

y los siguientes encabezados públicos:

  • Weave / Profiles / Mercury / Mercury.hpp
  • Weave / Profiles / Mercury / Bar.hpp
  • Tejido / Perfiles / Mercurio / Foo.hpp
  • Tejido / Perfiles / Mercurio / Foobar.hpp

donde Mercury.hpp es el encabezado "paraguas" del módulo. La mayoría de los integradores simplemente incluyen el encabezado del módulo "paraguas" como se muestra:

#include 

Sin embargo, el desarrollo de Mercury ha llegado a un punto en el que existe la necesidad de desarrollar una próxima generación de API y, potencialmente, el protocolo over-the-wire que no son compatibles con las implementaciones existentes. El uso de espacios de nombres administrados puede ayudar a lograr esto sin romper estas implementaciones existentes.

Mover el espacio de nombres existente al actual

Con el objetivo de continuar respaldando la versión actual de la API y la funcionalidad para las integraciones implementadas existentes, la primera tarea es mover el código actual:

% cd src/lib/profiles/mercury
% mkdir Current
% mv Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp *.cpp Current/

Tenga en cuenta que, además de mover los archivos, el encabezado incluye protecciones para los archivos movidos también debe cambiarse el nombre, posiblemente decorándolos con '_CURRENT', ya que los nuevos archivos con el mismo nombre se crearán en su lugar debajo.

Con el código movido, el siguiente paso es administrar el espacio de nombres con la designación apropiada, aquí 'Actual'. Primero, cree un encabezado que defina el espacio de nombres administrado, como 'Current / MercuryManagedNamespace.hpp'. Es preferible crear un encabezado de este tipo a repetir y duplicar este contenido en cada archivo de encabezado cuando hay varios archivos de encabezado.

% cat << EOF > Current/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current
#error Compiling Weave Mercury current-designation managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Current
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
EOF

A continuación, incluya este encabezado antes de otras directivas de inclusión específicas del módulo en los encabezados existentes. Por ejemplo:

#include 

#include 

Crear encabezados de compatibilidad

Sin embargo, mover los encabezados existentes a una nueva ubicación y administrar su espacio de nombres por sí solo no es suficiente para garantizar que las implementaciones existentes funcionen sin cambios, ya que todos usan directivas de inclusión que especifican los encabezados que se acaban de mover arriba.

Para solucionar esto, se deben crear encabezados de contenedor de compatibilidad con nombres que coincidan con los que se acaban de mover.

% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp

Si solo se está creando un espacio de nombres administrado designado por Actual sin crear un espacio de nombres administrado designado por Desarrollo o Siguiente para acompañarlo, el contenido de estos archivos puede consistir simplemente en una protección de inclusión de encabezado y una directiva de inclusión que especifica el encabezado recién movido de el mismo nombre:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Sin embargo, si también se está creando un espacio de nombres administrado designado por Desarrollo o Siguiente para dar cabida a un desarrollo nuevo e incompatible, es necesario hacer algo un poco más complejo.

Como antes, se crea un encabezado para la configuración del espacio de nombres administrado, aquí como MercuryManagedNamespace.hpp. Nuevamente, esto es preferible a repetir y duplicar este contenido en cada archivo de encabezado cuando hay varios archivos de encabezado.

% cat << EOF > MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE)                             \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current) \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development)
#error "WEAVE_CONFIG_MERCURY_NAMESPACE defined, but not as namespace kWeaveManagedNamespace_Current or kWeaveManagedNamespace_Development"
#endif

#if !defined(WEAVE_CONFIG_MERCURY_NAMESPACE)
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
EOF

Tenga en cuenta que, de forma predeterminada, como se desea, la designación del espacio de nombres administrado es 'Actual' si no se ha definido ninguna configuración.

Con este encabezado en su lugar, los encabezados del contenedor de compatibilidad ahora se pueden editar para que contengan:

#include 

#if WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development
#include 
#else
#include 
#endif // WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development

o lo que sea apropiado para el caso de uso de administración de espacio de nombres en cuestión.

Crear contenido de desarrollo

En este punto, la infraestructura ya está en su lugar para comenzar a desarrollar nuevas funcionalidades y API junto con las existentes.

% mkdir Development
% touch Development/Mercury.hpp Development/Bar.hpp Development/Foo.hpp Development/Foobar.hpp
% cat << EOF > Development/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP

#include 

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development
#error Compiling Weave Mercury development-designated managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Development
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Development
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
EOF

Por supuesto, si un módulo es mucho más simple que el ejemplo presentado aquí y no tiene muchas clases, fuentes, archivos o encabezados, todo esto podría lograrse en el mismo archivo de encabezado sin mover archivos y crear múltiples configuraciones independientes y encabezados de compatibilidad. . Sin embargo, con este ejemplo complejo, debería inspirar soluciones de espacios de nombres administrados a lo largo de un espectro que va de complejo a simple.

Uso de espacios de nombres administrados como integrador

Un enfoque clave del integrador de Weave SDK es incluir los encabezados de API públicos de Weave SDK apropiados y la integración y el desarrollo de aplicaciones contra ellos.

Como ejemplo práctico, asuma nuevamente un perfil de Weave, Mercury, que tiene espacios de nombres administrados designados como Next, Current y Legacy, cuyos encabezados públicos están estructurados de la siguiente manera:

  • Weave / Profiles / Mercury / Mercury.hpp
  • Weave / Profiles / Mercury / Bar.hpp
  • Tejido / Perfiles / Mercurio / Foo.hpp
  • Tejido / Perfiles / Mercurio / Foobar.hpp
  • Weave / Profiles / Mercury / Next / Mercury.hpp
  • Weave / Profiles / Mercury / Next / Bar.hpp
  • Tejido / Perfiles / Mercurio / Siguiente / Foo.hpp
  • Tejido / Perfiles / Mercurio / Siguiente / Foobar.hpp
  • Weave / Profiles / Mercury / Current / Mercury.hpp
  • Tejido / Perfiles / Mercurio / Corriente / Bar.hpp
  • Tejido / Perfiles / Mercurio / Actual / Foo.hpp
  • Tejido / Perfiles / Mercurio / Actual / Foobar.hpp
  • Weave / Profiles / Mercury / Legacy / Mercury.hpp
  • Weave / Profiles / Mercury / Legacy / Bar.hpp
  • Weave / Profiles / Mercury / Legacy / Foo.hpp
  • Weave / Profiles / Mercury / Legacy / Foobar.hpp

donde Mercury.hpp es el encabezado "paraguas" del módulo.

A menos que el caso de uso en cuestión motive la inclusión de un módulo administrado de espacio de nombres dentro de Weave explícitamente, por ejemplo:

#include 

Es mejor hacer referencia a los encabezados públicos del módulo Weave por sus rutas predeterminadas no administradas (por ejemplo, Weave / Profiles / Mercury / Mercury.hpp). Hacerlo permite seguir una progresión del desarrollo de API sin cambiar continuamente las directivas de inclusión de un proyecto a medida que esas API fluyen a través del ciclo de vida administrado.

Siguiendo esta estrategia, las implementaciones pueden redirigir su código a una designación de espacio de nombres administrado diferente, la designación Actual, por ejemplo, especificando la configuración deseada en el preprocesador C / C ++. Esto se puede hacer en la línea de comandos, en el código fuente o en una configuración o encabezado de prefijo:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

y use la ruta de inclusión no administrada / no calificada:

#include 

Cuando, y si, la designación del espacio de nombres administrado cambia para las API de destino, por ejemplo de Actual a Legacy, simplemente reoriente ajustando la definición del preprocesador:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy