• O pacote NetBeans IDE Java EE também inclui o servidor GlassFish, um servidor compatível com Java EE 6, que é necessário para este tutorial.
• Para o projeto de solução deste tutorial, baixe ConsultingAgencyJSF20.zip.

<h:outputStylesheet name="css/jsfcrud.css"/>

<application>
    <resource-bundle>
        <base-name>/resources/Bundle</base-name>
        <var>bundle</var>
    </resource-bundle>
</application>

Examinando o projeto concluído

1. Para executar o projeto, clique com o botão direito do mouse no nó do projeto na janela Projetos e escolha Executar ou clique no botão Executar projeto () na barra de ferramentas principal.
   
   Quando a página de boas-vindas do aplicativo é exibida, aparece uma lista de links que permite visualizar as entradas contidas em cada uma das tabelas do banco de dados.
   
   Os links foram adicionados à página de boas-vindas (index.xhtml) quando o assistente Páginas JSF de classes de entidade foi concluído. Tais links são fornecidos como pontos de entrada nas páginas Facelets que proporcionam funcionalidade CRUD no banco de dados da agência de consultoria.

   <h:body>
       Hello from Facelets
       <h:form>
           <h:commandLink action="/address/List" value="Show All Address Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/billable/List" value="Show All Billable Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/client/List" value="Show All Client Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/consultant/List" value="Show All Consultant Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/consultantStatus/List" value="Show All ConsultantStatus Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/project/List" value="Show All Project Items"/>
       </h:form>
       <h:form>
           <h:commandLink action="/recruiter/List" value="Show All Recruiter Items"/>
       </h:form>
   </h:body>

2. Clique no link 'Mostrar todos os itens do consultor'. Ao observar o código acima, é possível ver que a página de destino é /consultant/List.xhtml. (No JSF 2.0, a extensão do arquivo é deduzida devido à navegação implícita.)
   
   Atualmente, o banco de dados não contém nenhum dado de amostra. É possível adicionar dados manualmente clicando no link 'Criar novo consultor' e utilizando o formulário Web fornecido. A página /consultant/Create.xhtml é carregada para que seja exibida. Também é possível executar um script SQL no IDE para preencher as tabelas com os dados de amostra. As subseções seguintes exploram ambas as opções.

É possível clicar no link do índice para voltar à lista de links da página de boas-vindas. Os links oferecem uma visualização dos dados contidos em cada tabela do banco de dados e carrega o arquivo List.xhtml de cada pasta de entidade para que seja exibida. Conforme será demonstrado posteriormente, após adicionar os dados às tabelas, outros links serão exibidos em cada entrada a fim de permitir que você visualize (View.xhtml), edite (Edit.xhmtl) e destrua os dados de um único registro da tabela.

Preenchendo o banco de dados com um script SQL

Execute o script fornecido, que gera dados de amostra para as tabelas do banco de dados. O script (mysql_insert_data_consult.sql) está incluído no arquivo zipado Consultando banco de dados da agência que pode ser baixado da tabela de software requerido.

Dependendo do servidor de banco de dados com que estiver trabalhando (MySQL ou JavaDB), você pode executar o script fornecido, que gera dados de amostra para as tabelas de banco de dados. Para o MySQL, esse é o script mysql_insert_data_consult.sql. Para o JavaDB, esse é o script javadb_insert_data_consult.sql. Ambos os scripts são incluídos nos respectivos arquivos, que podem ser baixados da tabela de software requerido.

1. Escolha Arquivo > Abrir arquivo no menu principal e, em seguida, navegue até o local do script no seu computador. Clique em Abrir. O arquivo se abre automaticamente no editor SQL do IDE.
2. Certifique-se de que o banco de dados consult esteja selecionado na lista suspensa Conexão na barra de ferramentas do editor SQL.
   

   Clique com o botão direito do mouse no editor e escolha Executar instrução ou clique no botão Executar SQL (). É possível ver o resultado da execução do script na janela Saída.

3. Reinicie o servidor GlassFish. Essa é uma etapa necessária para habilitar o servidor a fim de recarregar e efetuar o cache dos novos dados contidos no banco de dados consultar. Para fazer isso, clique na aba do servidor GlassFish na janela Saída (a aba do servidor GlassFish exibe o registro do servidor.) e, em seguida, clique no botão Reiniciar servidor ( ) na margem esquerda. O servidor para e, em seguida, reinicia.
4. Execute o projeto novamente e clique no link 'Mostrar todos os itens do consultor'. Você verá que a lista não está mais vazia.
   

   Suporte ao banco de dados NetBeans

   É possível utilizar o visualizador de tabelas do banco de dados do IDE para exibir e modificar os dados da tabela mantidos diretamente no banco de dados. Por exemplo, clique com o botão direito do mouse na tabela consultant na janela Serviços e escolha Visualizar dados.

   

   A consulta SQL utilizada para efetuar a ação é exibida na parte superior do editor e uma visualização gráfica da tabela é exibida abaixo.

   

   Clique duas vezes dentro das células da tabela para efetuar modificações diretamente nos dados. Clique em Enviar registros () para enviar as alterações do banco de dados.

   A visualização gráfica oferece mais funcionalidade. Consulte Suporte ao banco de dados no NetBeans IDE para obter mais informações.

   
   

Explorando o suporte do editor em páginas Facelets

1. Abra a página /consultant/List.xhtml no editor. A linha 8 indica que a página depende do arquivo Facelets template.xhtml para que seja processada.

   <ui:composition template="/template.xhtml">
   
   

   Para exibir os números das linhas, clique com o botão direito do mouse na margem esquerda do editor e escolha Exibir números de linhas.

2. Utilize a caixa de diálogo Ir para arquivo do IDE para abrir template.xhtml. Pressione Alt-Shift-O (Ctrl-Shift-O no Mac) e, em seguida, comece a digitar modelo.
   

   Clique em OK (ou pressione Enter).

3. O modelo aplica as marcações <ui:insert> para inserir o conteúdo de outros arquivos no título e corpo. Coloque seu cursor na marca <ui:insert>, pressione Ctrl-Espaço para chamar uma janela pop-up de documentação.
   

   É possível pressionar Ctrl-Espaço nas marcações JSF e seus atributos para chamar o pop-up da documentação. A documentação exibida é retirada das descrições fornecidas na Documentação da biblioteca de marcas JSF oficial.

4. Volte para o arquivo List.xhtml (pressione Ctrl-Tab). As marcações <ui:define> são utilizadas para definir o conteúdo que será aplicado ao título e ao corpo do modelo. Esse padrão é utilizado nos quatro arquivos Facelets (Create.xhtml, Edit.xhtml, List.xhtml e View.xhtml) gerados para cada classe de entidade.
5. Coloque seu cursor em qualquer uma das expressões EL utilizadas nas mensagens localizadas contidas no arquivo Bundle.properties. Pressione Ctrl-Espaço para visualizar a mensagem traduzida.
   

   Na imagem acima, você pode ver que a expressão EL determina 'List', que é aplicada ao título do modelo e pode ser verificada na página processada no navegador.

6. Navegue para a parte inferior do arquivo e localize o código do link Criar novo consultor (linha 92). Trata-se do seguinte:

   <h:commandLink action="#{consultantController.prepareCreate}" value="#{bundle.ListConsultantCreateLink}"/>

7. Pressione Ctrl-Espaço no atributo action do commandLink para chamar a janela pop-up da documentação.
   
   O atributo ação indica o método que manipula a requisição quando o link é clicado no navegador. É fornecida a seguinte documentação:
   
   
   MethodExpression que representa a ação do aplicativo que será chamada quando este componente for ativado pelo usuário. A expressão deve ser interpretada como um método público que não toma nenhum parâmetro e retorna um Object (o toString() do qual é chamado para gerar o resultado lógico) que é passado para o NavigationHandler deste aplicativo.
   
   Em outras palavras, o valor de ação se refere normalmente a um método em um bean gerenciado do JSF que é avaliado como uma String. Então, a string é utilizada pelo NavigationHandler do JSF para encaminhar a requisição para a visualização apropriada. É possível verificar isso nas etapas a seguir.
8. Coloque o cursor no consultantController e pressione Ctrl-Espaço. O auto-completar código do editor indica que consultantController é um Bean gerenciado do JSF.
   
9. Mova o cursor para prepareCreate e pressione Ctrl-Espaço. O auto-completar código lista os métodos contidos no Bean gerenciado ConsultantController.
   
