O que é e como gerar um arquivo ICS (iCalendar) com Java.

Arquivos do tipo iCalendar podem ser utilizados em diversas situações. Apesar de não ser um tipo de arquivo tão conhecido entre o público em geral, por diversas vezes pode ser utilizado para agregar bastante valor a uma aplicação visto sua funcionalidade. Neste post você vai entender desde as possibilidades de aplicação de um arquivo tipo iCalendar até como criar um utilizando a linguagem Java.

O que é um arquivo ICS?

Arquivos ICS, ou também conhecidos como arquivos iCalendar são utilizados para definir eventos em aplicativos diversos de calendário e/ou agenda. Aplicativos como: Google Calendar, Apple Calendar, e tantos outros disponíveis no mercado permitem a incorporação de eventos a sua agenda por meio de arquivos ICS.

Sendo um arquivo de texto simples, não implica em muita dificuldade de se inserir ou modificar os valores do mesmo, entretanto, para fazer isso é necessário conhecer a sua estrutura básica e todas as opções de configurações de eventos diferentes possíveis.

Em que situação pode ser utilizado?

Esse tipo de arquivo pode ser utilizado em situações nas quais você deseja que fique salvo de alguma forma no aplicativo de agenda do seu usuário algum lembrete de evento, de forma a quando estiver chegando próximo a data e hora do mesmo o usuário seja lembrado.

Deste modo você cria o arquivo iCalendar e disponibiliza para o usuário de alguma maneira, a partir do momento que o usuário clica para abrir o arquivo, o mesmo já é aberto com o aplicativo de calendário padrão na aba de adição de eventos com todas as configurações de título do evento, horário de início, horário de término, descrição do evento, local e outras informações relevantes a serem melhor descritas mais a frente neste post.

Como colocado mais acima no post um arquivo tipo iCalendar é um arquivo tipo texto, deste modo uma das limitações do mesmo é não suportar de forma alguma a inserção de imagens no mesmo.

Possíveis dificuldades de implementação.

Como foi citado no inicio do post os arquivos ICS são o "meio oficial" das plataformas de gerenciamento de agenda de se comunicarem. Apesar disso, a depender do software o qual o seu usuário estará utilizando para abrir o arquivo iCalendar é possível que algumas etapas a mais sejam necessárias para se adicionar o evento na agenda. No meu caso, tive problemas principalmente com o Outlook Calendar em versões desktop mais antigas onde o mesmo não adicionava o evento automaticamente à agenda por interpretar o arquivo (neste caso recebido em anexo por e-mail) como potencialmente perigoso. Sendo neste caso então necessário confirmar num check-box a opção de "Reconheço a confiabilidade do arquivo!" para conseguir adicionar o mesmo a agenda.

Além deste caso, como veremos a seguir, é possível definir no escopo do arquivo uma propriedade com o nome de 'DESCRIPTION' onde é possível adicionar uma descrição do evento a ser exibida no calendário, a depender do software (neste caso mais especificamente do interpretador de texto que o software usada) era possível ou não adicionar tags HTML nesta propriedade. A depender do caso as mesmas eram interpretadas como texto comum ao invés de comporem um Link por exemplo.

Alguns dos softwares nos quais não tive qualquer tipo de problema foram o Google Calendar (testado em verão mobile e web) e o Apple Calendar (testado em versão mobile).

Como gerar um arquivo ICS com Java?

Por ser um arquivo tipo texto é possível trabalhar com o mesmo tratando-o como tal... Apesar disso, para tornar o aprendizado mais dinâmico vamos utilizar uma biblioteca para fazer a inserção dos atributos necessários nesse arquivo. A biblioteca a ser utilizada é a iCal4j.

Recomendo fortemente que se for sua primeira experiência criando qualquer tipo de arquivo que você veja primeiramente o post sobre "Como criar um arquivo .TXT usando Java". Deste modo você irá ter uma noção mais básica sobre como esse processo funciona em menor escala, isso vai tornar o entendimento deste post muito mais simples.

Após feito o download da biblioteca podemos iniciar a implementação do nosso código com os seguintes passos:

Passo 1: Adicionar a dependência do iCal4j ao seu projeto Java.

Se você tem dúvidas de como adicionar uma dependência ao seu projeto e/ou de como deve criar um projeto em Java temos um post dedicado a explicar como isso pode ser feito disponível clicando aqui.

Passo 2: Criar o seu arquivo Java e importar os seguintes objetos da biblioteca iCal4j.

import net.fortuna.ical4j.model.property.Location;
import net.fortuna.ical4j.model.property.ProdId;
import net.fortuna.ical4j.model.property.Version;
import net.fortuna.ical4j.model.DateTime;
import net.fortuna.ical4j.model.component.VEvent;
import net.fortuna.ical4j.model.property.CalScale;
import net.fortuna.ical4j.model.property.Description;

Passo 3: dentro da classe Java, no método main crie o arquivo já especificando a extensão com .ics.

