Skip to content

Commit

Permalink
Merge pull request #122 from tail-f-systems/development
Browse files Browse the repository at this point in the history 
merge all revival development activities into master
  • Loading branch information
@jomiklos
jomiklos authored Dec 21, 2022
2 parents aae755b + 22ab667 commit 5e0dccc
Show file tree
Hide file tree
Showing 359 changed files with 7,817 additions and 68,165 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,4 @@ jnc/lib

**/.idea
**/*.iml
**/.gradle
70 changes: 70 additions & 0 deletions CHANGES.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
## Release History

Next version (SNAPSHOT)
- Ganymed SSH-2 was replaced with SSHJ.
- Build system updated to Gradle.
- cleaned Python PEP 8 lints for jnc.py
- reduced some Java lints (PMD tool, "java" quickstart.xml lint set)
- implemented NETCONF-1.1 framing
- cleaned up some deprecated examples
- updated root README.md

2012-10-17
- JNC is finally made open source! There are some changes remaining
before this will be publicly announced however.

2012-09-20
- Support for notifications added, and there is only one thing
remaining until it is possible to generate fully compliant junos.yang classes!

2012-08-29
- The GitHub repository is renamed to JNC and its readme is updated.

2012-08-28
- JPyang is renamed to JNC. So now there is both a JNC library and a
JNC pyang plugin.

2012-08-23
- Meeting at Tail-f about the future of the project. The marketing and
product management VP seems inclined to release as open source once the most
basic functionality has been tested and the documentation is complete.

2012-08-20
- The JPyang project repository is cleaned up, removing all non-comprehensible
files and adding a new README and ant build files.

2012-08-16
- JPyang is now fully object oriented, with method generator classes for all
relevant statements. This means that the generated classes should import all
JNC, java.util, java.math and generated classes that they use, and no other.

2012-08-03
- The INM and ConfM libraries are merged into the new JNC library, with better
support for YANG.

2012-07-27
- The ConfM.xs classes are replaced by new internal representations of the YANG
built in classes.

2012-07-16
- Unit tests for JPyang functions and class methods are added to pyang.

2012-07-13
- Work on a new structure for the JPyang code begins, using classes to represent
methods and organize functionality.

2012-07-06
- New tests for the INM and ConfM library classes are written.

2012-06-20
- Empty initial commit of the repository. It will contain the source code for
JPyang once it has been decided that it will be open source rather than
proprietary to tail-f. The plugin itself is just the single jpyang.py script.

2012-06-12
- JPyang is born as a few lines of python code that integrates with pyang are
written.

2012-06-04
- Emil starts working at Tail-f and reads up on the NETCONF RFC 6241 and YANG RFC
6020. You should too if you intend to contribute to this project!
246 changes: 64 additions & 182 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,228 +2,110 @@

Java NETCONF Client.

