detach ( )/ clear ( )/ remove ( )/ refresh ( )

1. Ручное управление EntityManager

Методы detach(), clear(), remove() и refresh() — это ручные рычаги управления EntityManager. Если Hibernate — автопилот, то эти методы позволяют точечно вмешаться: отсоединить объект, очистить контекст, пометить сущность на удаление или перечитать её из базы. В обычном CRUD-коде они нужны не каждый день, но как только вы начинаете понимать модель выполнения, они перестают быть загадочными заклинаниями из StackOverflow и становятся нормальными инженерными инструментами.

После persist(), find() и getReference() картина уже видна: сущности входят в context и начинают жить по его правилам. Теперь нужен второй кусок той же модели — как эту связь с context явно поменять: отцепить один объект, очистить весь контекст, пометить сущность на удаление или перечитать её из базы.

Ключевая мысль простая: persistence context — это не абстракция для красоты, а «рабочий блокнот» Hibernate. Пока объект managed, Hibernate вправе считать его «своим»: держать в first-level cache, отслеживать его состояние и планировать SQL-операции. А эти четыре метода позволяют явно сказать Hibernate, что именно вы хотите сделать с объектом: перестать его вести, забыть всё сразу, пометить на удаление или выбросить локальные изменения и перечитать состояние из базы. Здесь нам важны именно переходы между состояниями и факт, связан ли объект с context; этого уже достаточно, чтобы перестать путать эти методы с магическими кнопками save/delete.

Чтобы всё было максимально наблюдаемо, мы будем постоянно задавать два контрольных вопроса. Первый: «Сущность сейчас managed или нет?» Для этого отлично подходит entityManager.contains(entity). Второй: «Какая операция реально коснулась базы?» Для этого мы смотрим на SQL trace. И вот тут начинается инженерная часть, а не шаманство.

2. detach(): отсоединить сущность

detach() — это самый точечный рычаг. Он говорит Hibernate: «вот конкретно этот объект — больше не под твоим управлением». Не удаляй его из памяти — это вообще не твоя работа, — не трогай базу, просто перестань считать его managed. На уровне модели состояний это классический переход managed → detached, который мы уже видели на карте состояний в начале дня.

Что меняется после detach()

Если держать в голове прошлую лекцию про identity map, то detach() можно описать очень бытово: вы вынули объект из first-level cache текущего persistence context. Объект всё ещё лежит в вашей переменной, его поля можно менять, можно вызывать методы, можно печатать его в лог. Но Hibernate перестаёт относиться к нему как к «живому представителю строки».

Самый простой способ убедиться в этом и одновременно потренировать инженерную привычку — использовать entityManager.contains(...).

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import com.example.commerce.catalog.entity.Product;

@Service
public class EntityStateControlLab {

    @PersistenceContext
    private EntityManager entityManager;

    @Transactional
    public void detachDemo(long productId) {
        // Загружаем сущность: после find() она managed в текущем persistence context
        Product product = entityManager.find(Product.class, productId);

        // contains() — быстрый способ проверить: управляет ли EntityManager этим объектом
        System.out.println(entityManager.contains(product)); // true

        // detach() "вынимает" конкретный объект из контекста (БД при этом не трогаем)
        entityManager.detach(product);

        // Теперь EntityManager больше не отслеживает изменения этого экземпляра
        System.out.println(entityManager.contains(product)); // false
    }
}

Здесь важна не сама печать, а мысль: «я не верю ощущению, я проверяю факт». В deep-dive по Hibernate это почти девиз курса.

detach() и identity map

После detach() вы можете снова сделать find() по тому же id — и получите другой managed-объект, потому что старый сами выкинули из контекста.

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.transaction.annotation.Transactional;

import com.example.commerce.catalog.entity.Product;

@Transactional
public void detachAndFindAgain(long productId) {
    // Первый find(): получаем managed-экземпляр, который лежит в identity map контекста
    Product p1 = entityManager.find(Product.class, productId);

    // Сами "отвязываем" этот экземпляр от контекста
    entityManager.detach(p1);

    // Второй find(): контекст уже не знает p1, поэтому создаст новый managed-экземпляр
    Product p2 = entityManager.find(Product.class, productId);

    // Ссылки разные: это разные Java-объекты, хотя id один и тот же
    System.out.println(p1 == p2); // false
}