public class iCalendar {

	public static void main(String[] args) {
		
		String calFile = "c:TestCalendar.ics";
		File arquivoCal = new File(calFile);
		try {
			arquivoCal.createNewFile();
		} catch (IOException e1) {
			e1.printStackTrace();
		}

Como exemplo neste caso especificamos o diretório no qual o arquivo será criado como o próprio diretório do projeto. S evocê estiver com dificuldade para realizar este passo recomendo novamente a leitura do post "Como criar um arquivo .TXT com Java." a mudança de lá pra cá se trata unicamente da extesão do arquivo.

Passo 4: instanciar um objeto do tipo GregorianCalendar para representar o início do evento.

        java.util.Calendar inicio = new GregorianCalendar();

É importante a instanciação de um objeto deste tipo pois é o tipo de data que se espera que seja inserida no arquivo iCalendar.

Passo 5: receber os atributos a serem inseridos no evento.

		Scanner sc = new Scanner(System.in);
		
		//data inicio
		System.out.print("Ano i: ");
		int ano_inicio = sc.nextInt();
		
		System.out.print("Mês i: ");
		int mes_inicio = sc.nextInt();
		
		System.out.print("Dia do mês i: ");
		int dia_do_mes_inicio = sc.nextInt();
		
		System.out.print("Hora do Dia i: ");
		int hora_inicio = sc.nextInt();
		
		System.out.print("Minuto i: ");
		int minuto_inicio = sc.nextInt();
		
		inicio.set(java.util.Calendar.MONTH, mes_inicio);
		inicio.set(java.util.Calendar.DAY_OF_MONTH, dia_do_mes_inicio);
		inicio.set(java.util.Calendar.YEAR, ano_inicio);
		inicio.set(java.util.Calendar.HOUR_OF_DAY, hora_inicio);
		inicio.set(java.util.Calendar.MINUTE, minuto_inicio);

Passo 6: repetir os dois passos anteriores para receber os dados referentes ao fim do evento.

		java.util.Calendar fim = new GregorianCalendar();
		
		//data fim
		System.out.print("Ano f: ");
		int ano_fim = sc.nextInt();
		
		System.out.print("Mês f: ");
		int mes_fim = sc.nextInt();
		
		System.out.print("Dia do mês f: ");
		int dia_do_mes_fim= sc.nextInt();
		
		System.out.print("Hora do Dia f: ");
		int hora_fim = sc.nextInt();
		
		System.out.print("Minuto f: ");
		int minuto_fim = sc.nextInt();
		
		fim.set(java.util.Calendar.MONTH, mes_fim);
		fim.set(java.util.Calendar.DAY_OF_MONTH, dia_do_mes_fim);
		fim.set(java.util.Calendar.YEAR, ano_fim);
		fim.set(java.util.Calendar.HOUR_OF_DAY, hora_fim);
		fim.set(java.util.Calendar.MINUTE, minuto_fim);

Passo 7: receber os dados referentes ao local, descrição e assunto do evento.

		System.out.print("Assunto: ");
		String assunto = sc.next();
		
		System.out.print("Local: ");
		String local = sc.next();
		
		System.out.print("Descrição: ");
		String descricao = sc.next();

Passo 8: criar um objeto do tipo VEvent (um evento para a agenda).

		DateTime inicioDaReuniao = new DateTime(inicio.getTime());
		DateTime fimDaReuniao = new DateTime(fim.getTime());
		
		VEvent reuniao = new VEvent(inicioDaReuniao, fimDaReuniao, assunto);
		
		reuniao.getProperties().add(new Location(local));
		reuniao.getProperties().add(new Description(descricao));

Aqui, além de criar o objeto tipo VEvent, adicionamos as propriedade de local e descrição ao mesmo.

Passo 9: criar o calendário em si e adicionar a reunião ao mesmo.

		net.fortuna.ical4j.model.Calendar calendario = new net.fortuna.ical4j.model.Calendar();
		
		calendario.getProperties().add(new ProdId("-//Ben Fortuna//iCal4j 1.0//EN"));
		calendario.getProperties().add(Version.VERSION_2_0);
		calendario.getProperties().add(CalScale.GREGORIAN);
		
		calendario.getComponents().add(reuniao);

Além de adicionar a reunião na última linha, especificamos aqui a escala do calendário (CalScale), o ProdId e também a Version utilizada no arquivo.

Feito isto seu arquivo tipo calendário esta pronto para ser anexado em um e-mail para ser enviado por exemplo. Para ver como ele ficou você pode ir até o path onde o mesmo foi criado e abri-lo como um interpretador de arquivos de texto convencionais.

Além dos atributos que definimos existem diversos outros que estão melhor especificados diretamente na documentação da biblioteca iCal4j.

Espero ter ajudado de alguma maneira, se você tiver ficado com alguma dúvida e ou tiver algum comentário a fazer logo abaixo se encontram minha redes sociais pessoais.