Java Nullableとは？Optionalと@Nullableの使い分けを実例解説【2026年】

String name = "Yamada"; // "Yamada"という文字列オブジェクトを参照
name = null;         // 何も参照しない状態 (null)

int age = 30; // age は 30 という値を持つ
// age = null; // コンパイルエラー！プリミティブ型にnullは代入できない

String text = getSomeText(); // nullが返る可能性があるメソッド

// textがnullの場合、ここでNullPointerExceptionが発生する！
int length = text.length();

String text = getSomeText();

if (text != null) {
    int length = text.length(); // nullでないことを確認してからアクセス
    System.out.println("Length: " + length);
} else {
    System.out.println("Text is null.");
}

// 値が存在する場合
Optional<String> opt1 = Optional.of("Hello");

// 値が存在しない場合 (空)
Optional<String> opt2 = Optional.empty();

// nullかもしれない値から生成
String nullableValue = getNullableValue(); // nullかもしれない値を取得
Optional<String> opt3 = Optional.ofNullable(nullableValue);

Optional<String> optText = findTextById(123); // Optional<String> を返すメソッド

// 従来のnullチェック
// String text = findTextByIdLegacy(123); // String (nullable) を返すメソッド
// if (text != null) {
//    String upperText = text.toUpperCase();
//    if (upperText.length() > 5) {
//        System.out.println(upperText);
//    }
// }

// Optionalを使った場合
optText.map(String::toUpperCase)       // 値があれば大文字に変換
       .filter(s -> s.length() > 5) // 長さが5より大きいかフィルタリング
       .ifPresent(System.out::println); // 条件を満たせば出力

int primitiveInt = 10;
// primitiveInt = null; // コンパイルエラー

Integer wrapperInt = 10;
wrapperInt = null; // OK

public void processUserData(Integer userId, Boolean isActive) {
    // userId (Integer) の null チェック
    if (userId != null) {
        // 安全に int として扱える
        int id = userId; // アンボクシング
        System.out.println("Processing user ID: " + id);
    } else {
        System.out.println("User ID is missing.");
    }

    // isActive (Boolean) の null チェック
    // Boolean.TRUE.equals() を使うと、nullの場合も安全に比較できる
    if (Boolean.TRUE.equals(isActive)) {
        System.out.println("User is active.");
    } else if (Boolean.FALSE.equals(isActive)) {
        System.out.println("User is inactive.");
    } else {
        // isActive が null の場合の処理
        System.out.println("User active status is unknown.");
    }
}

// 呼び出し例
processUserData(123, true);
processUserData(null, false);
processUserData(456, null);

import javax.annotation.Nullable;

// 例として JSR 305 を使用（新規プロジェクトは JSpecify の org.jspecify.annotations.Nullable を推奨）
public class UserProfile {
    private String name;

    @Nullable
    // 住所は任意入力かもしれない
    private String address;

    public UserProfile(String name, @Nullable String address) {
        this.name = name;
        this.address = address;
    }

    // @Nullable なパラメータ
    public void updateAddress(@Nullable String newAddress) {
        this.address = newAddress;
    }

    // @Nullable な戻り値
    @Nullable
    public String getAddress() {
        return this.address;
    }

    public String getName() {
        return this.name;
    }
}

import javax.annotation.Nonnull; // JSR 305 を使用（新規プロジェクトは JSpecify の @NonNull を推奨）
import javax.annotation.Nullable;

public class Order {

    @Nonnull
    // 注文IDは必須
    private final String orderId;

    @Nullable
    // 備考は任意
    private String remarks;

    public Order(@Nonnull String orderId) {
        // 引数も非nullを強制
        if (orderId == null) {
            // 本来はアノテーションプロセッサが検知するが、念のため明示チェック
            throw new IllegalArgumentException("Order ID cannot be null");
        }
        this.orderId = orderId;
    }

    @Nonnull
    // 注文IDは必ず返る
    public String getOrderId() {
        return orderId;
    }

    public void setRemarks(@Nullable String remarks) {
        this.remarks = remarks;
    }

    @Nullable
    public String getRemarks() {
        return remarks;
    }
}

String str1 = null;
String str2 = "";

// str1に対する操作は NullPointerException のリスクがある
// System.out.println(str1.length()); // NullPointerException!

// str2に対する操作は安全
System.out.println(str2.length()); // 0
System.out.println(str2.isEmpty()); // true

// null チェックと空文字チェック
if (str1 != null && !str1.isEmpty()) {
    System.out.println("str1 is not null and not empty.");
} else if (str1 == null) {
    System.out.println("str1 is null.");
} else { // str1 is empty
    System.out.println("str1 is empty.");
}

public enum Status {
    PENDING, PROCESSING, COMPLETED, FAILED;
}

public class Task {
    private String description;
    private Status currentStatus; // enum型の変数もNullable

    public Task(String description) {
        this.description = description;
        // 初期状態を null にするか、特定のenum値にするか？
        // this.currentStatus = null; // 「未開始」をnullで表現？
        this.currentStatus = Status.PENDING; // 「保留」を初期値とする？
    }

    public Status getCurrentStatus() {
        return currentStatus;
    }

