File: leiame.txt

* @author Marcelo Soares da Costa
* @email phpmafia at yahoo dot com dot br, unixmafia at yahoo dot com dot br
* @copyright Marcelo Soares da Costa © 2008.
* @license FreeBSD http://www.freebsd.org/copyright/freebsd-license.html

OOE (Orientado a Objeto de Escopo ou Objetos Orientados a Escopo) é um modelo de API de desenvolvimento para aplicações orientadas a objetos.

O desafio inicial de classe OOE foi prover um emulação de características de heranças multiplas 
(emulation multiple Inheritance ) permitindo que as classes de diferentes escopos
fossem independentes entre si , para poder emular esta característica foi criado uma unica
classe que provesse essa característica, a classe Inheritance que em tese deve ser sempre 
a superclasse a ser extendida e referênciar as classes de diferentes escopos.

Outro desafio foi o de criar uma classe de tomada de decisão sobre qual classe extender, 
a própia classe  Inheritance permitiu essa tomada de decisão a partir de uma classe abstrata,
classe SqlExtender que referência dinamicamente a classe DataBase ou a classe DataBasePdo 
e os metodos publicos finais para uso são determinados pela classe SqlQuery que extende 
a classe SqlExtender.

O objetivo da classe OOE é prover um modelo de orientação de objetos em que o desenvolvedor se 
preocupe somente com as regras de negócio de sua aplicação seja diretamente em seus scripts php 
ou aplicando o mesmo conceito da classe OOE  para sua aplicação, entendendo que os metodos 
públicos a serem usados devem estar na classe que trata da camada de aplicação para que seja 
necessário referênciar somente esta unica classe.

Caracteristicas do pacote OOE :

- Absolutamente orientada a objetos;
- Suporte a diversos banco de dados;
- Uso de encode e criptografia;
- Geração e leitura de xml;
- Uso de templates no formato xslt;
- Uso de base de dados tanto em banco de dados com em xml;
- Integrado a sistem de Login Seguro;
- Permite a integração com classes externas dentro do modelo OOE;
- Padronização dos metodos usados nas aplicações;
- Permite uma separação real de escopos dos objetos; 
- Uso de apenas um objeto para cada escopo usando singletron;
- Compativel para projetos com arquiterura MVC, Model-View-Controller design pattern;
- Necesita de referêcia a somente uma classe, a própia OOE ou a classe extendida ou com o mesmo modelo OOE;
- Modelo de arquitetura Orientado a Objeto de Escopo (OOE) ou seja, permite que cada classe gerencie 
um determinado escopo isoladamente, se este modelo não existe acaba de ser criado ;
- Todo tratamento de erros baseado em exceções, exception error; 
- Licensa BSD que permite o uso comercial e alterações sem restrições mantendo a referência do autor;


