Instrução import do Java

Assim que o seu código reside em um pacote, qualquer código externo a esse pacote precisa se referir aos seus tipos pelo nome completamente qualificado (com.w3docs.parser.Tokenizer) ou importando-os, para que o nome curto seja suficiente. Imports não carregam nada, não copiam nada e não afetam o runtime — são apenas uma conveniência em tempo de compilação que informa ao compilador o que Tokenizer significa nesse arquivo. Três formas cobrem tudo o que você precisará: tipo único, sob demanda (curinga) e estático.

Onde ficam os imports

Todo arquivo-fonte Java segue a mesma ordem fixa:

package com.w3docs.parser;          // optional: at most one

import java.util.List;              // zero or more imports
import java.util.Map;

public class Tokenizer { /* ... */ }

package primeiro (se houver), depois os imports e, por último, as declarações de tipos. Qualquer outra coisa é um erro de compilação.

Imports de tipo único

A forma mais comum nomeia uma única classe:

import java.util.ArrayList;

ArrayList<String> names = new ArrayList<>();

Após o import, toda menção não qualificada de ArrayList no arquivo é resolvida para java.util.ArrayList. Você ainda pode escrever o nome completamente qualificado no mesmo arquivo, caso precise desambiguar de outro ArrayList em algum lugar.

Imports sob demanda (curinga)

Para importar tudo de um pacote, use *:

import java.util.*;

List<String> names = new ArrayList<>();
Map<String, Integer> counts = new HashMap<>();

O curinga importa toda classe pública de nível superior de java.util — mas não os subpacotes. import java.util.*; não concede acesso a nada de java.util.concurrent; isso exige um import java.util.concurrent.*; separado. Também não existe o atalho import java.*; — o próprio java não contém classes, apenas subpacotes.

Um debate de estilo comum: imports de tipo único tornam as dependências do arquivo explícitas e legíveis; curingas mantêm o bloco de imports enxuto. As IDEs lidam com ambos sem dificuldade, então é principalmente uma escolha de estilo do projeto. O Google Java Style Guide proíbe curingas; muitos projetos de código aberto os permitem. Escolha um estilo e seja consistente.

Imports estáticos

Um import estático traz um membro static — um método ou campo — para o escopo, permitindo chamá-lo sem nomear a sua classe:

import static java.lang.Math.PI;
import static java.lang.Math.sqrt;

double hypotenuse(double a, double b) {
  return sqrt(a * a + b * b);   // not Math.sqrt
}

Imports estáticos se destacam em código de testes — assertEquals(...) é mais legível que Assertions.assertEquals(...) — e em fórmulas matemáticas intensivas, onde o nome da classe é apenas ruído. Tornam-se um problema quando usados em excesso: quem lê o arquivo precisa consultar os imports para descobrir de onde vem um assertThat(...) simples. Use-os quando os nomes das funções forem bem conhecidos e não ambíguos no contexto.

Você também pode usar curingas em imports estáticos: import static java.lang.Math.*; importa todos os membros públicos estáticos de Math. As mesmas ressalvas sobre clareza se aplicam.

O que é importado automaticamente

O Java importa algumas coisas automaticamente e você nunca precisa escrevê-las:

• Toda classe em java.lang — String, Object, Math, Integer, Thread, Throwable e as demais.
• Toda classe no seu próprio pacote.

É por isso que você pode usar String e System.out.println sem uma linha de import. Qualquer outra coisa precisa ser importada explicitamente.

Resolvendo conflitos de nomes

Dois imports para o mesmo nome simples não compilam — java.util.Date e java.sql.Date não podem ser importados juntos no mesmo arquivo. A solução é importar um e qualificar o outro:

import java.util.Date;            // imported short

// Use java.sql.Date by its full name where it appears:
java.sql.Date dbDate = resultSet.getDate(1);
Date now = new Date();

Um import de tipo único sempre prevalece sobre um curinga. Se import java.util.*; e import java.sql.Date; estiverem ambos presentes, um Date simples significa java.sql.Date — o import explícito de tipo único tem precedência sobre o sob demanda, então esse caso compila sem problemas. Apenas dois imports de tipo único para o mesmo nome simples constituem um erro.

Esse é o mesmo problema que o capítulo de pacotes destacou, visto pelo lado do import.

Um exemplo prático

Este programa importa tipos nas três formas — único, curinga, estático — e verifica em tempo de execução que as classes resultantes são exatamente as desses pacotes.

Os três primeiros imports cobrem todas as formas que a linguagem possui. Observe que o curinga import java.util.*; é o que torna List, Collections e Date disponíveis — o import java.util.ArrayList; explícito é redundante neste arquivo, mas é o tipo de linha que um guia de estilo de projeto pode exigir por legibilidade.

O que vem a seguir

Você viu como extrair tipos de pacotes. A seguir, você fará o outro lado — declarar o seu próprio pacote e organizar os arquivos para que tanto o compilador quanto a JVM fiquem satisfeitos. Continue em criando pacotes personalizados em Java.

Prática