    public void setCurrentStatus(Status currentStatus) {
        this.currentStatus = currentStatus;
    }
}

Task task = new Task("Some task");
task.setCurrentStatus(null); // nullを代入

// ...

// currentStatusがnullの場合、ここでNullPointerExceptionが発生する！
// switch (task.getCurrentStatus()) {
//    case PENDING:
//        System.out.println("Pending...");
//        break;
//    // ... 他のケース
// }

// nullチェックが必要
Status status = task.getCurrentStatus();
if (status != null) {
    switch (status) {
       case PENDING:
           System.out.println("Pending...");
           break;
       // ... 他のケース
       default:
            System.out.println("Unknown status");
            break;
    }
} else {
    System.out.println("Status is not set.");
}

import java.util.Arrays;
import java.util.List;
import java.util.stream.Collectors;
import java.util.Objects;

public class StreamNullableDemo {

    public static void main(String[] args) {
        List<String> listWithNulls = Arrays.asList("apple", null, "banana", "cherry", null);

        // 不安全な例: mapでnull要素のメソッドを呼び出すとNPE
        // listWithNulls.stream()
        //         .map(String::toUpperCase) // nullでNPE
        //         .forEach(System.out::println);

        // 方法1: filterでnullを除去する
        System.out.println("--- Filter out nulls ---");
        listWithNulls.stream()
                .filter(Objects::nonNull) // nullでない要素のみを通過させる
                .map(String::toUpperCase)
                .forEach(System.out::println);

        // 方法2: map処理内でnullチェックを行う (少し冗長になる場合がある)
        System.out.println("--- Map with null check ---");
        listWithNulls.stream()
                .map(s -> (s == null) ? "[NULL]" : s.toUpperCase())
                .forEach(System.out::println);

        // 方法3: OptionalとflatMapを組み合わせる (より関数型らしい書き方)
        System.out.println("--- Optional and flatMap ---");
        listWithNulls.stream()
                .map(Optional::ofNullable) // 各要素をOptionalにラップ
                // .flatMap(opt -> opt.map(Stream::of).orElseGet(Stream::empty)) // Java 8
                .flatMap(Optional::stream) // Java 9以降の標準（Java 17/21 LTSでも利用可）: OptionalをStreamに変換 (空なら空Stream)
                .map(String::toUpperCase)
                .forEach(System.out::println);

        // 収集 (Collectors) 時の注意:
        // デフォルトではnull要素があると toMap などで NPE になることがある
        List<String> safeList = listWithNulls.stream()
                                        .filter(Objects::nonNull)
                                        .collect(Collectors.toList());
        System.out.println("--- Collected non-null list ---");
        System.out.println(safeList);
    }
}

import java.util.Optional;
import java.util.Map;
import java.util.HashMap;

public class ReturnTypeDesign {

    private static Map<Integer, String> dataStore = new HashMap<>();
    static {
        dataStore.put(1, "Apple");
        dataStore.put(2, "Banana");
    }

    // 非推奨: nullを返す可能性
    @Nullable // アノテーションで示すことはできるが...
    public String findItemLegacy(int id) {
        return dataStore.get(id); // Map.getはキーがなければnullを返す
    }

    // 推奨: Optionalを返す
    public Optional<String> findItemOptional(int id) {
        return Optional.ofNullable(dataStore.get(id));
    }

    public static void main(String[] args) {
        ReturnTypeDesign design = new ReturnTypeDesign();

        // Legacy呼び出し (nullチェックが必要)
        String item1 = design.findItemLegacy(1);
        if (item1 != null) System.out.println(item1.toUpperCase());

        String item3Legacy = design.findItemLegacy(3);
        // System.out.println(item3Legacy.toUpperCase()); // NullPointerException!

        // Optional呼び出し (安全な処理)
        design.findItemOptional(2)
              .map(String::toUpperCase)
              .ifPresent(System.out::println); // 値があれば大文字で出力

        String item3 = design.findItemOptional(3)
                           .orElse("Not Found"); // 値がなければ"Not Found"
        System.out.println(item3);
    }
}

import java.util.Objects;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;

public class ParameterDesign {

    // 必須パラメータ (NonNull) と任意パラメータ (Nullable)
    public void processData(@Nonnull String id, @Nullable String tag, int value) {
        // 必須パラメータのnullチェック (アノテーションと合わせて二重チェックにもなる)
        Objects.requireNonNull(id, "ID cannot be null");

        System.out.println("Processing ID: " + id);
        System.out.println("Value: " + value);

        // 任意パラメータのnullチェック
        if (tag != null) {
            System.out.println("Tag: " + tag.toLowerCase());
        } else {
            System.out.println("Tag: [Not Provided]");
            // tagがnullの場合のデフォルト処理など
        }
    }

    // 引数にOptionalを使うのは一般的に非推奨
    // public void processOptionalData(Optional<String> optionalTag) { ... }

    public static void main(String[] args) {
        ParameterDesign design = new ParameterDesign();
        design.processData("user123", "important", 100);
        design.processData("item456", null, 200);
        // design.processData(null, "test", 300); // @Nonnull違反 (IDEやツールが警告) / Objects.requireNonNullで実行時エラー
    }
}