simple-arm is based on the Managed typeclass, which opens and
closes resources. There are three ways to use it: for-comprehensions,
the using function, and ResourceScopes:
import com.rojoma.simplearm.util._
val linesCopied = for {
in <- managed(new java.io.FileReader(inName))
out <- managed(new java.io.FileWriter(outName))
} {
copyLines(in, out)
}
val linesCopied = using(new java.io.FileReader(inName), new java.io.FileWriter(outName)) { (in, out) =>
copyLines(in, out)
}
// return an iterator which is managed by the given ResourceScope.
// Closing the iterator through the scope will also ensure the
// underlying Source is closed.
def fileAsIterator(in: File, rs: ResourceScope): Iterator[String] = {
val source = rs.open(Source.fromFile(in))
rs.openUnmanaged(source.getLines(), transitiveClose = List(source))
}The first two are almost completely equivalent; the
for-comprehension requires using managed but the using function
separates the resource from its name. In a for-comprehension,
earlier resources are available at the time later ones are
initialized, of course.
Managed is a monad; invoking flatMap or map on it will produce a
new Managed. To actually cause the effects to occur, run or
foreach must be used. This is a change from simple-arm 1, where
Managed supported the for-comprehension syntactic sugar without
actually being a monad. foreach and run are synonyms; in
particular, foreach will return the result of the function it is
passed:
val x = for(r <- managed(...)) yield 5 // x is Managed[Int]
val y = for(r <- managed(...)) 5 // y is IntSBT:
libraryDependencies += "com.rojoma" %% "simple-arm-v2" % "2.3.2"While for Maven, the pom snippets are:
<dependencies>
<dependency>
<groupId>com.rojoma</groupId>
<artifactId>simple-arm-v2_${scala.version}</artifactId>
<version>2.3.2</version>
</dependency>
</dependencies>Resource-management is defined as follows:
- Create the resouce by evaluating the by-name parameter passed to
managedorusing. - Open the resource by calling the
openPreTrymethod on the typeclass instance with it. By default, this is a no-op. If the open returns normally, the resource is considered to be under management and will be closed. - Open the resource by calling the
openPostTrymethod on the typeclass instance. By default, this is a no-op. - Do whatever is required with this resource.
- If the "whatever" returns normally ("normally" includes via
ControlThrowable), invokecloseon the typeclass instance with it. Otherwise, invokecloseAbormallywith both the resource object and the exception. By default, this simply defers toclose. IfcloseAbnormallythrows a non-ControlThrowableexception, it is added to the original exception's suppressed list.
Resources in using are acquired in left-to-right order and released
in the opposite order. ResourceScope will, unless resources are
explicitly closed early, also close resources in the opposite order
from which they were added. Note that transferring resources between
ResourceScopes may not preserve the exact order. Instead, it uses
some order consistent with the DAG produced by resources'
transitiveClose parameters.