Это хороший «мозгоправильный» момент: один и тот же id не гарантирует, что у вас одна и та же Java-ссылка, если вы сами разорвали связь с контекстом.

Когда detach() реально бывает полезен

В рамках курса нам полезно видеть detach() как учебный микроскоп: он помогает почувствовать грань между «объект живёт в памяти» и «объект живёт под управлением ORM».

В реальных приложениях detach() встречается реже, чем clear(), но бывает уместен в сложных сценариях, когда вы хотите гарантированно сказать: «этот объект больше не участвует в текущей unit of work». Это может быть важно и для предсказуемости, и для памяти, и для отладки. Но если вы начнёте пихать detach() в каждый сервис «на всякий случай», код быстро станет похож на самолёт, где пилот каждые 30 секунд отключает систему стабилизации, потому что «так надёжнее».

3. clear(): очистить persistence context

clear() — это уже «ядерная кнопка» по сравнению с detach(). Если detach() выдёргивает один объект, то clear() говорит: «Hibernate, забудь вообще всё, что ты сейчас ведёшь». То есть весь persistence context очищается, first-level cache становится пустым, а все ранее managed-сущности в этом контексте фактически превращаются в detached — с точки зрения связи с текущим EntityManager.

Психологически clear() удобно представлять как «перезапуск памяти» для ORM внутри текущей транзакции. Но с важной оговоркой: ваши Java-ссылки никуда не исчезают. И вот здесь начинаются самые типичные ошибки: объект лежит в переменной, вы его видите, но Hibernate его больше не «держит». Это как знакомый в телефоне: контакт есть, но вы удалили его из адресной книги — позвонить-то можно, но книга уже не подтверждает, что это тот же человек.

Наблюдаем эффект clear() через == и contains()

Давайте сделаем маленький эксперимент на Product из нашего Commerce Persistence Lab. Он отлично показывает, что clear() сбрасывает identity map.

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.transaction.annotation.Transactional;

import com.example.commerce.catalog.entity.Product;

@Transactional
public void clearDemo(long productId) {
    // Загружаем сущность: она managed и находится в first-level cache текущего контекста
    Product p1 = entityManager.find(Product.class, productId);

    // clear() очищает весь persistence context: все managed-сущности станут detached
    entityManager.clear(); // контекст пустой

    // Повторный find() вернёт новый managed-экземпляр (identity map уже сброшен)
    Product p2 = entityManager.find(Product.class, productId);

    // Java-ссылки разные — это два разных объекта
    System.out.println(p1 == p2);                   // false

    // p1 больше не под управлением EntityManager
    System.out.println(entityManager.contains(p1)); // false

    // p2 — свежий managed-объект
    System.out.println(entityManager.contains(p2)); // true
}

Это один из самых честных способов «пощупать» first-level cache руками. С точки зрения БД вы читаете одну и ту же строку. С точки зрения Java — у вас два разных объекта. И это не «ошибка Hibernate», а прямой результат того, что вы сами очистили контекст.

Риски clear()

Главная ловушка clear() даже не в том, что он «обнуляет кэш», а в том, что он делает ваш текущий объектный граф внезапно неуправляемым. Если вы где-то дальше по коду продолжите работать с уже загруженными сущностями как с managed — например, ожидая, что ORM «сам всё увидит», — то получите поведение в духе «оно не сохранилось» или «метод упал», и будете ругать Hibernate. Хотя ругать нужно будет… себя вчерашнего, который поставил clear() посреди сценария.

В этой лекции clear() нужен прежде всего как инструмент понимания: показать границу context и роль identity map. Но полезно сразу запомнить и практический смысл: после операций, которые обходят обычную managed-модель, неочищенный context легко начинает держать устаревшие данные.

4. remove(): пометить сущность на удаление

remove() звучит как «удалить объект», и новичка это название легко сбивает. Мозг тут же рисует картинку: объект исчез из памяти, Java-ссылка стала null, и вообще всё стёрлось. Реальность гораздо прозаичнее: remove() работает внутри persistence context, и его смысл — перевести сущность из managed в состояние removed, то есть пометить её на удаление из базы при синхронизации.

И да, как и с persist(), здесь важно не путать «я вызвал метод» и «SQL уже ушёл». Обычно DELETE отправится в базу на коммите транзакции или при явной синхронизации, а remove() — это именно изменение состояния в контексте и планирование будущего DELETE.

remove() требует managed-объект

