O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.
Esta página foi traduzida pela API Cloud Translation.
Switch to English

Namespaces gerenciados

Resumo

Introdução

Os namespaces gerenciados são usados ​​no SDK do Weave para fornecer aos desenvolvedores e integradores do SDK do Weave orientação anunciada e subtexto sobre a designação de conjuntos de API específicos dentro do SDK, de modo que eles possam planejar e prever seu caminho de migração nas versões do SDK do Weave e, potencialmente, gerenciar várias APIs do Weave simultâneas para um determinado módulo.

Designação

Os namespaces gerenciados podem ser gerenciados como uma de quatro designações:

Desenvolvimento

Qualquer namespace gerenciado com a designação de desenvolvimento é uma indicação para desenvolvedores e integradores de que as APIs contidas estão em desenvolvimento ativo, podem estar sujeitas a alterações e não são oficialmente suportadas. Os integradores geralmente são desencorajados de usar essas APIs, a menos que sejam especificamente orientados a fazê-lo.

Próximo

Qualquer namespace gerenciado com a designação Next é uma indicação para desenvolvedores e integradores de que as APIs contidas, embora tenham concluído o desenvolvimento ativo em grande parte, ainda podem estar sujeitas a alterações e são suportadas para fins de avaliação inicial. As APIs assim designadas representam a próxima frente evolutiva em uma API do SDK do Weave e se tornarão as APIs padrão atuais em um grande ciclo de lançamentos no futuro imediato ou próximo.

A compatibilidade com versões anteriores, tanto da perspectiva da API quanto do protocolo over-the-wire, pode existir, mas não é garantida nas APIs assim designadas.

A designação de namespace gerenciado Next fornece efetivamente aos desenvolvedores e integradores uma visão para onde o SDK do Weave está se dirigindo, sugerindo o que se tornará a API padrão atual em uma versão futura.

A designação de namespace gerenciado Next é opcional, de forma que um namespace gerenciado pode passar por um ciclo de vida sem usá-lo (consulte Managed Namespace Lifecycle ).

Atual

Qualquer namespace gerenciado com a designação Current ou qualquer namespace não gerenciado (ou seja, sem uma designação de namespace gerenciado) representa a API atual, padrão e oficial com suporte para essa parte ou módulo do Weave SDK. Embora ainda possa haver aprimoramentos em andamento para essas APIs, as alterações serão em grande parte incrementais e a compatibilidade com versões anteriores, tanto da API quanto através da rede, deve ser mantida.

A designação de namespace gerenciado atual é opcional, de modo que um namespace gerenciado pode fazer a transição por meio de um ciclo de vida sem usá-lo (consulte Ciclo de vida do namespace gerenciado ). Na verdade, qualquer namespace não gerenciado é implicitamente Current.

Legado

Qualquer namespace gerenciado com a designação Legacy é uma indicação para desenvolvedores e integradores de que as APIs contidas foram descontinuadas e substituídas por uma API nova e atual. Essas APIs representam o que antes era a API atual.

APIs assim designadas desaparecerão completamente no próximo grande lançamento do Weave SDK; consequentemente, os desenvolvedores e integradores devem estabelecer planos para a migração dessas APIs se pretendem permanecer com a vanguarda das versões do SDK do Weave.

Ciclo de vida do namespace gerenciado

A figura a seguir ilustra o ciclo de vida de um namespace gerenciado durante a transição de Desenvolvimento e, potencialmente, para Legado:

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

Se for empregado, o ciclo de vida do namespace gerenciado começa com a designação de Desenvolvimento.

Quando o desenvolvimento é concluído e o código está pronto para avaliação e integração, a designação migra para Próximo ou Atual. Como alternativa, a designação pode ser totalmente descartada e o namespace gerenciado não é mais empregado, tornando a designação implicitamente Atual.

Se o código deve viver junto e ainda não suplantar o código atual, a designação deve migrar para Next. Se o código deve substituir o código atual, a designação deve migrar para Atual.

Usando a designação Next, após o código ter passado pelo número desejado de ciclos de lançamento e avaliação, a designação migra para Atual ou, novamente, a Designação pode ser totalmente descartada.

Usando a designação Atual, se o código for suplantado por um novo código, mas ainda precisar ser mantido por vários ciclos de lançamento, a designação migra para o Legacy.

A partir da designação Legacy, o código é eventualmente removido do Weave SDK por completo.

Usando namespaces gerenciados

Os usuários do Weave SDK podem interagir com namespaces gerenciados como desenvolvedor , estendendo e mantendo o código existente, ou como integrador , integrando o Weave em seu próprio aplicativo, plataforma e código de sistema. As duas seções a seguir detalham recomendações para lidar com namespaces gerenciados pelo Weave a partir dessas duas perspectivas.

Usando namespaces gerenciados como desenvolvedor

Um foco principal do desenvolvedor do SDK do Weave é aprimorar e desenvolver novas APIs e funcionalidades do SDK do Weave, ao mesmo tempo em que, em muitos casos, oferece suporte às implantações de API e funcionalidade existentes.

Onde não é possível satisfazer essas duas áreas de foco de maneira compatível com versões anteriores na mesma API, os namespaces gerenciados fornecem um mecanismo para gerenciar essas APIs em paralelo, de uma forma que não interrompa as implementações de API e funcionalidade existentes.

Como exemplo prático, suponha que um perfil Weave, Mercury, exista atualmente na seguinte hierarquia de namespace não gerenciada:

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

// ...

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

e os seguintes cabeçalhos públicos:

  • Weave / Profiles / Mercury / Mercury.hpp
  • Weave / Profiles / Mercury / Bar.hpp
  • Weave / Profiles / Mercury / Foo.hpp
  • Weave / Profiles / Mercury / Foobar.hpp

onde Mercury.hpp é o cabeçalho "guarda-chuva" do módulo. A maioria dos integradores simplesmente inclui o cabeçalho "guarda-chuva" do módulo, conforme mostrado:

#include 

No entanto, o desenvolvedor do Mercury agora atingiu um ponto em que há uma necessidade de desenvolver uma próxima geração de APIs e, potencialmente, o protocolo over-the-wire que não são compatíveis com versões anteriores das implantações existentes. O uso de namespaces gerenciados pode ajudar a realizar isso sem interromper essas implantações existentes.

Mover o namespace existente para o atual

Com o objetivo de continuar a oferecer suporte à versão atual da API e à funcionalidade das integrações implantadas existentes, a primeira tarefa é mover o código atual:

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

Observe que, além de mover os arquivos, o cabeçalho inclui proteções para os arquivos movidos também devem ser renomeados, potencialmente decorando-os com '_CURRENT', uma vez que novos arquivos com o mesmo nome serão criados em seus lugares abaixo.

Com o código movido, a próxima etapa é gerenciar o namespace com a designação apropriada, aqui 'Atual'. Primeiro, crie um cabeçalho que defina o namespace gerenciado, como 'Current / MercuryManagedNamespace.hpp'. A criação de tal cabeçalho é preferível a repetir e duplicar esse conteúdo em cada arquivo de cabeçalho quando houver vários arquivos de cabeçalho.

% 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

Em seguida, inclua este cabeçalho antes de outras diretivas de inclusão específicas do módulo nos cabeçalhos existentes. Por exemplo:

#include 

#include 

Crie cabeçalhos de compatibilidade

Mover os cabeçalhos existentes para um novo local e gerenciar seu namespace sozinho, no entanto, não é suficiente para garantir que as implantações existentes funcionem sem alterações, pois todas estão usando diretivas de inclusão que especificam os cabeçalhos que acabaram de ser movidos acima.

Para resolver isso, devem ser criados cabeçalhos de wrapper de compatibilidade com nomes que correspondam aos que acabaram de ser movidos.

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

Se apenas um namespace gerenciado designado por Current estiver sendo criado sem criar um namespace gerenciado designado por Desenvolvimento ou Next para acompanhá-lo, o conteúdo desses arquivos pode simplesmente consistir em um cabeçalho de proteção de inclusão e uma diretiva de inclusão especificando o cabeçalho recém-movido de o mesmo nome:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

No entanto, se um namespace gerenciado designado por Desenvolvimento ou Next também estiver sendo criado para acomodar um desenvolvimento novo e incompatível, algo um pouco mais complexo precisa ser feito.

Como antes, um cabeçalho para a configuração do namespace gerenciado é criado, aqui como MercuryManagedNamespace.hpp. Novamente, isso é preferível a repetir e duplicar este conteúdo em cada arquivo de cabeçalho quando houver vários arquivos de cabeçalho.

% 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

Observe que esse padrão, conforme desejado, a designação de namespace gerenciado para 'Atual' se nenhuma configuração tiver sido definida.

Com este cabeçalho no lugar, os cabeçalhos do wrapper de compatibilidade agora podem ser editados para conter:

#include 

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

ou o que for apropriado para o caso de uso de gerenciamento de namespace em questão.

Criar conteúdo de desenvolvimento

Neste ponto, a infraestrutura está pronta para começar a construir novas funcionalidades e APIs junto com as 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

Claro, se um módulo for muito mais simples do que o exemplo apresentado aqui e não tiver muitas classes, fontes, arquivos ou cabeçalhos, tudo isso pode ser realizado no mesmo arquivo de cabeçalho sem mover os arquivos e criar vários cabeçalhos de compatibilidade e configuração autônomo . No entanto, com este exemplo complexo, ele deve inspirar soluções de namespace gerenciado ao longo de um espectro do complexo ao simples.

Usando namespaces gerenciados como um integrador

Um dos principais focos do integrador Weave SDK é incluir os cabeçalhos de API públicos do Weave SDK apropriados e integrar e desenvolver aplicativos neles.

Como um exemplo prático, novamente suponha um perfil Weave, Mercury, que tem namespaces gerenciados designados por Next-, Current- e Legacy, cujos cabeçalhos públicos são estruturados da seguinte forma:

  • Weave / Profiles / Mercury / Mercury.hpp
  • Weave / Profiles / Mercury / Bar.hpp
  • Weave / Profiles / Mercury / Foo.hpp
  • Weave / Profiles / Mercury / Foobar.hpp
  • Weave / Profiles / Mercury / Next / Mercury.hpp
  • Weave / Profiles / Mercury / Next / Bar.hpp
  • Weave / Profiles / Mercury / Next / Foo.hpp
  • Weave / Profiles / Mercury / Next / Foobar.hpp
  • Weave / Profiles / Mercury / Current / Mercury.hpp
  • Weave / Profiles / Mercury / Current / Bar.hpp
  • Weave / Profiles / Mercury / Current / Foo.hpp
  • Weave / Profiles / Mercury / Current / 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

onde Mercury.hpp é o cabeçalho "guarda-chuva" do módulo.

A menos que o caso de uso em questão motive a inclusão de um módulo gerenciado por namespace no Weave explicitamente, por exemplo:

#include 

é melhor fazer referência aos cabeçalhos públicos do módulo Weave por seus caminhos padrão não gerenciados (por exemplo, Weave / Profiles / Mercury / Mercury.hpp). Isso permite seguir uma progressão de desenvolvimento de API sem alterar continuamente as diretivas de inclusão de um projeto à medida que essas APIs fluem pelo ciclo de vida gerenciado.

Seguindo essa estratégia, as implantações podem então redirecionar seu código em uma designação de namespace gerenciado diferente, a designação Atual por exemplo, especificando a configuração desejada no pré-processador C / C ++. Isso pode ser feito na linha de comando, no código-fonte ou em uma configuração ou cabeçalho de prefixo:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

e usar o caminho de inclusão não gerenciado / não qualificado:

#include 

Quando e se a designação do namespace gerenciado muda para as APIs de destino, por exemplo, de Atual para Legado, basta redirecionar ajustando a definição do pré-processador:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy