Объект scala.util.Using

объект Using

Утилита для автоматического управления ресурсами. Она может использоваться для выполнения операции с ресурсами, после чего ресурсы освобождаются в обратном порядке их создания.

Использование

Существует несколько способов автоматического управления ресурсами с помощью Using. Если вам нужно управлять только одним ресурсом, метод apply является наиболее простым; он оборачивает открытие ресурса, операцию и освобождение ресурса в Try.

Пример:

val lines: Try[Seq[String]] =
  Using(new BufferedReader(new FileReader("file.txt"))) { reader =>
    Iterator.unfold(())(_ => Option(reader.readLine()).map(_ -> ())).toList
  }

Если вам нужно управлять несколькими ресурсами, следует использовать Using.Manager. Он позволяет управлять произвольным количеством ресурсов, чьё создание, использование и освобождение все оборачиваются в Try.

Пример:

val lines: Try[Seq[String]] = Using.Manager { use =>
  val r1 = use(new BufferedReader(new FileReader("file1.txt")))
  val r2 = use(new BufferedReader(new FileReader("file2.txt")))
  val r3 = use(new BufferedReader(new FileReader("file3.txt")))
  val r4 = use(new BufferedReader(new FileReader("file4.txt")))

  // use your resources here
  def lines(reader: BufferedReader): Iterator[String] =
    Iterator.unfold(())(_ => Option(reader.readLine()).map(_ -> ()))

  (lines(r1) ++ lines(r2) ++ lines(r3) ++ lines(r4)).toList
}

Если вы хотите избежать обертывания управления и операций в Try, вы можете использовать Using.resource, которое выбрасывает любые возникшие исключения.

Пример:

val lines: Seq[String] =
  Using.resource(new BufferedReader(new FileReader("file.txt"))) { reader =>
    Iterator.unfold(())(_ => Option(reader.readLine()).map(_ -> ())).toList
  }

Поведение при подавлении исключений

Если возникают два исключения (например, при выполнении операции и закрытии ресурса), одно из них перебрасывается, а другое добавляется к нему как подавленное исключение. Если два исключения имеют разную «степень тяжести» (см. ниже), исключение с более высокой степенью тяжести перебрасывается, а исключение с более низкой степенью тяжести добавляется к нему как подавленное исключение. Если два исключения имеют одинаковую степень тяжести, то сначала перебрасывается то, которое было брошено первым, а второе, брошенное вторым, добавляется к нему как подавленное исключение. Если исключение является ControlThrowable или если оно не поддерживает подавление (см. конструктор Throwable с параметром enableSuppression), исключение, которое должно было быть подавлено, вместо этого отбрасывается.

Исключение сортируются по степени тяжести от наивысшей к наименьшей следующим образом:

java.lang.VirtualMachineError
java.lang.LinkageError
java.lang.InterruptedException и java.lang.ThreadDeath
исключения, не являющиеся критическими, за исключением scala.util.control.ControlThrowable
scala.util.control.ControlThrowable
все остальные исключения

Когда возникает более двух исключений, первые два комбинируются и перебрасываются, как описано выше, а каждое последующее брошенное исключение комбинируется по мере его возникновения.

Источник: Using.scala
Линейные супертипы: AnyRef, Any

Члены типа

final класс Manager extends AnyRef

Управляющий ресурсами.

Ресурсы могут быть зарегистрированы в менеджере, вызвав acquire; такие ресурсы будут освобождаться в обратном порядке их получения при закрытии менеджера, независимо от каких-либо исключений, выброшенных во время использования.

См. основную документацию по Using для получения подробной информации о поведении при подавлении исключений.

Примечание

Рекомендуется для разработчиков API требовать неявного Manager для создания настраиваемых ресурсов и вызывать acquire при создании этих ресурсов. Это гарантирует, что ресурс обязательно будет управляться автоматически и делает невозможным забыть об этом. Пример:

class SafeFileReader(file: File)(implicit manager: Using.Manager)
  extends BufferedReader(new FileReader(file)) {

  def this(fileName: String)(implicit manager: Using.Manager) = this(new File(fileName))

  manager.acquire(this)
}

тракт Releasable[-R] extends AnyRef

Тип-маркер, описывающий, как освободить определенный тип ресурса.

Ресурс — это всё, что нужно освободить, закрыть или иначе очистить после завершения его использования, а ожидание его очистки сборкой мусора неприемлемо. Например, экземпляр java.io.OutputStream считается ресурсом, так как важно закрыть поток после завершения его использования.

Экземпляр Releasable необходим для автоматического управления ресурсом с помощью Using. Неявный экземпляр предоставляется для всех типов, расширяющих java.lang.AutoCloseable.

R: тип ресурса

Члены значения

final def !=(arg0: Any): Boolean

