Merge pull request #2 from ankushs92/dev

Dev

Author: ankushs92

README.md

@@ -1 +1,62 @@
-Java wrapper for the DB-IP dataset
+# Java DB-IP
+A simple to use Java library for the freely available DB-IP [IP address to city dataset](https://db-ip.com/db/download/city).
+**Requires Java 8**
+
+#Before you begin
+The entire dataset is loaded into a [TreeMap](https://docs.oracle.com/javase/8/docs/api/allclasses-noframe.html) . Make sure that you have about **3 GB of Heap space** available to load it.
+
+#Get 
+
+With maven :
+
+```xml
+
+<dependency>
+	  <groupId>in.ankushs</groupId>
+	  <artifactId>Java-DB-IP</artifactId>
+	  <version>1.0</version>
+</dependency>
+```
+
+Or gradle:
+
+```groovy
+
+compile('in.ankushs:Java-DB-IP:1.0')
+
+```
+
+The Javadocs for the latest release can be found [here](http://www.javadoc.io/doc/in.ankushs/Java-DB-IP/1.0)
+
+
+#Instructions
+In order to get geographical information for an ip address, just pass the `dbip-city-latest.csv.gz` as a File object to `DbIpClient` as follows:
+
+```java
+File gzip = new File(PATH_TO_dbip-city-latest.csv.gz);
+DbIpClient client = new DbIpClient(gzip);
+```
+
+Once the data is loaded from the file into memory , any subsequent invocation of the above code **would not** re-load the data . 
+
+Next,just fetch the data for a ip ,like so :
+
+```java
+DbIpClient client = new DbIpClient(gzip);
+GeoEntity geoEntity = client.lookup("31.45.127.255");
+String city = geoEntity.getCity();
+String country = geoEntity.getCountry();
+String province = geoEntity.getProvince();
+
+System.out.println("city : " + city);
+System.out.println("province : " + province);
+System.out.println("country : " + country);
+```
+
+This prints : 
+```
+city : Oslo
+province : Oslo
+country : Norway
+```
+That's pretty much it.

build.gradle

@@ -1,12 +1,17 @@
 apply plugin: 'groovy'
 apply plugin: 'eclipse'
 apply plugin : 'idea'
- 
+apply plugin: 'maven'
+apply plugin: 'signing'
+
+
 sourceCompatibility = 1.8
+group ="in.ankushs"
+archivesBaseName = "dbip"
 version = '1.0'
 
 jar {
-    baseName = "Java DbIp"
+    baseName = "Java-DB-IP"
     manifest {
         attributes 'Implementation-Title': 'Gradle Quickstart',
                    'Implementation-Version': version
@@ -26,13 +31,13 @@ dependencies {
   testCompile('org.codehaus.groovy:groovy-all:2.4.5')
 }
 
-sourceSets {
-	main {
-	  java { srcDirs = ["src/main/java"] }    // no source dirs for the java compiler
-	  groovy { srcDirs = ["src/test/groovy"] }  // compile everything in src/ with groovy
-	 }
-  }
- 
+//sourceSets {
+//	main {
+//	  java { srcDirs = ["src/main/java"] }    // no source dirs for the java compiler
+//	  groovy { srcDirs = ["src/test/groovy"] }  // compile everything in src/ with groovy
+//	 }
+//  }
+// 
 test {
     systemProperties 'property': 'value'
 }
@@ -44,11 +49,73 @@ eclipse {
   }
 }
 
+
+task javadocJar(type: Jar) {
+	classifier = 'javadoc'
+	from javadoc
+}
+
+task sourcesJar(type: Jar) {
+	classifier = 'sources'
+	from sourceSets.main.allSource
+}
+
+artifacts {
+	archives javadocJar, sourcesJar
+}
+
+signing {
+	sign configurations.archives
+}
+
 
 uploadArchives {
     repositories {
-       flatDir {
-           dirs 'repos'
-       }
+	   mavenDeployer{
+		   beforeDeployment{MavenDeployment deployment->
+			   signing.signPom(deployment)
+		   }
+	    
+		   repository(url: "https://oss.sonatype.org/service/local/staging/deploy/maven2") {
+			   authentication(userName: ossrhUsername, password: ossrhPassword)
+			 }
+	   	   
+		   pom{
+			   project{
+				   name 'Java DbIP'
+				   description 'A Java library for the DB-IP IP address to city dataset '
+				   packaging 'jar'
+				   url 'https://github.com/ankushs92/Java-DB-IP'
+			       inceptionYear '2016'
+				   
+				   scm {
+					   connection 'scm:git:git@github.com:ankushs92/Java-DB-IP.git'
+					   developerConnection 'scm:git:git@github.com:ankushs92/Java-DB-IP.git'
+					   url 'git@github.com:ankushs92/Java-DB-IP.git'
+					 }
+				   
+				   licenses {
+					   license {
+						 name 'The MIT License'
+						 url 'https://github.com/ankushs92/Java-DB-IP/blob/master/LICENSE.md'
+					   }
+				   }
+				   developers {
+					   developer {
+						 name 'Ankush Sharma'
+						 email 'ankush20058@gmail.com'
+					   }
+					}
+				   issueManagement{
+					   system 'Github'
+					   url 'https://github.com/ankushs92/Java-DB-IP/issues'
+					   
+				   }
+			   }
+		   }
+	       flatDir {
+	           dirs 'repos'
+	   }
     }
+  }
 }

gradle.properties

@@ -2,53 +2,90 @@
 
 import java.io.File;
 import java.net.InetAddress;
+import java.util.concurrent.Executor;
+import java.util.concurrent.Executors;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import com.google.common.net.InetAddresses;
 
+import in.ankushs.dbip.exceptions.InvalidIPException;
 import in.ankushs.dbip.importer.ResourceImporter;
 import in.ankushs.dbip.lookup.GeoEntityLookupService;
 import in.ankushs.dbip.lookup.GeoEntityLookupServiceImpl;
 import in.ankushs.dbip.utils.PreConditions;
-
+/**
+ * 
+ * Class responsible for loading data into the JVM and also an API for resolving ip.
+ * @author Ankush Sharma
+ */
 public final class DbIpClient {
 
 	private static final Logger logger = LoggerFactory.getLogger(DbIpClient.class);
-	
+
+	/*
+	 * The dbip-city-latest.csv.gz file 
+	 * */
 	private final File file ;
-	private final GeoEntityLookupService lookupService = new GeoEntityLookupServiceImpl();
+	//Singleton
+	private final GeoEntityLookupService lookupService = GeoEntityLookupServiceImpl.getInstance();
 
+	/*
+	 * Indicates whether the file has been loaded into the JVM.
+	 * */
 	private static boolean flag = false;
 
-	public DbIpClient(final File csvFile){
-		PreConditions.checkExpression(!csvFile.exists(), "file " + csvFile.getName() + " does not exist");
-		this.file = csvFile;
+	
+	/**
+	 * Create a new DbIpClient . 
+	 * Once an instance has been created, the allLoaded flag is set to true.
+	 * Any futher initializations of the DbIpClient  will not load data into memory again.
+	 * @param gzip The dbip-city-latest.csv.gz file as a File object.
+	 * @throws IllegalArgumentException if {@code gzip} does not exist.
+	 */
+	public DbIpClient(final File gzip){
+		PreConditions.checkExpression(!gzip.exists(), "file " + gzip.getName() + " does not exist");
+		this.file = gzip;
 		if(!flag){
 			flag = true;
 			logger.info("Loading db ip into repository ");
-			new ResourceImporter().load(csvFile);
+			ResourceImporter.getInstance().load(gzip);
 			logger.info("Loading finished");
 		}
 		else{
 			logger.info(" DbIp csv file has already been loaded ");
-
 		}
 	}
-
+	
+	
+	/**
+	 * Returns a loaded GeoEntity object for a given {@code ip}
+	 * If nothing can be resolved for an {@code ip} , then the city,state and country 
+	 * for the GeoEntity will be set to 'Unknown'
+	 * Any futher initializations of the DbIpClient  will not load data into memory again.
+	 * @param ip The ip (as String) to be resolved.
+	 * @return a GeoEntity object representing city,state and province info
+	 */
 	public GeoEntity lookup(final String ip){
 		InetAddress inetAddress = null;
 		try{
 			inetAddress = InetAddresses.forString(ip);
 		}
 		catch(final IllegalArgumentException ex){
-			logger.error("",ex);
-			throw ex;
+			logger.error("Invalid IP given",ex);
+			throw new InvalidIPException("Invalid IP passed");
 		}
 		return lookup(inetAddress);
 	}
 
+	/**
+	 * Returns a loaded GeoEntity object for a given {@code inetAddress}
+	 * If nothing can be resolved for an {@code inetAddress} , then the city,state and country 
+	 * for the GeoEntity will be set to 'Unknown'
+	 * @param inetAddress The inetAddress (as InetAddress) to be resolved.
+	 * @return a GeoEntity object representing city,state and province info
+	 */
 	public GeoEntity lookup(final InetAddress inetAddress){
 		PreConditions.checkNull(inetAddress, "inetAddress cannot be null");
 		return lookupService.lookup(inetAddress);

src/main/java/in/ankushs/dbip/api/DbIpClient.java

@@ -1,22 +1,26 @@
 package in.ankushs.dbip.api;
 
 import in.ankushs.dbip.utils.PreConditions;
-
+/**
+ * 
+ *
+ * @author Ankush Sharma
+ */
 public final class GeoEntity {
 	private final String city;
 	private final String country;
-	private final String state;
+	private final String province;
 
 	public GeoEntity(final Builder builder){
 		this.city = builder.city;
 		this.country = builder.country;
-		this.state = builder.state;
+		this.province = builder.province;
 	}
 
 	public static class Builder{
 		private String city;
 		private String country;
-		private String state;
+		private String province;
 
 		public Builder withCity(final String city ){
 			this.city = city;
@@ -28,8 +32,8 @@ public Builder withCountry(final String country ){
 			return this;
 		}
 
-		public Builder withState(final String state ){
-			this.state = state;
+		public Builder withProvince(final String province ){
+			this.province = province;
 			return this;
 		}
 
@@ -46,13 +50,13 @@ public String getCountry() {
 		return country;
 	}
 
-	public String getState() {
-		return state;
+	public String getProvince() {
+		return province;
 	}
 
 	@Override
 	public String toString() {
-		return "GeoEntity [city=" + city + ", country=" + country + ", state=" + state + "]";
+		return "GeoEntity [city=" + city + ", country=" + country + ", province=" + province + "]";
 	}