Commit 47d97c54 authored by Rajiv Prabhakar's avatar Rajiv Prabhakar
Browse files

v1.5.0 release:

- mvn shade plugin deleted since it is not needed
- Updated README
parent d104cfc9
Pipeline #9074803 failed with stage
in 1 minute and 13 seconds
job1:
script: "mvn clean install"
\ No newline at end of file
......@@ -7,17 +7,21 @@ Principles
RunTimeExceptions over Checked Exceptions
-----------------------------------------
Robert Martin argues in Clean Code that we should always use Unchecked Exceptions, and I agree with him. Suppose for example that you're reading from a file, using the Apache FileUtils library. The library method throws an IOException, forcing you to deal with it as well. But very often, it is perfectly valid to say *"If I ever encounter an error while reading this file, I will let the application exit immediately, or I will let the exception escalate to the outermost main method of my application, where all exceptions will be caught and handled by a generic handler."* If the IOException being thrown was a RunTimeException, this behavior automatically happens. But because the IOException is a checked exception, this forces you to pollute your code with try-catch blocks or throws declarations, throughout your codebase.
Robert Martin argues in Clean Code that we should always use Unchecked Exceptions, and we agree with him.
Suppose for example that you're reading from a file, using the Apache FileUtils library. The library method throws an IOException, forcing you to deal with it as well. But very often, it is perfectly valid to say *"If I ever encounter an error while reading this file, I will let the application exit immediately, or I will let the exception escalate to the outermost main method of my application, where all exceptions will be caught and handled by a generic handler."* If the IOException being thrown was a RunTimeException, this behavior automatically happens. But because the IOException is a checked exception, this forces you to pollute your code with try-catch blocks or throws declarations, throughout your codebase.
There are hundreds of possible reason for any code to fail, and programmers should have the flexibility to decide which of these reasons should be caught and handled programmatically, and which of them should be silently escalated to a system exit or generic exception handler. This is a decision that every application should make for itself, without being forced into it by an external library. Hence why we strive to provide library alternatives that are free of Checked Exceptions.
Simplify Common Code Paths
--------------------------
There are many generic code paths that thousands of programmers around the world are manually implementing individually, over and over again. This is a violation of DRY on a global level. Any code that is so generic that it's widely used, deserves to be refactored into a central library, which can then be reused everywhere. Even if this saves just 1-2 lines of code or a couple of manually invoked method calls, that's still additional complexity and verbosity that can and should be abstracted away.
There are many generic code paths that thousands of programmers around the world are manually implementing individually, over and over again. This is a violation of DRY on a global level, and an unnecessary burden that makes programming less enjoyable. Cava aims to allieviate this problem by providing these common code paths in a library.
Keep It Simple
--------------
We don't believe in magic. We don't believe in doing anything smart or clever. We simply want to write library functions that are simple, clear and intuitive. If another library already does 90% of what we need, we will use that library ourselves. Our goal is not performance. We will never optimize our implementations or interfaces for performance. Our goal is to first and foremost to provide the user with the most convenient utility for their needs, and second, to implement this interface in a manner that makes maintenance as easy as possible.
We don't believe in magic. We don't believe in doing anything smart or clever. We simply want to write library functions that are simple, clear and intuitive. If another library already does 90% of what we need, we will use that library ourselves.
Our goal is not performance. We will never optimize our implementations or interfaces for performance. Our goal is first and foremost to provide the user with the most convenient utility for their needs, and second, to implement this interface in a manner that makes maintenance as easy as possible.
Planned Obsolesence
--------------
......@@ -27,8 +31,8 @@ In an ideal world, other libraries like ApacheCommons and Guava will make us obs
Features
=========
Convert any checked exceptions to run-time exceptions without corrupting the message/toString/stack-trace
-------------
Convert any checked exceptions to run-time exceptions without altering the message/toString/stack-trace
--------------------------------------------------------------------------------------------------------
Replace:
```java
try {
......@@ -116,8 +120,6 @@ return map;
with:
```java
// return Mapc.newHashMap(1, "one", 2, "two", 3); // Throws an IllegalArgumentException
// return Mapc.newHashMap(1, "one", 2, "two", 3, 3); // Throws an IllegalArgumentException
return Mapc.newHashMap(1, "one", 2, "two", 3, "three");
```
......@@ -131,11 +133,13 @@ Add the following to your pom.xml file, and you should be good to go. Check [her
<dependency>
<groupId>com.rajivprab</groupId>
<artifactId>cava</artifactId>
<version>1.2.0</version>
<version>1.4.0</version>
</dependency>
</dependencies>
```
About
=====
Cava was developed while building [Caucus](thecaucus.net). We realized that we had a number of utility functions and code patterns that we were manually implementing over and over again, in countless instances. These were all borne out of certain frustrations and limitations of the 3rd party libraries that we use. We initially just grumbled and put up with it, but soon decided that there's no reason why we couldn't abstract out these repeated code patterns into a library of our own. A library that aims to make Java cleaner and more elegant to program in. A library generic enough that anyone can use it, and simple enough that anyone can understand and maintain it. Thus was born Cava.
\ No newline at end of file
Cava was developed while building [Caucus](thecaucus.net). We realized that we had a number of utility functions and code patterns that we were manually implementing over and over again, in countless instances. These were all borne out of certain frustrations and limitations of the 3rd party libraries that we use.
We initially just grumbled and put up with it, but soon decided that there's no reason why we couldn't abstract out these repeated code patterns into a library of our own. A library that aims to make Java cleaner and more elegant to program in. A library generic enough that anyone can use it, and simple enough that anyone can understand and maintain it. Thus was born Cava.
\ No newline at end of file
......@@ -6,7 +6,7 @@
<groupId>com.rajivprab</groupId>
<artifactId>cava</artifactId>
<version>1.4.0</version>
<version>1.5.0</version>
<name>Cava: Clean Java</name>
<description>A library that enables users to write minimal, clean and simple Java code</description>
......@@ -62,6 +62,11 @@
<version>4.12</version>
<scope>test</scope>
</dependency>
<!-- TODO Major can of worms here. Use slf4j + log4j? Or Apache.commons.logging + log4j?
Maven central snippets recommends using test scope here, but what does that mean for other projects like caucus?
Does that mean that the log4j.properties will be applied only when running tests, and not in prod?
If test scope is applied below, will I need to manually copy-paste this dependency in all my other projects?
If I'm using apache.commons.logging (ie, LogFactory.getLog()), then why am I using this slf4j-log4j below? -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
......@@ -111,27 +116,9 @@
<artifactId>maven-surefire-plugin</artifactId>
<version>2.19.1</version>
<configuration>
<!-- TODO Enhancement: Really needed? Add to all projects-->
<enableAssertions>true</enableAssertions>
</configuration>
</plugin>
<!-- Run 'mvn package' to generate shade-jar, which will have any and all dependencies -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>2.4.3</version>
<configuration>
<!-- put your configurations here -->
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- Code coverage. Open browser and go to:
{proj}/target/site/jacoco-ut/index.html &&
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment