Skip to content

Commit

Permalink
[Multiple issues]: Lots of 5.x rewrite work (#157)
Browse files Browse the repository at this point in the history
  • Loading branch information
isuPatches authored Dec 26, 2022
1 parent f1deae7 commit 5c2269f
Show file tree
Hide file tree
Showing 1,927 changed files with 35,214 additions and 22,433 deletions.
41 changes: 41 additions & 0 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
version: 2.1

orbs:
android: circleci/[email protected]

jobs:
static-analysis:
executor:
name: android/android-machine
steps:
- checkout
- run:
name: Run lint
command: ./gradlew lintDebug
- run:
name: Run Kotlinter
command: ./gradlew lintKotlin
- run:
name: Run detekt
command: ./gradlew detekt
- run:
name: Run CPD
command: ./gradlew cpdCheck

build:
executor:
name: android/android-machine
steps:
- checkout
- run:
name: Assemble debug build
command: ./gradlew assembleDebug
- run:
name: Assemble release build
command: ./gradlew assembleRelease

workflows:
ci:
jobs:
- static-analysis
- build
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -1 +1 @@
* @isuPatches
* @isuPatches
10 changes: 5 additions & 5 deletions .github/ISSUE_TEMPLATE/bug-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@ about: Create a report to help us improve

---

Thank you for creating an issue to improve this library! Please check Please check [the current issues](https://github.com/isuPatches/WiseFy/issues) to make sure that the improvement isn't already being worked on.
Thank you for creating an issue to improve this library! Please check Please check [the current issues](https://github.com/isuPatches/android-wisefy/issues) to make sure that the improvement isn't already being worked on.

It will be _EXTREMELY_ helpful if you also take a look at the [sample app](/wisefysample) to see how it behaves and if you can reproduce there.
It will be _EXTREMELY_ helpful if you also take a look at the [sample app](/app) to see how it behaves and if you can reproduce there.

**Description**
A clear and concise description of the bug.
Expand All @@ -19,8 +19,8 @@ If applicable, add screenshots to help explain.

**To Reproduce**
Steps to reproduce the behavior:
1. Create WiseFy instance
2. Call '...' method with '...' as params (please include if it's the synchronous or asynchronous API)
1. Create Wisefy instance
2. Call '...' method with '...' as params (please include if it's the synchronous, asynchronous, or ktx API)
3. Witness unexpected behavior

**Expected behavior**
Expand All @@ -38,4 +38,4 @@ A description of what actually happened
- Reproducible with sample app?:

**Logs**
Please include logs from WiseFy if at all possible. They can be found with `logging(true)` set on the WiseFy instance and by filtering on 'WiseFy'
Please include logs from Wisefy if at all possible. They can be found with `logging(true)` set on the Wisefy instance and by filtering on 'Wisefy'
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/feature-request.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ about: Suggest an idea for this project

---

Thank you for creating an issue to improve this library! Please check Please check [the current issues](https://github.com/isuPatches/WiseFy/issues) to make sure that the improvement isn't already being worked on.
Thank you for creating an issue to improve this library! Please check Please check [the current issues](https://github.com/isuPatches/android-wisefy/issues) to make sure that the improvement isn't already being worked on.

**Description**
A clear and concise high-level description of the request. (f.e. As a developer I want ___ so that ___)
Expand Down
44 changes: 44 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
I'd love to have your help, but please don't skimp on greatness!

Please check the [Issues](https://github.com/isupatches/android-wisefy/issues) and the [Main Board](https://github.com/isuPatches/android-wisefy/projects/1) to make sure what you want is not already being worked on.

* Please create an issue and use the [Main Board](https://github.com/isuPatches/android-wisefy/projects/1) to denote its status
- Please tag the issue with the appropriate labels as well (i.e. status, bug, TODO, etc.)
- Each issue should have clear details (i.e. steps to reproduce if it's a bug or acceptance criteria if a new feature)
* Please branch off develop to do any new work
- Branches should be prefixed with issue-#/ and a short description, example: issue-53/adding-some-feature
* Please make sure all static code analysis checks pass
* Please write tests
* Please make sure current tests pass
* Please help maintain the KDocs and write new ones
* Please help maintain the markdown docs (if necessary)
* Once satisfied with your work, please submit a Pull Request and I'll be happy to review it! All PRs need to be reviewed by a code owner.

For merging:

* PRs will be squashed and merged after a rebase
- The commit should have the issue-# in its message
- [Signed commits](https://docs.github.com/en/github/authenticating-to-github/managing-commit-signature-verification/signing-commits) are required
- The branch must be up-to-date before merging
- Conventional commits should be used to denote and differentiate between breaking changes, fixes, chores/tasks, and new features

Some architecture/code guidelines:
- Follow the patterns and naming conventions present to ensure consistency
- The query class is prefixed with function name (f.e. the function `getCurrentNetwork` uses the query class `GetCurrentNetworkQuery`)
- The request class is prefixed with function name (f.e. the function `addNetwork` uses the request class `AddNetworkRequest`)
- The result class is prefixed with function name (f.e. the function `removeNetwork` uses the result class `RemoveNetworkResult`)
- The `ktx` extension functions have the suffix `Async` (f.e. the extension for `getNetworkConnectionStatus` is `getNetworkConnectionStatusAsync`)
- Keep in-mind the folder and organization structure defined in the [README.md](/README.md)
- Synchronous, async, and ktx options are supported for each feature (unless there is an exceptional case)
- Adapters are the only expected location for assertions
- For `ktx` extension functions, the library deliberately catches any exception and throws a [WisefyException](/wisefy/core/src/main/java/com/isupatches/android/wisefy/core/exceptions/WisefyException.kt)
- Async operations use coroutines internally and:
- Execute on the background thread
- Return results to the main thread
- Are locked with a mutex if there are potential conflicts with out async functions (f.e. enableWifi, disableWifi, and isWifiEnabled)

For releasing:

- The CHANGELOG.md will be generated once per release
- The release task will be run to regenerate all of the KDocs
- The version codes and version names will be bumped in a release PR
2 changes: 1 addition & 1 deletion LICENSE.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,7 @@
same "printed page" as the copyright notice for easier
identification within third-party archives.

Copyright 2017 Patches Klinefelter
Copyright 2022 Patches Barrett

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
Expand Down
173 changes: 155 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,57 +1,194 @@
## Wisefy

<img src="Banner.png" width="40%" height="40%" />

A Wifi configuration and util library built in Kotlin for Android.

> Developed by Patches 04/24/2016 - present
> Logo/icon created by mansya (2018)
>
> Supports Android SDK levels 23-33
[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-WiseFy-brightgreen.svg?style=flat)](https://android-arsenal.com/details/1/6011) [![Android Weekly](https://img.shields.io/badge/Android%20Weekly-%23230-blue.svg)](http://androidweekly.net/issues/issue-230)

- [Installation](#installation)
- [KTX Artifact](#ktx-artifact)
- [5.0 Rewrite](#50-rewrite)
- [Highlights](#highlights)
- [New Structure](#new-structure)
- [Packaging & Naming Conventions](#packaging-and-naming-conventions)
- [Deprecations](#deprecations)
- [Known Android Q Problems](#known-android-q-problems)
- [Documentation](#documentation)
- [Reset](#reset)
- [Links](#links)
- [FAQ](#faq)
- [For Contributors](#for-contributors)
- [License](#license)

## Installation

There is a new package for 5.0. Please use:

```kotlin
implementation("com.isupatches.android:wisefy:5.0.0-RC2")
implementation("com.isupatches.android:wisefy:5.0.0-RC3")
```

This will include all of the Wisefy sub-artifacts through `api` dependencies.

There are also new more modular artifacts published so that individual pieces of Wisefy can be imported directly:

> `com.isupatches.android.wisefy:core:<LATEST VERSION>` will be a requirement for the other Wisefy artifacts.
- `com.isupatches.android.wisefy:accesspoints:<LATEST VERSION>`
- `com.isupatches.android.wisefy:addnetwork:<LATEST VERSION>`
- `com.isupatches.android.wisefy:core:<LATEST VERSION>`
- `com.isupatches.android.wisefy:networkconnection:<LATEST VERSION>`
- `com.isupatches.android.wisefy:networkinfo:<LATEST VERSION>`
- `com.isupatches.android.wisefy:removenetwork:<LATEST VERSION>`
- `com.isupatches.android.wisefy:savednetworks:<LATEST VERSION>`
- `com.isupatches.android.wisefy:signal:<LATEST VERSION>`
- `com.isupatches.android.wisefy:wifi:<LATEST VERSION>`

Here are the descriptions of what functionality each artifact provides:

- `:accesspoints` For getting and searching for nearby networks
- `:addnetwork` For adding a Wifi network
- `:core` For base Wisefy functionality
- `:networkconnection` For connecting and disconnecting from networks
- `:networkinfo` For information about the device's current network and current connectivity status
- `:removenetwork` For removing a Wifi network
- `:savednetworks` For getting and searching for saved networks
- `:signal` For calculating a signal level and comparing signal levels
- `:wifi` For enabling and disabling Wifi

## KTX Artifact

There is a new artifact for 5.0 that provides Kotlin extension functions. Please use:

```kotlin
implementation("com.isupatches.android:wisefy-ktx:<LATEST VERSION>")
```

if you want to try it out. All functions in this package have the suffix `Async` and are `suspend` functions.

## 5.0 Rewrite

The 5.0 version of WiseFy works to rectify the problems that caused it to be overly challenging as a single developer
to keep up with the ever-changing Wifi APIs for new Android OS's, especially with a lot of functionality becoming
privatized.
to keep up with the ever-changing Wifi APIs for new Android operating systems, especially with a lot of functionality
becoming privatized. It also strives to simplify the API and removes redundancy within the APIs that caused additional
overhead for maintenance.

I hope you enjoy the rewrite and please create an issue if you see anything odd or have questions!

### Highlights

- Android P, Android Q, and Android R are now supported
- Android Q, Android R, Android S, and Android T are now supported
- Compiled with Java 11
- Rewritten with extensibility and future Android OS's in-mind
* Future versions of the Android OS will be easier to support with the new delegate system
* Future versions of the Android OS will be easier to support with the new delegate/adapter system
* Improved modularity where APIs for OS versions are contained in their own API / API implementation files
- Async operations updated to internally leverage Coroutines and new exception handler
- Returns are now WiseFy classes or primitives opposed to a class from the OS, making it easier to add new variants
in the future through sealed classes
- Async operations updated to internally leverage Coroutines and a new exception handler
- Returns are now Wisefy classes opposed to a class from the OS, making it easier to add new variants in the future
through sealed classes
- Updated names for callbacks
- Kotlin first mentality (but willing to support Java as first class too!)
- WPA3 networks now supported
- wisefysample renamed to app
- WPA3 networks are now supported
- `wisefysample` renamed to `app`
- BSSID support is now added
- More modular artifacts are available now
- Less bloat if there are things you're not going to use
- Able to iterate and update portions of the library without the overhead of the entire project
- `gradle.lockfile`s and Gradle ranges are enabled for more control over versioning
- [Locking dependency versions](https://docs.gradle.org/current/userguide/dependency_locking.html)
- [Declaring Versions and Ranges](https://docs.gradle.org/current/userguide/single_versions.html)
- Sample app re-written
- Down with SharedPreferences, onward to DataStore
- Written in Compose complete with previews
- Niceties like progress bars added
- Better input validation

### Work Remaining Before Official Release
### New Structure

- Documentation added
- Unit and instrumentation tests added back
- Wisefy public API -> Wisefy implementation -> Delegate to determine which adapter to use ->
Adapter converts request for usage by the Android OS -> Android OS APIs are used and the adapter returns information
as a Wisefy result

### New Structure
### Packaging and Naming Conventions

Types of classes:

- `Query` - Indicates a read only operation where nothing is modified or written
- `Request` - Indicates an action where some state is modified or a value is written
- `Result` - Indicates the return from an action or query
- `Data` - Indicates a complex return for a result that includes several different properties, fields, and functions

- WiseFy API -> WiseFy -> Internal util -> Delegate -> OS API and OS API implementation
Types of property values:

- `value` - A field within a `Result` object for a `Data` class (a Wisefy based class)
- `rawValue` - A field for a OS level class or object (not a Wisefy based class) within a `Data` object

Suffixes:

- Api (top-level of a feature package) -> Contains the definitions of synchronous APIs available for the feature
- ApiAsync (top-level of a feature package) -> Contains the definitions of asynchronous APIs available for the feature
- Delegate -> Determines which adapter to use based on the Android device's SDK level
- Adapter -> Middleware that converts requests and responses between the API and Delegate layers
- Api (within os package context) -> Houses the definitions of Android OS level APIs that Adapter classes may use
- ApiImpl (within os package context) -> Houses the implementation for executing Android OS level APIs

Package structure for each section is as follows:

- Feature (accesspoints, addnetwork, etc.) -> Location of Wisefy Specific delegate -> supporting sub-directories

*Supporting sub-directories can include*

- callbacks (public) -> Location of callback interfaces for returns from async calls
- entities (public) -> Location of data classes for queries, requests, responses, and data
- os (internal) - Purely on organizational directory
- adapters (internal) -> Location of the classes that convert requests and responses between the Delegate and Android
OS level APIs
- converters (internal) -> Location of helpers to convert one data class to another
- apis (internal) -> Location of the API interfaces to talk to the Android OS
- impls (internal) -> Location of the implementation for an API that talks to the Android OS

### Deprecations

- disableWifi() and disableWifi(callbacks: DisableWifiCallbacks?)
- disconnectFromCurrentNetwork() and disconnectFromCurrentNetwork(callbacks: DisconnectFromCurrentNetworkCallbacks?)
- enableWifi() and enableWifi(callbacks: EnableWifiCallbacks?)
- calculateBars(rssiLevel: Int, targetNumberOfBars: Int)

### Known Android Q Problems

- Saving a network doesn't seem possible. A notification is presented if not connected to the suggestion, but even the
appearance of the notification seems flakey
- Adding, removing, and getting saved network functionality is not present.
Android Q / SDK 29 was in a weird half-baked state between the old WifiManager APIs and the new WifiSuggestion APIs...Android 30 seems to have full support, but Android 29 really drops the ball for saved network functionality.

## Documentation

### Reset

To keep the documentation clean and because of the amount of architectural changes for the 5.x release, the
documentation was stripped and then completely re-written.

## Links

For auto-generated [Dokka](https://kotlin.github.io/dokka) markdown files based on the KDocs please see
[here](/dokka/index.md).

For more high-level examples based on different functionality please see [here](/documentation/index.md).

## FAQ

You may find a list of frequently asked questions [here](/documentation/FAQ.md).

## For Contributors

Want to help? Have an idea for a cool feature or want to fix a bug for the community? See
[CONTRIBUTING](CONTRIBUTING.md) for how you can make impactful changes for Wisefy.

## License ##
Copyright 2021 Patches Klinefelter
Copyright 2022 Patches Barrett

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
compliance with the License. You may obtain a copy of the License at
Expand Down
Loading

0 comments on commit 5c2269f

Please sign in to comment.