[![Build Status](https://travis-ci.org/btisystems/JNC.svg?branch=master)](https://travis-ci.org/btisystems/JNC)
## Overview

JNC (Java NETCONF Client) consists of two parts:

## Overivew
* Java library for NETCONF client (JNC library)
* pyang plugin for Java class hierarchies generation.

JNC (Java NETCONF Client) is the name of both a Java library for NETCONF client
code and a Java output format plugin for pyang, an extensible YANG validator
and converter in python. You need an installation of pyang to use the JNC
plugin. Get it here: http://code.google.com/p/pyang/
Together with the JNC library, these generated Java classes may be used as the foundation for a NETCONF client (AKA manager) written in Java.

The JNC plugin can be used to generate Java class hierarchies from YANG data
models. Together with the JNC library, these generated Java classes may be used
as the foundation for a NETCONF client (AKA manager) written in Java. The JNC
library is distributed along with the JNC plugin script.
JNC's Java library code uses [SSHJ](https://github.com/hierynomus/sshj) to communicate with NETCONF servers/agents.

JNC uses Ganymed SSH-2 to communicate with NETCONF servers/agents, you may get
it from here: http://www.cleondris.ch/opensource/ssh2/ or by using aptitude
(http://manpages.ubuntu.com/manpages/lucid/man8/aptitude.8.html):
sudo aptitude install libganymed-ssh2-java

This readme proposes two different ways of getting started. If you're running
Linux and don't want to use eclipse, feel free to skip the following section.
## Getting started

Typical use-case of JNC consists of three "standalone" areas - **Java library** for NETCONF clients, **pyang plugin** for YANG hierarchy class generation, and finally complete **Java application** connecting everything into combined client application.

## Get started using eclipse
### JNC Java library

Make sure you have pyang installed, and that jnc.py is in the plugins directory
of your installation. For instructions on how to use pyang, please see the
pyang man page.
JNC's Java library uses [Gradle](https://gradle.org/) as its build system.

[pyang](http://www.yang-central.org/twiki/pub/Main/YangTools/pyang.1.html)
If your `gradle` is outdated or is not installed at all, you can use Gradle Wrapper.
To use Gradle Wrapper you replace `gradle` command with `./gradlew` in the following steps/commands to be executed.
Wrapper automatically downloads & caches the correct Gradle version, and uses it to invoke Gradle commands.

Create an eclipse project for JNC: open the "New Java Project" dialog, uncheck
the "Use default location" checkbox and choose the jnc folder as the location
instead, then Finish.
You build the JNC Java library with following command:
```
gradle build
```
resp.
```
gradlew build
```
when using the wrapper...

Now you need to add ganymed ssh2 to the project. Right click on the project
folder in the Package Explorer, choose Build Path->Add External Archives and
select your ganymed ssh2 Jar file.
This will download dependencies (if needed), build JNC library, run tests and create corresponding JAR files (library, Javadoc and sources) in the `build/libs` directory.

If you don't want to run the tests, just delete the test source folder.
Otherwise, you need to add JUnit 4 to the build path. This may be done by
opening one of the test files, placing the marker on one of the lines which
have errors, pressing Ctrl+1, choosing "Fix project setup..." and then OK when
eclipse proposes to add the library. You should now be able to run the tests
by right clicking on the test source folder and selecting Run As -> JUnit test.
Alternative to building the JNC library locally is to utilize online Maven based repository.
See codebase of JNC `examples/` for details on the inclusion of Java lib for building your NETCONF client application.

The next step is to generate some Java classes using the JNC pyang plugin and
write a client that uses them together with the JNC library. Please see the
user manual for instructions on how to do this.

### Installing JNC Pyang plugin

## Get started in Linux (without eclipse):
The easiest way to use the pyang plugin is to install it into your environment
using `pip` (or `pip3`) like `pip install pyang-jnc`. This makes sure that
`pyang` is installed too and that `jnc` is registered as a Pyang plugin.

Add the JNC plugin to your existing pyang installation. This may be done in one
of the following three ways:
Another option is to use the plugin source that is part of this repository.
For that, you need an installation of *pyang* - get it
[here](https://github.com/mbj4668/pyang) or use `pip3 install pyang`. Then, add
the JNC plugin to your existing pyang installation. This may be done in one of
the following three ways:

1. Add jnc.py to pyang/plugins in your pyang installation,
2. Add the location of jnc.py to the $PYANG_PLUGINPATH environment variable, or
3. Use the --plugindir option of pyang each time you want to use JNC
1. Add jnc.py to `pyang/plugins` in your pyang installation directory,
2. Add the location of jnc.py to the `$PYANG_PLUGINPATH` environment variable, or
3. Use the `--plugindir` option of pyang each time you want to use JNC

If more than one of these approaches is used, you will end up with optparse
conflicts so please choose one and stick with it. From here on, we will assume
that you went for (1), but using (2) or (3) should be anologous.
**Note!**
If more than one of these approaches is used, you will end up with *optparse*
library conflicts, so please choose one and stick with it. From here on, we
will assume that you went for (1), but using (2) or (3) should be analogous.

JNC can be used to generate Java classes from a YANG file of your choice.
There are a collection of yang files in the 'examples/yang' directory. To
generate classes for a YANG file, open a terminal, change directory to where
you want the classes to be generated, launch pyang with the jnc format,
specifying the output folder and the yang model file.

For example, to generate the classes for simple.yang to the 'examples'
directory with base package gen.simple, type:
### Generating Java classes

$ pyang -f jnc --jnc-output src/gen/simple yang/simple.yang

There should now be a newly generated 'src' folder in the current directory,
containing a directory structure with the generated classes. Note that 'src' is
special treated so that it does not become part of the package names of the
generated classes.

To get more detailed information on how the generation proceeds the --jnc-debug
or --jnc-verbose options can be used. Rerunning JNC silently overwrites any old
classes in the output directory.

To actually use the generated classes, you need to compile Java client code
using the JNC library. It might be convenient to make a Jar file with the JNC
library for this purpose. There are several ways to do this:

1. Run the ant script located in the jnc directory: ant clean all
2. Manually: Open a terminal, change directory to jnc, compile the classes with
javac -d bin -sourcepath src src/com/tailf/jnc/*.java
Now change directory to bin and generate the Jar file with
jar cvf ../lib/JNC.jar *
3. Set up a project in eclipse and export the Jar (see previous section).

If the ant script fails to run, the most probable reason is that ganymed ssh2
is not installed in the expected way. Check that the ganymed.dir variable
points to the directory containing your ganymed ssh2 Jar file, and that the
classpath in the compile target corresponds to the correct build.

To run the JNC tests, see the previous section or run them with JUnit 4 from
commandline if you so prefer. The tests resides in the jnc/test folder.

Please see the user manual for tutorials and further information on how to
write a client and how to run it against a server using JNC.


## High level description

The different types of generated files are:

Root class -- This class has the name of the prefix of the YANG module, and
contains fields with the prefix and namespace as well as methods
that enables the JNC library to use the other generated classes
when interacting with a NETCONF server.

YangElement -- Each YangElement corresponds to a container or a list in the
YANG model. They represent tree nodes of a configuration and
provides methods to modify the configuration in accordance with
the YANG model that they were generated from.
The top-level containers or lists in the YANG model will have
their corresponding YangElement classes generated in the output
directory together with the root class. Their respective
subcontainers and sublists are generated in subpackages with
names corresponding to the name of the parent container or list.

YangTypes -- For each derived type in the YANG model, a class is generated to
the root of the output directory. The derived type may either
extend another derived type class, or the JNC type class
corresponding to a built-in YANG type.

Packageinfo -- For each package in the generated Java class hierarchy, a
package-info.java file is generated, which can be useful when
generating javadoc for the hierarchy.

Schema file -- If enabled, an XML file containing structured information about
the generated Java classes is generated. It contains tagpaths,
namespace, primitive-type and other useful meta-information.
JNC plugin can be used to generate Java classes from a YANG file of your choice.

The typical use case for these classes is as part of a JAVA network management
system (EMS), to enable retrieval and/or storing of configurations on NETCONF
agents/servers with specific capabilities.
There is a collection of yang files in the `examples/yang` directory.

To generate classes for a YANG file, open a terminal, change directory to where you want the classes to be generated, launch pyang with the `"jnc"` format, specifying the output folder and the yang model file.

## Release History
2012-06-04
For example, to generate the classes for `simple.yang` file included in our `examples` directory with base package name `gen.simple`, type:

Emil starts working at Tail-f and reads up on the NETCONF RFC 6241 and YANG RFC
6020. You should too if you intend to contribute to this project!

2012-06-12

JPyang is born as a few lines of python code that integrates with pyang are
written.

2012-06-20

Empty initial commit of the repository. It will contain the source code for
JPyang once it has been decided that it will be open source rather than
proprietary to tail-f. The plugin itself is just the single jpyang.py script.

2012-07-06

New tests for the INM and ConfM library classes are written.

2012-07-13

Work on a new structure for the JPyang code begins, using classes to represent
methods and organize functionality.

2012-07-16

Unit tests for JPyang functions and class methods are added to pyang.

1012-07-27

The ConfM.xs classes are replaced by new internal representations of the YANG
built in classes.

2012-08-03

The INM and ConfM libraries are merged into the new JNC library, with better
support for YANG.

2012-08-16
$ pyang -f jnc --jnc-output src/gen/simple yang/simple.yang

JPyang is now fully object oriented, with method generator classes for all
relevant statements. This means that the generated classes should import all
JNC, java.util, java.math and generated classes that they use, and no other.
There should now be a newly generated `"src"` folder in the current directory, containing a directory structure with the generated classes. Note that `"src"` is special treated so that it does not become part of the package names of the generated classes.

2012-08-20
To get more detailed information on how the generation proceeds the `--jnc-debug` or `--jnc-verbose` options can be used. Re-running JNC silently overwrites any old classes in the output directory.

The JPyang project repository is cleaned up, removing all non-comprehensible
files and adding a new README and ant build files.
### JNC Java application

2012-08-23
To actually use the generated classes, you need to compile Java client code with the JNC library (JAR file). The examples of JNC application can be found in the `examples` directory.

Meeting at Tail-f about the future of the project. The marketing and
product management VP seems inclined to release as open source once the most
basic functionality has been tested and the documentation is complete.
Gradle is used to build application. It also shows how to use JNC pyang plugin with Gradle task.

2012-08-28
See the example's `README` file for details.

JPyang is renamed to JNC. So now there is both a JNC library and a
JNC pyang plugin.

2012-08-29
## pyang generated files - high level description

The GitHub repository is renamed to JNC and its readme is updated.
There are different types of filed generated by pyang plugin:

2012-09-20

Support for notifications added, and there is only one thing
remaining until it is possible to generate fully compliant junos.yang classes!
| Class name | Description |
| --- | --- |
| Root class | This class has the name of the prefix of the YANG module, and contains fields with the prefix and namespace as well as methods that enables the JNC library to use the other generated classes when interacting with a NETCONF server.|
| YangElement | Each YangElement corresponds to a container or a list in the YANG model.<br/>They represent tree nodes of a configuration and provides methods to modify the configuration in accordance with the YANG model that they were generated from.<br/>The top-level containers or lists in the YANG model will have their corresponding YangElement classes generated in the output directory together with the root class.<br/>Their respective sub-containers and sub-lists are generated in sub-packages with names corresponding to the name of the parent container or list. |
| YangTypes | For each derived type in the YANG model, a class is generated to the root of the output directory. The derived type may either extend another derived type class, or the JNC type class corresponding to a built-in YANG type. |
| PackageInfo | For each package in the generated Java class hierarchy, a `package-info.java` file is generated, which can be useful when generating Javadoc for the hierarchy. |
| Schema file | If enabled, an XML file containing structured information about the generated Java classes is generated. It contains tag-paths, namespace, primitive-type and other useful meta-information. |

2012-10-17
The typical use case for these classes is as part of a JAVA network management system, to enable retrieval and/or storing of configurations on NETCONF agents/servers with specific capabilities.

JNC is finally made open source! There are some changes remaining
before this will be publicly announced however.

## License
Copyright 2012 Tail-f Systems AB
Copyright 2012-2022 Tail-f Systems AB

See [License File](LICENSE).
5 changes: 5 additions & 0 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
JNC Pyang plugin
================

Pyang plugin for generating Java classes for the JNC library. See the `JNC
GitHub page <https://github.com/tail-f-systems/JNC/>`__ for more details.
Loading

0 comments on commit 5e0dccc

Please sign in to comment.