10. Pressione Ctrl (&#8984 no Mac) e, em seguida mova o mouse para prepareCreate. É formado um link, que permite ir diretamente para o método prepareCreate() no Bean gerenciado ConsultantController.
    
11. Clique no link e visualize o método prepareCreate() (exibido abaixo).

    public String prepareCreate() {
        current = new Consultant();
        selectedItemIndex = -1;
        return "Create";
    }

    O método retorna Criar. O NavigationHandler coleta informações em segundo plano e aplica a string Criar ao caminho que indica a visualização enviada em resposta à requisição: /consultant/Criar.xhtml. (No JSF 2.0, a extensão do arquivo é deduzida devido à navegação implícita.)

Explorando a integridade do banco de dados com validação de campo

1. Na página Lista de consultores do navegador, clique no link 'Criar novo consultor'. Conforme demonstrado na subseção anterior, isso carrega a página /consultant/Create.xhtml para que seja processada.
2. Insira os detalhes a seguir no formulário. Temporariamente, deixe os campos RecruiterId e StatusId em branco.
   
   

   Campo	Valor
   ConsultantId	2
   Email
   Password	jack.smart
   HourlyRate	75
   BillableHourlyRate	110
   HireDate	07/22/2008
   Retornar	Sou um ótimo consultor. Contrate-me - Você não vai se arrepender!
   RecruiterId	---
   StatusId	---

3. Clique em Salvar. Ao clicar em salvar, um erro de validação é sinalizado no campo StatusId.
   
   Por que aconteceu isso? Re-examine o diagrama entidade de relacionamento do banco de dados da agência de consultoria. Conforme apresentado na tabela de relacionamentos acima, as tabelas CONSULTANT e CONSULTANT_STATUS compartilham um relacionamento um para muitos não nulo. Portanto, todas as entradas da tabela CONSULTANT devem conter uma referência a uma entrada na tabela CONSULTANT_STATUS. Isso é indicado pela chave estrangeira consultant_fk_consultant_status que vincula as duas tabelas.

   É possível visualizar as chaves estrangeiras contidas nas tabelas expandindo o nó Chaves estrangeiras da tabela na janela Serviços (Ctrl-5; &#8984-5 no Mac).

   
4. Para solucionar o erro de validação, selecione entity.ConsultantStatus[statusId=A] na lista suspensa StatusId.
   
   Nota: você pode deixar o campo RecruiterId em branco. Conforme indicado no diagrama entidade-relacionamento do banco de dados, há um relacionamento não-nulo um para muitos entre as tabelas CONSULTANT e RECRUITER, indicando que tais entradas de CONSULTANT não precisam estar associadas a uma entrada de RECRUITER.
5. Clique em Salvar. É exibida uma mensagem indicando que a entrada consultante foi salva com êxito. Se clicar em Exibir todos os itens do consultor, verá a nova entrada listada na tabela.

Em geral, as páginas Facelets geradas produzem erros em entradas do usuário que introduzem:

• campos vazios em células de tabela não-nula.
• modificações de dados que não podem ser alterados (por exemplo, chaves primárias).
• inserção de dados que não são do tipo correto.
• modificações de dados quando uma visualização do usuário não estiver mais sincronizada com o banco de dados.

Editando as classes de entidade

Na subseção anterior, você viu como a lista suspensa StatusId forneceu a desagrádavel opção entity.ConsultantStatus[statusId=A]. Você já deve ter notado que o texto exibido em cada item desta lista suspensa é a representação de uma string de cada entidade ConsultantStatus encontrada (por exemplo, o método toString() da classe de entidade é chamado).

Essa subseção demonstra como você pode utilizar o autocompletar de código, a documentação e o suporte à navegação do editor para chegar a essa conclusão. Também oferece uma mensagem mais agradável para a lista suspensa.

1. Abra o arquivo /consultant/Create.xhtml no editor. Trata-se do formulário Criar novo consultor que você acaba de visualizar no navegador. Role para baixo até o código da lista suspensa StatusId (ilustrado em negrito abaixo).

       <h:outputLabel value="#{bundle.CreateConsultantLabel_resume}" for="resume" />
       <h:inputTextarea rows="4" cols="30" id="resume" value="#{consultantController.selected.resume}" title="#{bundle.CreateConsultantTitle_resume}" />
       <h:outputLabel value="#{bundle.CreateConsultantLabel_statusId}" for="statusId" />
       <h:selectOneMenu id="statusId" value="#{consultantController.selected.statusId}" title="#{bundle.CreateConsultantTitle_statusId}" required="true" requiredMessage="#{bundle.CreateConsultantRequiredMessage_statusId}">
           <f:selectItems value="#{consultantStatusController.itemsAvailableSelectOne}"/>
       </h:selectOneMenu>
       <h:outputLabel value="#{bundle.CreateConsultantLabel_recruiterId}" for="recruiterId" />
       <h:selectOneMenu id="recruiterId" value="#{consultantController.selected.recruiterId}" title="#{bundle.CreateConsultantTitle_recruiterId}" >
           <f:selectItems value="#{recruiterController.itemsAvailableSelectOne}"/>
       </h:selectOneMenu>
   </h:panelGrid>

2. Examine o valor aplicado à marcação <f:selectItems>. O atributo value determina o texto exibido de cada item na lista suspensa.
   
   Pressione Ctrl-Espaço em itemsAvailableSelectOne. O auto-completar código do editor indica que o método getItemsAvailableSelectOne() do ConsultantStatusController retorna uma raiz de objetos SelectItem.
   
3. Pressione Ctrl (&#8984 no Mac) e, em seguida, mova o mouse sobre itemsAvailableSelectOne. É formado um link que permite ir diretamente para o método getItemsAvailableSelectOne() no código-fonte da entidade ConsultantStatus. Clique neste link.
4. Coloque o cursor sobre o valor de retorno SelectItem[] na assinatura do método e pressione Ctrl-Espaço para chamar a janela pop-up da documentação.
   

   Clique no ícone do navegador Web ( ) na janela da documentação para abrir o Javadoc em um navegador Web externo.

   Como é possível visualizar, a classe SelectItem pertence à estrutura JSF. O componente UISelectOne, conforme mencionado na documentação, é representado pela marca <h:selectOneMenu> da marcação que você examinou na etapa 1 acima.
5. Pressione Ctrl (&#8984 no Mac) e, em seguida, mova o mouse sobre findAll(). É exibido um pop-up com a assinatura do método.
   
   É possível observar que aqui o ejbFacade.findAll() retorna uma Lista de objetos ConsultantStatus.
6. Vá para JsfUtil.getSelectItems. Coloque o mouse sobre getSelectItems e pressione Ctrl (&#8984 no Mac), a seguir, clique no link exibido.
   
   Nota: lembre-se que JsfUtil é uma das classes de utilitário gerada ao concluir o assistente classes de entidade da página JSF.
   
   O método efetua o loop através da lista de entidades (por exemplo, Lista de objetos ConsultantStatus), criando um SelectItem para cada. Conforme indicado abaixo em negrito, cada SelectItem é criado utilizando o objeto da entidade e um label para o objeto.

   public static SelectItem[] getSelectItems(List<?> entities, boolean selectOne) {
       int size = selectOne ? entities.size() + 1 : entities.size();
       SelectItem[] items = new SelectItem[size];
       int i = 0;
       if (selectOne) {
           items[0] = new SelectItem("", "---");
           i++;
       }
       for (Object x : entities) {
           items[i++] = new SelectItem(x, x.toString());
       }
       return items;
   }

   O rótulo é criado utilizando o método toString() da entidade e corresponde à representação do objeto quando processado na resposta. (Consulte a definição do construtor SelectItem(java.lang.Object value, java.lang.String label) no Javadoc.)
   
   Agora que averiguou que o método toString() da entidade é o método processado no navegador ao visualizar os itens em uma lista suspensa, modifique o método toString() de ConsultantStatus.
7. Abra a classe de entidade ConsultantStatus no editor. Modifique o método toString para retornar statusId e descrição. Trata-se das propriedades da entidade que correspondem às duas colunas da tabela CONSULTANT_STATUS.

   public String toString() {
       return statusId + ", " + description;
   }

8. Execute o projeto novamente. Quando o navegador exibir a página de boas-vindas, clique no link Exibir todos os itens do consultor e, em seguida, em Criar novo consultor.
   
   Inspecione a lista suspensa StatusId. Você verá que agora exibe o ID de status e a descrição do registro contido na tabela CONSULTANT_STATUS do banco de dados.
   

Tutoriais e artigos NetBeans

• Introdução ao JavaServer Faces 2.0 no NetBeans IDE
• Suporte JSF 2.0 no NetBeans IDE
• Scrum Toys: complete o aplicativo de amostra do JSF 2.0
• Primeiros passos com os aplicativos do Java EE 6
• Trilha do aprendizado do Java EE e Java Web

Recursos externos

• Tecnologia JavaServer Faces (Homepage oficial)
• Especificação JSR 314 para JavaServer Faces 2.0
• Tutorial do Java EE 6, Capítulo 5: tecnologia JavaServer Faces
• Projeto Mojarra GlassFish (Implementação oficial de referência do JSF 2.0)
• Fóruns de Discussão OTN: JavaServer Faces
• Central do JSF

Blogs

• Ed Burns
• Ryan Lubke
• Jim Driscoll