Descrição da classes :

  Classe Inheritance:
  
  Arquivo: class_Inheritance.php;
  Descrição: Superclasse que referência as classes de escopo do modelo OOE;
  Métodos: - callClassParent é o método responsavel por instanciar as classes em tempo de execução, 
             retorna a referência do objeto instanciado;
           - contrutor e clone retornam exceção por não serem acessíveis;
           
  Classe PhpEncode:
  Arquivo class_PhpEncode.php;
  Descrição: Classe pai do escopo encode, usa serealize e base64 para colocar em encode um array ou uma string
  Métodos: - Metodos para gerar o encode e para decodificar o encode de strings e arrays
  
  Classe Array2Xml:
  Arquivo: class_Array2Xml.php;
  Descrição: Classe que extende a classe Inheritance e referencia as classes php nativas DomDocumente XsltProcessor, 
             e tem como escopo gerar xml a partir de um array e adicionar um estilo xsl e transformar em html;
  Métodos: - Os métodos publicos tem objetivos de transformar um array associativo em xml e implementar estilos xsl,
  				uma constante DEBUGXML pode ser setada como true para debug;
  
  Classe Xml2Array:
  Arquivo: class_Xml2Array.php;
  Descrição: Classe que lê um arquivo xml e transforma os objetos em array;
  Métodos: - Metodos publicos para ler arquivo xml e transformar os objetos em array; 
  
  Classe Array2XmlGrid:
  Arquivo: class_Array2XmlGrid.php;
  Descrição: Classe que extende Inheritance e referencia os metodos da classe PhpEncode e Array2Xml, gera um xml formatado
             com tags especiais a serem reconhecidas por um estilo xsl, originalmente escrita para gerar um grid a partir
              de um template em xsl mas que pode aplicar um estilo qualquer para transformar esse xml com marcações 
              especiais em um html qualquer, implementa a interface GridTemplate;
  Métodos: - Os métodos publicos criam as marcações especiais a partir de manipulação do array que sera transformado 
             em html por um estilo xsl
             
  Classe DataBase:
  Arquivo class_DataBase.php;
  Descrição: Classe pai para uso direto dos drivers php para mysql e postgres que possui um longo histórico, tendo como
             seu primeiro modelo a classe Innodb e posteriormente a classe mafiaSql, trata-se de um conjunto de métodos
             para facilitar a partir de querys sql a manipulação de resultados de SELECT,INSERT,UPDATE e DELETE;
  Métodos: - os métodos publicos simplificados para o uso de transações e metodos protegidos para serem usados na manipulação 
             da classe filha, o construtor apenas seta as variaveis de conexão;
             
  Classe DataBasePdo:
  Arquivo: class_DataBasePdo.php;
  Descrição: Classe que extende a classe PDO (PHP DATA OBJECT) apenas com os metodos necessários para um coerente manipulação
             de querys SQL de SELECT,INSERT,UPDATE E DELETE;
  Métodos: - Os métodos referêciam a classe pai PDO com o escopo parent e tornam os metodos protegidos para serem manipulados 
             a partir da classe filha;
             
  Classe SqlExtender:
  Arquivo: class_SqlExtender.php
  Descrição: Classe abstrata que extende a classe Inheritance, com metodos abstratos para macro de manipulação de resultados 
             de querys SQL, define se a classe extendida sera a classe DataBase ou dataBasePdo a partir do set das constantes
              e sobrescreve os metodos extendidos;
  Metodos : - Formada em sua maior parte por metodos protegidos que serão herdados pela classe filha que tem o objetivo de criar
             as regras de negócio para o escopo de querys SQL;
  
  Classe SqlQuery:
  Arquivo class_SqlQuery.php
  Descrição: Classe filha que extende a classe SqlExtender que gerencia o escopo de querys SQL , tem por objetivo gerar os métodos
              publicos do escopo de SQL;
  Métodos: - Os metodos publicos determinam os métodos do escopo query SQL para SELECT,INSERT,DELETE e UPDATE , retornando um 
             resultado coerente ao tipo de query.
             
  Classe SecuritySession:
  Arquivo: class_SecuritySession.php;
  Descrição: - Classe que extende a classe Inheritance e referenciam os metodos da classe SqlQuery e implementa as interfaces
               SqlTemplate e SSTemplate, possue um histórico pois se trata de uma classe do escopo login/gerenciamento de sessão 
               de forma segura que foi inicialmente criado pela classe mafiasession , awards de inovação no phpclasses, tem por 
               objetivo prover um sistema de login seguro atravez do uso de criptografia a partir do modelo HMAC;
  Métodos: - Métodos publicos para geração e captura de chave criptografica de verificação de autenticidade da sessão armazenada
             no banco de dados , preve troca de chaves de sessão periodicamente para prover alto indice de segurança;
             
  Interface SqlTemplate:
  Arquivo: class_SqlTemplate.php;
  Descrição: Interface que determina quais devem ser os métodos publicos obrigatórios a serem implementados pelas classes que 
             referenciam os métodos da classe SqlQuery;
             
  Interface SSTemplate:
  Arquivo: class_SSTemplate.php;
  Descrição: Interface que determina quais devem ser os métodos publicos obrigatórios a serem implementados pelas classes que 
             referenciam a classe SecuritySession;
 
 Interface GridTemplate:
 Arquivo class_GridTemplate.php;
 Descrição: Interface que determina quais devem ser os métodos publicos obrigatórios a serem implementados pelas classes que 
            referenciam a classe Array2XmlGrid;
             
  Classe Sql2Xml:
  Arquivo class_Sql2Xml.php;
  Descrição: Classe que une os escopos de query SQL com o escopo de XML , é um exemplo de intercessão de escopos uma camada de OOE;

  Classe Sql2Grid:
  Arquivo class_Sql2Grid.php;
  Descrição: Classe que une os escopos de query SQL com o escopo de xmlGrid , é um exemplo de intercessão de escopos uma camada de OOE;
  
  Classe OOE:
  Arquivo class_OOE.php;
  Descrição: Classe que une os escopos de query SQL, XML , SESSION ,ENCODE , é o própio modelo OOE onde cada escopo é gerênciado por um
             objeto específico e referenciado em tempo de execução , fazendo a intercessão de todos os escopos para permitir o uso de 
             referência a uma unica classe no escopo da aplicação para gerar as regras de negócio da aplicação;
             
  Login.php, sucesso.php e action.php são exemplos de como se aplicar o modelo OOE. 
  
