// Last edited on 2014-12-17 02:46:37 by stolfilocal
package quack;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.List;
import javax.servlet.http.HttpServletResponse;
public interface HTMLTools {
// Esta classe especifica funções auxiliares para construção de
// páginas HTML a serem enviadas ao browser através do servidor
// HTTP. Enquanto o servidor {Quack} estiver rodando, deveria heaver
// uma única instância desta classe. (Os métodos logicamente
// deveriam ser {static} mas não é possível usar {static} numa
// interface.)
// O parâmetro {wr} nos métodos abaixo é um {PrintWriter},
// geralmente obtido de um objeto {HttpServletResponse}, onde o
// método escreverá o trecho de HTML especificado.
public HTMLTools initialize(Server server);
// Inicializa uma instância desta classe e devolve a mesma inicializada.
// ----------------------------------------------------------------------
// COMPONENTES PRINCIPAIS DE PÁGINAS
//
// O parâmetro {requestor} nos métodos abaixo é o usuário que pediu a informação,
// ou seja o dono da sessão. Se esse parâmetro for {null}, supõe
// que a informação foi solicitada por uma pessoa que não está atualmente logada no
// sistema {Quack}. Esse parâmetro afeta os botões e informações incluídos
// no HTML gerado.
public void writePageHeader(PrintWriter wr, User requestor, String title) throws IOException;
// Escreve em {wr} o trecho de HTML inicial comum a todas as páginas,
// incluindo as tags de abertura "", "", "..."
// e ". Escreve também a declaração dos estilos, e a barra de menu no alto da página. O
// parâmetro {title} é usado na declaração "..." e no
// cabeçalho "...
" logo abaixo da barra de menu.
public void writePageTrailer(PrintWriter wr, User requestor) throws IOException;
// Escreve em {wr} o trecho de HTML final comum a todas as páginas,
// terminando com "".
public void writeListWithNavLinks
( PrintWriter wr,
User requestor,
List list,
int start,
int n,
String requestCmd,
User user,
int maxN
) throws IOException;
// Escreve em {wr} um trecho de uma lista {list} de mensagens, usuários, contatos, etc.. Cada item é
// formatado por {writeMessage}, {writeUser}, {writeContact} etc..
// Escreve também botões de navegação na lista. Esses botões são criados
// por {writeMoreItemsReqLink}.
public void writeMessageList(PrintWriter wr, User requestor, List list, int start, int n) throws IOException;
// Escreve em {wr} um trecho de uma lista de mensagens {list}. Cada mensagem é
// formatada por {writeMessage}.
public void writeUserList(PrintWriter wr, User requestor, List list, int start, int n) throws IOException;
// Escreve em {wr} um trecho de uma lista de usuários {list}. Cada usuário é
// formatado por {writeUser}. Se o {requestor} não for {null}, mostra
// também o estado do contato entre {requestor} e cada usuário.
public void writeContactList(PrintWriter wr, User requestor, List list, boolean targets, int start, int n) throws IOException;
// Escreve em {wr} um trecho de uma lista de contatos {list}. Cada contato é
// formatado por {writeUser} aplicado ao usuário fonte (se {targets == false})
// ou ao usuário alvo se {targets == true}.
// ----------------------------------------------------------------------
// SUB-COMPONENTES DE PÁGINAS
public void writeMessage(PrintWriter wr, User requestor, Message message, boolean full) throws IOException;
// Escreve em {wr} a mensagem {message}, na forma de uma tabela HTML de largura fixa.
// Pode ser usada isoladamente ou dentro de uma lista de mensagens.
//
// Além do texto da mensagem original, escreve os dados do autor original
// (nome login, nome completo, avatar) e botões (repostar, deletar, responder, etc.).
// Se a mensagem é repostagem, escreve também o login, nome e data do último repostador.
// Se {full} for verdade, mostra toda a história de repostagens.
// O botão para repostar só é gerado se {requestor} não for {null}, nem o autor, nem um dos repostadres.
// O botão para responder só é gerado se {requestor} não for {null} nem o autor.
//
// Se o texto da mensagem contém nomes de login de usuários com "@",
// eles são transformados em links para a página desses usuários.
// trecho é transformado em link. Caracteres "<", "&", e ">" no texto
// são convertidos para "<", "&", e ">" respectivamente.
public void writeUser(PrintWriter wr, User requestor, User user, Contact contact) throws IOException;
// Escreve em {wr} os dados do usuário {user}, na forma de uma tabela HTML de largura fixa.
// Pode ser usada isoladamente ou dentro de uma lista de usuários.
//
// A tabela mostra o nome login, nome completo, e avatar do usuário
// {user}. Se o {contact} não for nulo, deve ter origem {requestor}
// e alvo {user}, ou vice-versa; o método vai mostra o estado
// corrente desse contato. Mostra também botões para listar as
// mensagens postadas e repostadas pelo usuário.
//
// Se {user} é igual a {requestor}, inclui botões para mostrar
// listas de contatos de {user}, e sua caixa de entrada (timeline).
//
// Se {requestor} não é {null} e é diferente de {user}, mostra
// botões para fazer o {requestor} seguir, bloquear, deixar de
// seguir, desbloquear o {user}. Se {contact} não é null, o botão
// correspondente ao estado corrente estará desativado.
// ----------------------------------------------------------------------
// BOTÕES E LINKS
public void writeMoreItemsReqLink (
PrintWriter wr,
String label,
String requestCmd,
User user,
int start,
int dir,
long maxN
) throws IOException;
// Escreve em {wr} um link HTTP que pede mais um lote de elementos
// de uma lista de mensagens, usuários, contatos, etc..
//
// O link gerado terá texto visível {label}. Seu URL será
// "{requestCmd}" seguido de "?" e dos argumentos
// "user={user.getLoginName()}", "start={start},
// "dir={dir}", e "maxN={maxN}", separados por "&".
//
// A lista original é identificada pelos parâmetros {requestCmd} e {user}. O
// parâmetro {start} identifica um elemento
// nessa lista original. O parâmetro {dir} indica a direção de
// percurso na lista original, a partir desse elemento inclusive; pode
// ser {-1} (para trás) ou {+1} (para a frente). Note que é direção
// na lista e não no tempo. O parâmetro {maxN} diz o número máximo
// de mensagens a incluir no lote.
// ----------------------------------------------------------------------
// FORMATAÇÃO DE DATAHORAS
//
// Internamente, uma datahora é um {long int}: um número inteiro de
// segundos desde a "época UNIX" (1970-01-01 00:00:00 UTC).
// A precisão de segundos deve ser suficiente para fins do sistema Quack.
//
// Externamente (em particular, nas páginas HTML), uma datahora é
// uma {String} no formato "%Y-%m-%d %H:%M:%S %Z" onde "%Z" é o fuso
// horário.
//
// Tratar fuso horário local é complicado, tem que deixar o usuário
// escolher se quiser, tratar o começo e fim do horário de verão,
// etc. Quando um usuário quer especificar uma hora para outro
// usuário, ele precisa incluir seu fuso, e o outro usuário precisa
// saber converter para o seu. Portanto, por enquanto o sistema
// Quack usa apenas o fuso horário "UTC" (praticamente a hora de
// Londres). Para evitar confusão, o fuso "UTC" será sempre
// especificado exxplicitamente em todas as datahoras no formato
// externo. ??{ Mais tarde podemos implementar códigos de fusos
// locais, como "BRST", ou a notação geral "(+0300)" para UTC + 3
// horas. }??
public String formatTimestamp(long timestamp, String timezone);
// Converte uma datahora do formato interno para o formato externo,
// com o fuso horário especificado pelo parâmetro {timezone}.
// Por enquanto, {timezone} deve ser obrigatoriamente "UTC".
public long parseTimestamp(String timestamp);
// Converte uma datahora do formato externo para o formato interno.
// Por enquanto, a cadeia {timestamp} deve terminar com " UTC", e
// a conversão vai usar o fuso horário UTC.
// Se o formato não for reconhecido, retorna {-1L}.
}