// Last edited on 2014-12-17 02:46:00 by stolfilocal

package quack;

import java.io.IOException;
import java.util.List;

import javax.servlet.http.HttpServletResponse;

public interface HTML {

    // Esta classe especifica funções para construção de páginas HTML
    // a serem enviadas ao browser através do servidor HTTP.
    // Enquanto o servidor {Quack} estiver sendo executado, haverá 
    // apenas uma instância desta classe existente.

    public HTML initialize(Server server);
    // Inicializa o objeto {this} e devolve o objeto inicializado.
    // O objeto {server} será usado para mostrar as estatísticas
    // (número de usuários, mensagens, etc.) no cabeçalho das páginas,
    // e para consultar o relógio. !!{ A fazer }!!.
	
    // ------------------------------------------------------------------------
    // CONSTRUÇÃO DE PÁGINAS COMPLETAS
        
    // Cada um dos métodos nesta seção escreve uma página HTML completa no 
    // parâmetro {response}. 
    // 
    // O parâmetro {requestor}, em aguns dos métodos abaixo,
    // é o usuário para o qual a página está sendo
    // construída; ou seja, o dono da sessão. Se esse parâmetro for {null},
    // supõe-se que a página está sendo gerada para um leitor que não está logado no sistema.
    // Em alguns métodos, o {requestor} pode ser {null}; em outros ele deve ser não-nulo.
    //
    // O parâmetro {requestor}
	
    public void homePage(HttpServletResponse response, User requestor);
    // Retorna a pagina principal da rede {Quack}, com botões e campos
    // para login/logout, cadastramento de novos usuários, listagem de dados públicos e 
    // e mensagens públicas de usuários, busca por conteúdo em mensagens e/ou usuários, etc..
    // Se o {requestor} for {null}, gera um botão de login, senão mostra o nome
    // do requestor e gera um botão de {logout}.

    public void errorPage(HttpServletResponse response, String msg);
    // Compõe uma página HTML com a mensagem de erro {msg}, e a envia como resposta para o usuario usando {response}.
    // Alem disso, escreve a mensagem na saida padrao.

    public void loginPage(HttpServletResponse response);
    // Compoe uma página HTML com campos {loginName} e {password},
    // para o usuário fazer login.

    public void loginSuccessfulPage
      ( HttpServletResponse response, 
        User requestor, 
        String cookie
        );
    // Pagina de resposta a um login bem sucedido pelo usuário {requestor}. 
    // O {cookie} será incluído na página e armazenado pelo browser
    // para identificar a sessão de login em futuros pedidos da mesma pessoa no mesmo browser.
    // ??{ No futuro, armazenar o {cookie} no usuário e talvez na base persistente? }??
	
    public void userProfilePage
      ( HttpServletResponse response, 
        User requestor, 
        User user, 
        Contact contact
        );
    // Página que mostra o perfil do usuário {user} (que não pode ser {null}).
    // 
    // Se o {requestor} for igual ao {user}, gera botões para editar o perfil.
    //
    // Se o {requestor} não for {null} mas for diferente de {user}, gera botões
    // para seguir, bloquear, deixar de seguir, ou desbloquar o usuário {user}
    // na lista de contatos do {requestor}.  Se o {contact} não for nulo,
    // deve ter origem {requestor} e alvo {user}; o método então mostra o
    // estado corrente desse contato, e inativa o botão correspondente.

    public void listPage
        ( HttpServletResponse response, 
          User requestor, 
          String title,
          List list,
          int start,
          int n,
          String requestCmd, 
          User user,
          int maxN
          );
    // Escreve em {response} uma pagina com título {title} que exibe
    // um trecho de uma lista de itens {list} -- por exemplo, todos os usuários do
    // sistema, mensagens recebidas ou enviadas por um usuário,
    // contatos de um usuário, etc.
    //
    // O trecho começa no elemento {start} e tem {n} elementos.
    // A página terá botões de navegação para pedir o próximo trecho itens da lista,
    // ou o trecho anterior.  Estes botões geram um pedido GET 
    // com URL "http://{host}/Quack/{requestCmd}?"seguido de parâmetros
    // "loginName={user.getLoginName()}", "start={newStart}", "dir={dir}", "n={maxN}";
    // onde {dir} é {-1} ou {+1}, {newStart} é {start} ou {start+n-1}, respectivamente.
	
}