Проверка двух объектов на неравенство.

returns: true если !(this == that), false в противном случае.

Определяющие классы: AnyRef → Any

final def ##(): Int

Эквивалентно x.hashCode за исключением boxed числовых типов и null. Для чисел, он возвращает хэш-значение, которое согласуется с равенством значений: если два экземпляра типа значения сравниваются как true, то ## будет создавать одно и то же хэш-значение для каждого из них. Для null возвращает хэш-код, где null.hashCode вызывает NullPointerException.

returns: хэш-значение, согласованное с ==

Определяющие классы: AnyRef → Any

final def ==(arg0: Any): Boolean

Выражение x == that эквивалентно if (x eq null) that eq null else x.equals(that).

returns: true если принимающий объект эквивалентен аргументу; false в противном случае.

Определяющие классы: AnyRef → Any

def apply[R, A](resource: => R)(f: (R) => A)(implicit arg0: Releasable[R]): Try[A]

Выполняет операцию с использованием ресурса, а затем освобождает ресурс, даже если операция вызывает исключение.

См. основную документацию для Using для получения полной информации о поведении подавления.

returns: a Try содержащий исключение, если одно или несколько были выброшены, или результат операции, если исключения не были выброшены

final def asInstanceOf[T0]: T0

Привести принимающий объект к типу T0.

Обратите внимание, что успех приведения во время выполнения является модульным по отношению к семантике стирания Scala. Поэтому выражение 1.asInstanceOf[String] вызовет ClassCastException во время выполнения, а выражение List(1).asInstanceOf[List[String]] — нет. В последнем примере, поскольку аргумент типа стирается в процессе компиляции, невозможно проверить, являются ли содержимое списка запрашиваемого типа.

returns: принимающий объект.

Определяющие классы: Any
Выбрасываемые исключения: ClassCastException если принимающий объект не является экземпляром стирания типа T0.

def clone(): AnyRef

Создать копию принимающего объекта.

Реализация метода clone по умолчанию зависит от платформы.

returns: копия принимающего объекта.

Атрибуты: protected[java.lang]
Определяющие классы: AnyRef
Аннотации: @throws(classOf[java.lang.CloneNotSupportedException]) @native()
Примечание: не указано в SLS как член AnyRef

final def eq(arg0: AnyRef): Boolean

Проверяет, является ли аргумент (that) ссылкой на принимающий объект (this).

Метод eq реализует отношение эквивалентности для не-null экземпляров AnyRef, и имеет три дополнительных свойства:

x

y

AnyRef

x.eq(y)

true

false

x

AnyRef

x.eq(null)

null.eq(x)

false

null.eq(null)

true

При переопределении методов equals или hashCode, важно убедиться, что их поведение согласуется с равенством ссылок. Поэтому, если два объекта являются ссылками друг на друга (o1 eq o2), они должны быть равны друг другу (o1 == o2) и должны иметь одинаковое хэш-значение (o1.hashCode == o2.hashCode).

returns: true если аргумент является ссылкой на принимающий объект; false в противном случае.

Определяющие классы: AnyRef

def equals(arg0: AnyRef): Boolean

Метод равенства для ссылочных типов. Реализация по умолчанию делегирует eq.

См. также equals в scala.Any.

returns: true если принимающий объект эквивалентен аргументу; false в противном случае.

Определяющие классы: AnyRef → Any

def finalize(): Unit

Вызывается сборщиком мусора для принимающего объекта, когда больше нет ссылок на объект.

Подробности о том, когда и вызывается ли метод finalize, а также взаимодействие между finalize и нелокальными возвратами и исключениями, зависят от платформы.

Атрибуты: protected[java.lang]
Определяющие классы: AnyRef
Аннотации: @throws(classOf[java.lang.Throwable])
Примечание: не указано в SLS как член AnyRef

final def getClass(): Class[_ <: AnyRef]

Возвращает представление класса объекта во время выполнения.

returns: объект класса, соответствующий типу получателя во время выполнения.

Definition Classes: AnyRef → Any
Annotations: @native()

def hashCode(): Int

Метод hashCode для ссылочных типов. См. hashCode в scala.Any.

returns: значение хэш-кода для этого объекта.

Definition Classes: AnyRef → Any
Annotations: @native()

final def isInstanceOf[T0]: Boolean

Проверка, является ли динамический тип объекта-получателя T0.

Обратите внимание, что результат проверки выполняется с учётом правил стирания Scala. Следовательно, выражение 1.isInstanceOf[String] вернёт false, а выражение List(1).isInstanceOf[List[String]] вернёт true. В последнем примере, поскольку тип аргумента стирается во время компиляции, невозможно проверить, относятся ли элементы списка к указанному типу.