Escopo dos objetos:

  A primeira questão a ser discutida é o que é escopo:
  
  Escopo é um entidade qualquer definida pelo desenvolvedor , quanto mais profunda a análise de escopos mais baixo níveis de escopos
  podem ser definidos.
  
  Como exemplo na class OOE desta API de desenvolvimento temos o própio escopo OOE, ou seja toda classe deve representar um escopo.
  
  Dentro do escopo da classe OOE temos os seguintes escopos contidos :
  
   SqlQuery, SecuritySession, Array2XmlGrid, Xml2Array e PhpEncode.
   
  O escopo SqlQuery contém um único escopo SqlExtender que por sua vez contém os escopos DataBase e DataBasePdo que contem o escopo PDO.
  
  Por sua vez o escopo SecuritySession também contém o escopo SqlQuery, o que significa que existe uma "área" de intercessão entres os
  escopos, ou seja o escopo SqlQuery esta contido tanto dentro do escopo OOE como do escopo SecuritySession.
  
  Analisando o escopo Array2XmlGrid vemos que ele contém os escopos PhpEncode e Array2Xml, ambos os escopos estão também continos no
  escopo OOE mas por sua vez o escopo PhpEncode não possuem nenhum escopo dentro dele , enquanto o escopo Array2Xml possue ainda os 
  escopos DomDocument e XsltProcessor.
  
  Os escopos Xml2Array e PhpEncode não possuem nenhum escopo contido portanto são escopos de níveis mais baixos.
  
  Verificamos então que os escopos de níveis mais baixos são :
  
  DataBase, PDO, DomDocument, XsltProcessor,Xml2Array,PhpEncode e SecuritySession , e que o escopo
  SecuritySession possue uma interferencia com um escopo de nivel mais alto SqlQuery , portanto o modelo OOE é paralelo a teoria de 
  conjuntos, ou seja cada objeto é pode ser representado por um conjunto que podem conter outros conjuntos , pode ter uma área de intercessão 
  com outro conjunto mas que existe um conjunto maior que é o OOE que contém todos outros conjuntos (objetos).
  
  Isto demostra que o escopos são meras definições do desenvolvedor , o escopo OOE poderia ser construido de forma diferente, ou seja poderia 
  conter os escopos Sql2Xml,Sql2Grid, SecuritySession, Xml2Array pois dentro desses escopos estão contidos todos os demais escopos e que haveria
  um intercessão estre os escopos Sql2Xml,Sql2Grid e SecuritySession que seria o escopo SqlQuery. Entretanto quanto mais baixo os níveis de 
  escopos definidos maior é o numero de funcionalidades possiveis com a API OOE.
  
  Para um implementação completa da OOE então se temos dois ou mais objetos que possuem uma área de interferencia esta área deve ser definida
  como um outro escopo que esta contido na área de interferência de dois objetos contidos na OOE.
  
  Isto também defini que um escopo é nada mais do que um conjunto de funcionalidades contidas em um objeto representado por sua classe.
  
  A implementação de um objeto OOE deve ser sempre atravéz da extensão da classe Inheritance.
  
  A extensão pura e simples de uma classe OOE mantém a característica de ser OOE.
  
  Dois ou mais objetos OOE podem formar um outro objeto OOE que contém os objetos OOE de escopo mais baixo preservando as características dos
  objetos de escopos de níveis mais baixos.
  
Porque usar OOE ?

  Para o desenvolvedor no paradigma da orientação à objetos é mais prático definir objetos de escopos do que em outros modelos onde os 
  paradigmas são frequentes e a implementação de uma funcionalidade que pode pertencer a mais de um contexto os obriga muitas vezes a tomar 
  uma decisão em uma unica direção ou repetir a implementação de uma funcionalidade em mais de um lugar, onde na OOE isso se torna um escopo
  de nivel mais baixo que pode ser usado em qualquer parte do modelo OOE.
  
  Apenas como exemplo de uso de contexto de nível mais baixo seria implementar o escopo REQUEST que conteria os escopos POST e GET e ainda 
  implementar o escopo SESSION , mas não há uma necessidade de se criar esses escopos pois o php já os implementa por si mesmo.
  
Contibuições com esse modelo e mesmo tradução da documentação serão sempre bem vindas e referênciadas como co-autores / colaboradores.

* @author Marcelo Soares da Costa
* @email phpmafia at yahoo dot com dot br, unixmafia at yahoo dot com dot br
* @copyright Marcelo Soares da Costa © 2008.
* @license FreeBSD http://www.freebsd.org/copyright/freebsd-license.html