kotlin-whois-parser

A library for WHOIS response parsing.

Report Bug · Request Feature · Changelog

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Contributing
5. License
6. Contact

About The Project

kotlin-whois-parser is a library for requesting and parsing data from (primary) WHOIS servers into reusable models.

As of August 2022, the Wikipedia states 1,502 active top level domains, including 308 country-code top level domains. Due to the existence of hundreds of NICs with their wide range of different data output (some of them doesn't provide any information at all), it's hard for developers to gather useful and structured information from WHOIS.

Since there was no parser library for Java or Kotlin available as of Summer 2022 (at least we didn't find one), this project was started and gears towards all those use-cases one would like to get information from public WHOIS databases.

Therefor, this library makes use of the WhoisClient from org.apache.commons.net for the requests itself, and parses the output with Parsing expression grammars (via parboiled) afterwards (you may find all available parsers here).

(back to top)

Getting Started

Prerequisites

We choose to support the lowest actively supported Java version at the time of writing, that is, Java 11 (this may be subject to change in future major releases). There are no additional dependencies other than Kotlin and some plugins for publishing and documentation (Dokka).

Installation

There are several ways to install this library:

1. Apache Maven

   <dependency>
     <groupId>io.mailguru</groupId>
     <artifactId>whois-parser</artifactId>
     <version>1.0.3</version>
   </dependency>
   

2. Gradle Groovy DSL

   implementation 'io.mailguru:whois-parser:1.0.3'
   

3. Gradle Kotlin DSL

   implementation("io.mailguru:whois-parser:1.0.3")
   

4. Or you may clone the latest branch of your choice (presumably this will be develop ) of this repository and work on that clone itself or publish it to your local maven repository:

   git clone https://github.com/mlgr-io/kotlin-whois-parser.git
   cd kotlin-whois-parser
   ./gradlew publishToMavenLocal

   Then, in your target project, import the local lib by one of the methods (1. - 3.) above. Please make sure that the version you import matches the value given in your local build.gradle and you local maven repository:

   repositories {
        mavenLocal()
        // ...
   }

(back to top)

Usage

Gather information is pretty easy. Your entry point is the WhoisService singleton class (that is, object in Kotlin), that you use to make a call to the lookup() method with the hostname in question as its argument:

• in Kotlin:

  import io.mailguru.whois.service.WhoisService
  import io.mailguru.whois.model.WhoisResult
  
  // ...
  val result: WhoisResult = WhoisService.lookup("example.com")
  // ...
  

• in Java:

  import io.mailguru.whois.service.WhoisService;
  import io.mailguru.whois.model.WhoisResult;
  
  // ...
  WhoisResult result = WhoisService.INSTANCE.lookup("example.com");
  // ...

You will then, on a successful pass, have a WhoisResult object containing the parsed data. Please be aware that exceptions may be thrown by this method; see latest Javadoc or the code itself for details.

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

This library uses Conventional Commits.

(back to top)

License

Distributed under the GNU General Public License v3.0. See LICENSE.md for more information.

(back to top)

Contact

Project Link: https://github.com/mlgr-io/kotlin-whois-parser

(back to top)