returns: true если объект-получатель является экземпляром стираемого типа T0; false в противном случае.

Definition Classes: Any

final def ne(arg0: AnyRef): Boolean

Эквивалентно !(this eq that).

returns: true если аргумент не является ссылкой на объект-получатель; false в противном случае.

Definition Classes: AnyRef

final def notify(): Unit

Разбуживает один поток, ожидающий монитор объекта-получателя.

Definition Classes: AnyRef
Annotations: @native()
Note: не указано SLS как член AnyRef

final def notifyAll(): Unit

Разбуживает все потоки, ожидающие монитор объекта-получателя.

Definition Classes: AnyRef
Annotations: @native()
Note: не указано SLS как член AnyRef

def resource[R, A](resource: R)(body: (R) => A)(implicit releasable: Releasable[R]): A

Выполняет операцию с ресурсом, а затем освобождает ресурс, даже если операция вызывает исключение. Этот метод аналогичен Java try-with-resources.

См. основную документацию по Using для получения подробной информации о поведении подавления.

R: тип ресурса
A: тип возвращаемого значения операции
resource: ресурс
body: операция для выполнения с ресурсом
returns: результат операции, если ни операция, ни освобождение ресурса не вызывают исключение

def resources[R1, R2, R3, R4, A](resource1: R1, resource2: => R2, resource3: => R3, resource4: => R4)(body: (R1, R2, R3, R4) => A)(implicit arg0: Releasable[R1], arg1: Releasable[R2], arg2: Releasable[R3], arg3: Releasable[R4]): A

Выполняет операцию с четырьмя ресурсами, а затем освобождает ресурсы в обратном порядке, даже если операция вызывает исключение. Этот метод аналогичен Java try-with-resources.

См. основную документацию по Using для получения подробной информации о поведении подавления.

R1: тип первого ресурса
R2: тип второго ресурса
R3: тип третьего ресурса
R4: тип четвёртого ресурса
A: тип возвращаемого значения операции
resource1: первый ресурс
resource2: второй ресурс
resource3: третий ресурс
resource4: четвёртый ресурс
body: операция для выполнения с ресурсами
returns: результат операции, если ни операция, ни освобождение ресурсов не вызывают исключение

def resources[R1, R2, R3, A](resource1: R1, resource2: => R2, resource3: => R3)(body: (R1, R2, R3) => A)(implicit arg0: Releasable[R1], arg1: Releasable[R2], arg2: Releasable[R3]): A

Выполняет операцию с тремя ресурсами и затем освобождает ресурсы в обратном порядке, даже если операция вызывает исключение. Этот метод работает аналогично try-with-resources в Java.

См. основную документацию по Using для подробной информации о поведении подавления исключений.

R1: тип первого ресурса
R2: тип второго ресурса
R3: тип третьего ресурса
A: тип возвращаемого значения операции
resource1: первый ресурс
resource2: второй ресурс
resource3: третий ресурс
body: операция, выполняемая с использованием ресурсов
returns: результат операции, если ни операция, ни освобождение ресурсов не вызывают исключения

def resources[R1, R2, A](resource1: R1, resource2: => R2)(body: (R1, R2) => A)(implicit arg0: Releasable[R1], arg1: Releasable[R2]): A

Выполняет операцию с двумя ресурсами и затем освобождает ресурсы в обратном порядке, даже если операция вызывает исключение. Этот метод работает аналогично try-with-resources в Java.

См. основную документацию по Using для подробной информации о поведении подавления исключений.

R1: тип первого ресурса
R2: тип второго ресурса
A: тип возвращаемого значения операции
resource1: первый ресурс
resource2: второй ресурс
body: операция, выполняемая с использованием ресурсов
returns: результат операции, если ни операция, ни освобождение ресурсов не вызывают исключения

final def synchronized[T0](arg0: => T0): T0

Definition Classes: AnyRef

def toString(): String

Создает строковое представление этого объекта. По умолчанию представление зависит от платформы. На платформе Java это конкатенация имени класса, «@» и хэш-кода объекта в шестнадцатеричном формате.

returns: строковое представление объекта.

Definition Classes: AnyRef → Any

final def wait(): Unit

Definition Classes: AnyRef
Annotations: @throws(classOf[java.lang.InterruptedException])

final def wait(arg0: Long, arg1: Int): Unit

Definition Classes: AnyRef
Annotations: @throws(classOf[java.lang.InterruptedException])

final def wait(arg0: Long): Unit

Definition Classes: AnyRef
Annotations: @throws(classOf[java.lang.InterruptedException]) @native()

object Manager

object Releasable

© 2002-2019 EPFL, with contributions from Lightbend.
Licensed under the Apache License, Version 2.0.
https://www.scala-lang.org/api/2.13.0/scala/util/Using$.html