По правилам JPA, remove() ожидает, что сущность находится под управлением текущего EntityManager. Поэтому типовой и самый понятный сценарий выглядит так: find() → remove().

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.transaction.annotation.Transactional;

import com.example.commerce.catalog.entity.Product;

@Transactional
public void removeDemo(long productId) {
    // Сначала получаем managed-экземпляр в текущем EntityManager
    Product product = entityManager.find(Product.class, productId);

    // remove() помечает сущность как removed (DELETE уйдёт позже, при синхронизации/коммите)
    entityManager.remove(product);
}

Здесь важнее не то, что покажет вспомогательная проверка вроде contains(), а сам смысл состояния: объект уже помечен на удаление внутри текущего unit of work. Он может всё ещё существовать как Java-ссылка, но бизнес-логика не должна относиться к нему как к обычной живой сущности.

remove() для detached-сущности

Если вы попробуете удалить detached-сущность — например, загрузили её в другой транзакции, вышли из неё, а потом принесли объект в новую, — JPA обычно не в восторге. Чаще всего вы получите IllegalArgumentException, потому что EntityManager не управляет этим экземпляром.

Правильная привычка для начинающего звучит скучно, зато спасает часы жизни: если хотите удалить — получите managed-экземпляр в текущей транзакции, а потом удаляйте.

В нашем проекте это будет выглядеть примерно так: «в сервисе загрузить Product по id и удалить». Не надо пытаться «сэкономить» на find(), пока вы не понимаете всех побочных эффектов. Экономия на одном SELECT иногда превращается в два часа разбора «а почему оно упало на удалении».

Что важно помнить после remove() в том же контексте

После remove() не стоит строить логику на вспомогательных проверках вроде повторного find() по тому же id. Конкретные детали такого поведения лучше не делать своей опорой. Надёжное правило проще: в рамках текущего unit of work сущность уже помечена на удаление, и дальше код должен исходить именно из этого.

5. refresh(): перечитать из базы

После detach() и clear() нужен симметричный рычаг: иногда объект не хочется отцеплять или удалять, наоборот, нужно выбросить локальные изменения и снова взять состояние из базы.

refresh() — метод, который чаще всего либо не знают, либо знают и боятся трогать, и в целом это понятно. Он нужен, когда вы хотите сказать Hibernate: «возьми текущую версию данных из базы и положи её обратно в мой managed-объект, отменив локальные изменения». Это не про «ускорить кэш», а про консистентность: вы признаёте, что состояние объекта в памяти вам больше не нравится, и просите ORM принудительно синхронизироваться с тем, что лежит в таблице.

Важно сразу зафиксировать две вещи. Во‑первых, refresh() работает только для managed сущности. Во‑вторых, refresh() почти неизбежно делает SQL SELECT, потому что ему нужно перечитать данные. Поэтому refresh() — это сознательный и довольно «дорогой» рычаг, который стоит применять редко, но понимание его поведения очень укрепляет вашу модель происходящего.

Демонстрация: “передумал — верни как в базе”

Представим, вы загрузили товар, поменяли имя — случайно или специально, — а потом решили: «нет, хочу обратно оригинал».

import jakarta.persistence.EntityManager;
import jakarta.persistence.PersistenceContext;
import org.springframework.transaction.annotation.Transactional;

import com.example.commerce.catalog.entity.Product;

@Transactional
public void refreshDemo(long productId) {
    // Получаем managed-объект: refresh() работает только с такими сущностями
    Product product = entityManager.find(Product.class, productId);

    // Делаем локальное изменение в памяти (ещё не факт, что оно ушло в БД)
    product.setName("Temporary name");

    // refresh() перезапишет поля значениями из БД, "отменив" локальные изменения
    entityManager.refresh(product);

    // После refresh() имя снова будет как в базе
    System.out.println(product.getName()); // имя снова как в базе
}

Если у вас включён SQL trace, вы увидите SELECT ... FROM product WHERE id=? или что-то очень близкое. И это нормально: refresh() — не телепатия, ему нужно реально сходить в базу.

Когда refresh() бывает уместен в реальной жизни

Самый простой кейс: вы сделали изменения в объекте в рамках транзакции, но потом решили их отменить — не создавая новую сущность, не копируя поля обратно вручную и не устраивая себе “undo” через собственный код.

Более прикладной и более редкий кейс: база могла изменить данные сама, например через триггеры, или параллельная транзакция уже закоммитила изменения, а вы хотите увидеть свежие значения в текущем контексте. Тут нужно быть очень аккуратным: refresh() — не замена правильному проектированию транзакционных границ. Но как инструмент диагностики и как «сброс в состояние из базы» он полезен.

refresh() и detached: дружбы не будет

Если объект detached, то refresh() обычно бросит исключение, потому что EntityManager не имеет права «перезаписать» объект, который он не ведёт. И это логично: иначе вы могли бы обновлять что угодно, не имея связи с контекстом.

Поэтому в голове удобно держать простое правило: refresh() — это операция над managed-сущностью, так же как remove(). А detach() и clear() — это операции «снять управление».

6. Шпаргалка по detach/clear/remove/refresh

К этому моменту в голове легко может начаться лёгкая каша: «detach вроде отсоединяет, clear вроде тоже, remove что-то удаляет, refresh что-то перечитывает…». Чтобы мозг не перегревался, полезно держать рядом компактную шпаргалку. Она не заменяет понимание, но отлично помогает быстро проверить свою гипотезу перед тем, как делать выводы по поведению кода.

Таблица сравнения

Мини-схема переходов состояний

stateDiagram-v2
    Transient --> Managed: "persist()"
    Managed --> Detached: "detach()"
    Managed --> Detached: "clear() для всех"
    Managed --> Removed: "remove()"
    Managed --> Managed: "refresh()"

    %% физическое удаление/вставка происходят при синхронизации с БД

Обратите внимание: на схеме нет пункта «удалить объект из памяти». Потому что JPA/Hibernate этим не занимаются. И это хороший момент, чтобы ещё раз отделить две реальности. Java управляет памятью — и сборщик мусора решает, когда объект исчезнет. Hibernate управляет связью объекта с БД через persistence context.

7. Типичные ошибки методов EntityManager

Ошибка №1: ожидание, что remove() “удалит объект из памяти”.
Начинающий часто подсознательно думает: «я же вызвал remove — значит объекта больше нет». Потом удивляется, что переменная всё ещё указывает на объект, методы вызываются, поля читаются. Это нормально: remove() — про состояние внутри persistence context, а не про уничтожение Java-объекта. Если нужно избавиться от ссылки в коде, это уже ваша ответственность, но к ORM это отношения не имеет.

Ошибка №2: вызов remove() или refresh() на detached-сущности.
Очень частый сценарий: объект загрузили в одной транзакции, вышли из неё, потом принесли в другой метод и пытаются «просто удалить» или «просто refresh». Но EntityManager не управляет этим экземпляром, поэтому поведение будет либо исключением, либо неожиданностью. Правильная привычка — внутри текущей транзакции получить managed-экземпляр, обычно через find(), и уже с ним делать remove() или refresh().

Ошибка №3: использовать clear() как “кнопку починить всё”.
clear() иногда воспринимают как универсальный «сброс» и ставят туда, где «что-то странно работает». На короткой дистанции это может успокоить поведение, а на длинной создаёт хаос: у вас остаются ссылки на объекты, которые вы продолжаете менять, но ORM их больше не ведёт. Получается эффект «вроде менял — не сохранилось», и начинается охота на ведьм. clear() полезен, когда вы понимаете, что делаете, а не когда вы просто устали.

Ошибка №4: путаница между detach() и “не вызывать репозиторий save()”.
Интуитивно хочется думать: «если я не вызвал save(), значит изменения не уйдут». Но это мышление из мира ручного SQL. В ORM важно состояние объекта: managed он или detached. detach() — это явный способ перевести объект в detached. Отсутствие вызова save() само по себе не гарантирует «ничего не произойдёт», если объект остаётся managed. Сейчас достаточно запомнить принцип на уровне модели состояний: пока объект остаётся managed, отсутствие вызова save() само по себе ничего не гарантирует.

Ошибка №5: использовать refresh() как повседневную “синхронизацию на всякий случай”.
Иногда разработчик начинает вызывать refresh() после каждого изменения, чтобы «быть уверенным». Это превращает приложение в генератор лишних SELECT и делает код трудно читаемым. refresh() — осмысленный рычаг «верни как в базе», а не ежедневная гигиена. Если вам постоянно нужно «перечитывать из базы», обычно проблема не в отсутствии refresh(), а в том, как спроектирована операция и её границы.